smaramwbc/statewave

Statewave – deterministic, provenance‑rich memory for AI agents

What it is – Statewave is an open‑source runtime that sits next to your LLM‑powered application and gives it a durable, structured memory. It records raw episodes (e.g. chat messages, Git events, Slack posts), compiles them into typed memories with confidence scores and provenance, and then serves context bundles that are token‑bounded, ranked, and deterministic (the same query at the same point in time always returns the same bytes).

Why it matters – Most LLM‑driven bots are stateless: every request starts from a blank prompt, so they forget preferences, past decisions, or user history. Statewave solves this by:

• Persisting events in PostgreSQL (with the pgvector extension for embeddings).
• Compiling once per subject change, eliminating noisy, on‑the‑fly retrieval.
• Providing provenance so every piece of context can be traced back to its source episode.
• Running on CPU only (LLM or embedding calls are optional), making it cheap to host.

Core concepts

Concept	Role
Episode	Append‑only raw event (e.g. a chat message, a Git PR).
Memory	Typed, summarised representation produced by a compiler (heuristic regex or LLM via LiteLLM).
Context bundle	Ranked list of memories trimmed to a token budget, ready to be inserted into a prompt.
Subject	Logical entity the memory belongs to – user, repo, account, etc.
Receipt	Immutable, ULID‑addressable record of which memories formed a bundle, signed with HMAC‑SHA256.
Policy engine	YAML rules (deny, redact, log_only) applied to memory tags (pii, financial, …).

How you use it

from statewave import StatewaveClient

with StatewaveClient("http://localhost:8100") as sw:
    # 1️⃣ Ingest a raw event
    sw.create_episode(
        subject_id="user-42",
        source="chat",
        type="message",
        payload={"text": "Alice asked about pricing tiers"},
    )
    # 2️⃣ Compile memories for that subject (idempotent)
    sw.compile_memories("user-42")
    # 3️⃣ Retrieve a deterministic context bundle for a task
    bundle = sw.get_context(
        "user-42", task="answer pricing", max_tokens=1000
    )
    print(bundle.assembled_context)

The loop is ingest → compile → retrieve. The server can be started with a single Docker command or via the provided npx @statewavedev/statewave installer.

Key features

• Deterministic compiled bundles – no sampling noise from query‑time retrieval.
• Provenance & receipts – every token can be traced back to its source episode; receipts are signed and replayable.
• Pluggable compilers – simple regex‑based heuristics or any LLM supported by LiteLLM (OpenAI, Anthropic, Azure, Ollama, etc.).
• Sensitivity labeling & policy engine – declarative YAML rules to deny, redact, or log memories tagged as PII, secrets, etc.
• Multi‑tenant isolation – X‑Tenant‑ID header scopes data; optional region pinning enforces residency.
• Self‑hosted on PostgreSQL + pgvector – no vendor lock‑in, works on any cloud or on‑prem infra.
• SDKs – Python (statewave-py) and TypeScript (statewave-ts) clients, plus a REST OpenAPI spec.
• Connector ecosystem – separate packages (GitHub, Slack, Gmail, Notion, etc.) push real‑world events into Statewave as episodes.

Typical use‑cases

• Customer‑support bots that remember a user’s past tickets and preferences.
• Long‑running coding assistants that retain project decisions across sessions.
• A/B comparison of a stateless LLM vs. the same LLM with memory‑augmented context.
• Enterprise agents that need audit‑able, token‑level traceability for compliance.

Getting started

1. Install the server (Docker compose or the one‑liner installer).
2. Set a minimal .env – at least STATEWAVE_DATABASE_URL.
3. Optionally enable an LLM compiler by providing STATEWAVE_LITELLM_API_KEY and model IDs.
4. Use the Python or TypeScript SDK to ingest episodes and request context.

Where to learn more

• Full docs: https://github.com/smaramwbc/statewave-docs
• API reference: http://localhost:8100/docs
• Example projects: https://github.com/smaramwbc/statewave-examples
• Connectors repo: https://github.com/smaramwbc/statewave-connectors

---

TL;DR – Statewave is a self‑hosted, PostgreSQL‑backed memory layer for LLM agents that gives you deterministic, provenance‑rich context, policy‑driven labeling, and multi‑tenant isolation, all via a simple REST API and language‑specific SDKs.