smaramwbc/statewave

Statewave – AIエージェント向けの決定論的で証跡豊富なメモリ

何であるか – Statewaveは、LLM駆動アプリケーションの隣に配置されるオープンソースのランタイムで、耐久的で構造化されたメモリを提供します。Rawなエピソード（例：チャットメッセージ、Gitイベント、Slack投稿）を記録し、タイプ付きのメモリにコンパイル（ヒューリスティックまたはLLMコンパイラ経由）、その後、トークン制限付きで、ランク付けされ、決定論的（同じ時刻に同じクエリを実行すると常に同じバイト列を返す）なコンテキストバンドルを提供します。PostgreSQL + pgvectorを基盤としており、ポリシー駆動のラベル付け、マルチテナント隔離、PythonおよびTypeScript用SDKを提供しています。

なぜ重要か – 多くのLLM駆動ボットは状態なしです：各リクエストは空のプロンプトから始まるため、好み、過去の意思決定、ユーザー履歴を忘れてしまいます。Statewaveは以下の点でこれを解決します。

• PostgreSQL（pgvector拡張機能による埋め込み）にイベントを永続化。
• 主題の変更ごとに一度だけコンパイルすることで、ノイズの多いリアルタイム取得を排除。
• 証跡を提供し、コンテキストの各部分が元のエピソードに追跡可能。
• CPUのみで動作（LLMまたは埋め込み呼び出しはオプション）、ホスティングコストが低く抑えられます。

コアコンセプト

コンセプト	役割
エピソード	追加のみ可能なRawイベント（例：チャットメッセージ、Git PR）。
メモリ	コンパイラ（ヒューリスティックな正規表現またはLiteLLM経由のLLM）によって生成されるタイプ付き要約。
コンテキストバンドル	トークン予算に合わせてトリムされたランク付けされたメモリのリスト。プロンプトに挿入可能。
主題	メモリが属する論理的エンティティ – ユーザー、リポジトリ、アカウントなど。
レシート	変更不可能なULIDアドレス付き記録。どのメモリがバンドルに含まれたかを記録し、HMAC-SHA256で署名。
ポリシーエンジン	YAMLルール（deny、redact、log_only）をメモリタグ（pii、financialなど）に適用。

使い方

from statewave import StatewaveClient

with StatewaveClient("http://localhost:8100") as sw:
    # 1️⃣ Rawイベントをインジェスト
    sw.create_episode(
        subject_id="user-42",
        source="chat",
        type="message",
        payload={"text": "Alice asked about pricing tiers"},
    )
    # 2️⃣ その主題のメモリをコンパイル（idempotent）
    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など）。
• 機密性ラベル付けとポリシーエンジン – PII、シークレットなどにタグ付けされたメモリに対して、deny、redact、log_onlyを宣言的に制御するYAMLルール。
• マルチテナント隔離 – X-Tenant-IDヘッダーでデータをスコープ化。オプションのリージョンピンで居住地要件を強制。
• PostgreSQL + pgvectorベースのセルフホスティング – ベンダーロックインなし。あらゆるクラウドまたはオンプレインフラで動作。
• SDKs – 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は、LLMエージェント向けのセルフホスティング型、PostgreSQLベースのメモリレイヤーであり、決定論的で証跡豊富なコンテキスト、ポリシー駆動のラベル付け、マルチテナント隔離を、シンプルなREST APIと言語固有のSDKで提供します。