Statewave
Statewave is an open-source memory runtime that gives AI agents reproducible, provenance-tagged context by compiling raw events into typed memories. It solves the problem of stateless AI applications by providing durable, structured memory with a clear data lifecycle. It is for developers building AI agents that need persistent, auditable memory across sessions.
✨ Key features
- Compiled context bundles: ranked, token-bounded, deterministic per subject and task.
- Provenance: every memory traces back to source episodes; receipts are content-hashed.
- Pluggable compilers: heuristic (regex, local) or LLM via any LiteLLM provider.
- Subject-organised: user:, repo:, account:, or any entity prefix.
- Sensitivity labels + policy engine: YAML policies with deny/redact modes.
- Multi-tenant: query-scoped isolation via X-Tenant-ID header, per-tenant config.
🎯 Use cases
- Customer support agent that recognizes returning customers across sessions.
- Long-running coding agent with multi-session project memory.
- A/B testing stateless vs memory-powered agents with a live LLM.
- Building memory from GitHub, Slack, Notion, and other sources via connectors.
📦 Installation
🧰 Requirements: Python 3.11+ for SDK, server on Linux (macOS/Windows for dev), PostgreSQL 14+ with pgvector ≥0.4.2, Docker for quickstart, optional LiteLLM API key for LLM features.
npx @statewavedev/statewavecurl -fsSL https://www.statewave.ai/install | sh# Windows (PowerShell)
irm https://www.statewave.ai/install.ps1 | iex
Prefer to run it yourself?
git clone https://github.com/smaramwbc/statewave && cd statewave
docker compose up -d
🚀 Usage
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)
⚠️ Good to know
Actively developed (v1.5.0); Python 3.12/3.13 not CI-gated, macOS/Windows not CI-tested, demo mode uses stub embeddings, and compiled bundles cost more tokens than fact-store retrieval.
❓ FAQ
How is this different from other memory systems?
Statewave compiles context once per subject change with provenance, unlike systems that retrieve isolated facts per query, which can return the same summary regardless of question. This yields higher multi-hop accuracy.
Does it work with my model provider?
Yes, Statewave uses LiteLLM, so any of 100+ providers work (OpenAI, Anthropic, Azure, Bedrock, Ollama, Groq, Cohere, Gemini, Mistral, etc.). Set STATEWAVE_LITELLM_MODEL to any LiteLLM identifier.
What's the license — can I use this commercially?
Yes, Statewave (server + SDKs) is Apache-2.0, a permissive license with an explicit patent grant. Use it freely in proprietary, hosted, or commercial products with no source-disclosure obligations.
Can I self-host?
Yes, that's the default. You can use Docker Compose, Helm chart, or bare-metal. See the Deployment guide for details.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.