Statewave 智能体内存运行时

这个 Agent 能做什么，适合哪些场景？

Statewave 是一个自托管的开源内存运行时，用 Postgres + pgvector 存放数据，核心思路是“编译一次、按需取用”，而不是每次查询都做相似度检索。它按主体（subject，如 user:、repo:、account:）记录 append-only 的 episode，再通过启发式或 LLM 编译器抽取带置信度与来源的记忆，最后按任务和 token 预算组装排序好的上下文包。每个上下文包都携带 state-assembly receipt，可追溯到源 episode，并支持 HMAC-SHA256 签名与 POST /v1/receipts/{id}/replay 重放。服务端以 Docker Compose、Helm 或裸机方式部署在 8100 端口，对外提供 REST API，配套 Python（pip install statewave）与 TypeScript（npm install @statewavedev/sdk）SDK。默认演示模式使用 stub 嵌入和启发式编译器，完全本地运行无需 GPU；要获得语义检索和更强的记忆抽取，需配置 LiteLLM 的模型与嵌入提供方。

运行时围绕主体组织数据，端到端流程是 ingest → compile → use。写入侧通过 POST /v1/episodes 或 POST /v1/episodes/batch（单次最多 100 条）追加原始事件；编译侧调用 POST /v1/memories/compile，将 episode 抽取为带类型、摘要、置信度和来源的记忆，且幂等不产生重复。取用侧由 POST /v1/context 组装按 task 排序、受 max_tokens 限制的上下文包，同一主体在同一时间点用同一任务查询会得到完全相同的字节。治理能力包括 GET /v1/timeline 查看主体时间线、GET /v1/subjects 列出主体、DELETE /v1/subjects/{id} 按主体彻底删除数据，以及 POST /v1/handoff 生成交接包、GET /v1/subjects/{id}/health 计算可解释的客户健康分、GET /v1/subjects/{id}/sla 输出响应与解决时长和违约情况。检索接口 GET /v1/memories/search 可按类型、文本或语义相似度查找；POST /v1/resolutions 跟踪会话内的问题解决状态。合规相关能力包括 YAML 策略引擎（deny/redact，作用于 pii、financial、secret 等标签）、v0.9 的启发式 auto-labeling 建议标签与人工提升、多租户 X-Tenant-ID 隔离，以及按租户的区域钉选（区域不匹配返回 403 residency.mismatch）。

1. 客服团队：让回访客户在不同会话中被识别，用 token 预算内排序好的上下文回答，升级时用 POST /v1/handoff 生成交接包并追溯每条记忆的来源。
2. 长期编码智能体：把技术栈、偏好和架构决策写入 repo: 主体的 episode，跨多次会话持久保留项目记忆。
3. 平台工程团队：在自有 Postgres 上自托管内存服务，通过 REST API 接入任意语言或框架的智能体，避免数据离开自有网络。
4. 合规与风控场景：用 YAML 策略对 pii、financial、secret 标签执行 deny/redact，并用签名 receipt 审计每次上下文组装由哪些记忆影响。
5. 数据驻留要求明确的组织：把租户钉选到指定区域，跨区域进程直接拒绝请求，满足本地化合规。
6. 多来源记忆建设：通过 @statewavedev/connectors-* 把 GitHub、Slack、Notion、Zendesk、Gmail 等来源的事件同步为 episode，先 dry-run 确认再写入。

如何安装或部署这个 Agent？

最快方式是官方安装脚本或 npx，也可自行用 Docker Compose 起服务。

# macOS / Linux
npx @statewavedev/statewave
# 或
curl -fsSL https://www.statewave.ai/install | sh

# Windows (PowerShell)
irm https://www.statewave.ai/install.ps1 | iex

自行部署：

git clone https://github.com/smaramwbc/statewave && cd statewave
docker compose up -d

该命令会启动 Postgres（含 pgvector）与 API，迁移在容器启动时自动执行，服务监听 http://localhost:8100。默认是演示模式（stub 嵌入 + 启发式编译器）。要启用 LLM 行为，在 docker-compose.yml 同级放置 .env 后重新执行 docker compose up -d：

STATEWAVE_EMBEDDING_PROVIDER=litellm
STATEWAVE_LITELLM_API_KEY=sk-...            # 任意 LiteLLM 提供方
STATEWAVE_LITELLM_MODEL=gpt-4o-mini
STATEWAVE_LITELLM_EMBEDDING_MODEL=text-embedding-3-small

依赖：PostgreSQL 14+ 与 pgvector ≥ 0.4.2；SDK 需要 Python 3.11+ 或 Node.js。

如何使用这个 Agent？

先确认服务健康，再用 SDK 或 HTTP 完成一次 ingest → compile → use 循环。

curl http://localhost:8100/readyz
curl http://localhost:8100/healthz

from statewave import StatewaveClient

with StatewaveClient("http://localhost:8100") as sw:
    sw.create_episode(subject_id="user-42", source="chat", type="message",
                      payload={"text": "Alice asked about pricing tiers"})
    sw.compile_memories("user-42")
    print(sw.get_context("user-42", task="answer pricing", max_tokens=1000).assembled_context)

接口文档在 http://localhost:8100/docs（Swagger）与 /redoc；常用端点包括 POST /v1/episodes、POST /v1/memories/compile、POST /v1/context、GET /v1/timeline、GET /v1/subjects 与 DELETE /v1/subjects/{id}。连接器示例（默认 dry-run，不会写入）：

statewave-connectors sync github \
  --repo smaramwbc/statewave \
  --subject repo:smaramwbc/statewave \
  --dry-run

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

常见问题