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 實現。