smaramwbc/statewave

Statewave – 为 AI 代理提供确定性且具有完整溯源的内存

是什么 – Statewave 是一个开源运行时，位于您的 LLM 驱动的应用程序旁边，为其提供持久化、结构化的记忆。它记录原始的 事件（例如聊天消息、Git 事件、Slack 帖子），将它们编译为带有置信度分数和溯源信息的类型化 记忆，然后提供 上下文包，这些包具有令牌限制、排序，并且 确定性（在相同时间点执行相同查询总是返回相同的字节）。

为何重要 – 大多数 LLM 驱动的机器人都是 无状态 的：每次请求都从空白提示开始，因此会忘记偏好、过去的决策或用户历史。Statewave 通过以下方式解决此问题：

• 持久化 事件到 PostgreSQL（使用 pgvector 扩展进行嵌入）。
• 仅在主题变更时编译一次，消除嘈杂的实时检索。
• 提供溯源，使每个上下文片段都能追溯到其原始事件。
• 仅在 CPU 上运行（LLM 或嵌入调用为可选），使其托管成本低廉。

核心概念

概念	作用
事件	仅追加的原始事件（例如聊天消息、Git PR）。
记忆	由 编译器（基于正则表达式的启发式方法或通过 LiteLLM 的 LLM）生成的类型化摘要。
上下文包	按令牌预算修剪并排序的记忆列表，可直接插入提示中。
主题	记忆所属的逻辑实体 – 用户、仓库、账户等。
收据	不可变的、ULID 可寻址的记录，记录了哪些记忆组成了一个包，并使用 HMAC-SHA256 签名。
策略引擎	应用于记忆标签（pii、financial 等）的 YAML 规则（deny、redact、log_only）。

如何使用

from statewave import StatewaveClient

with StatewaveClient("http://localhost:8100") as sw:
    # 1️⃣ 注入原始事件
    sw.create_episode(
        subject_id="user-42",
        source="chat",
        type="message",
        payload={"text": "Alice asked about pricing tiers"},
    )
    # 2️⃣ 为该主题编译记忆（幂等）
    sw.compile_memories("user-42")
    # 3️⃣ 获取任务的确定性上下文包
    bundle = sw.get_context(
        "user-42", task="answer pricing", max_tokens=1000
    )
    print(bundle.assembled_context)

该循环为 注入 → 编译 → 获取。服务器可通过单个 Docker 命令或提供的 npx @statewavedev/statewave 安装程序启动。

主要特性

• 确定性编译包 – 无查询时检索带来的采样噪声。
• 溯源与收据 – 每个令牌均可追溯到其原始事件；收据已签名且可重放。
• 可插拔编译器 – 简单的正则表达式启发式方法 或 任何由 LiteLLM 支持的 LLM（OpenAI、Anthropic、Azure、Ollama 等）。
• 敏感性标记与策略引擎 – 通过声明式 YAML 规则，对标记为 PII、密钥等的记忆执行拒绝、脱敏或仅记录操作。
• 多租户隔离 – X-Tenant-ID 头部限定数据范围；可选区域绑定强制数据驻留。
• 基于 PostgreSQL + pgvector 的自托管 – 无供应商锁定，可在任何云或本地基础设施上运行。
• SDK – Python（statewave-py）和 TypeScript（statewave-ts）客户端，以及 REST OpenAPI 规范。
• 连接器生态系统 – 独立包（GitHub、Slack、Gmail、Notion 等）将现实世界事件推送到 Statewave 作为事件。

典型用例

• 记住用户过往工单和偏好的客户支持机器人。
• 跨会话保留项目决策的长期编码助手。
• 对比无状态 LLM 与带记忆增强上下文的相同 LLM 的 A/B 测试。
• 需要可审计、令牌级可追溯性的企业代理，以满足合规要求。

快速入门

1. 安装服务器（Docker Compose 或单行安装程序）。
2. 设置最小 .env 文件 – 至少包含 STATEWAVE_DATABASE_URL。
3. 可选地通过提供 STATEWAVE_LITELLM_API_KEY 和模型 ID 启用 LLM 编译器。
4. 使用 Python 或 TypeScript SDK 注入事件并请求上下文。

了解更多

• 完整文档： https://github.com/smaramwbc/statewave-docs
• API 参考： http://localhost:8100/docs
• 示例项目： https://github.com/smaramwbc/statewave-examples
• 连接器仓库： https://github.com/smaramwbc/statewave-connectors

---

TL;DR – Statewave 是一个自托管、基于 PostgreSQL 的 LLM 代理内存层，提供确定性、溯源丰富的上下文、策略驱动的标记和多租户隔离，全部通过简单的 REST API 和语言特定 SDK 实现。