Statewave is an open-source memory runtime for AI agents, with the goal of giving AI systems persistent, structured memory and replacing query-time retrieval with reproducible, provenance-tagged context packs. It is licensed under Apache-2.0, self-hosted on Postgres + pgvector, and provides Python and TypeScript SDKs. According to official documentation, it is not a chatbot framework, vector database, RAG pipeline, or managed service, but rather infrastructure that runs alongside applications.
Purpose
Most AI applications have no memory, starting from scratch with every conversation, losing cross-session context, failing to remember decisions, and having user history disappear when a session ends. Simply adding a vector database or stuffing chat logs into prompts creates fragile, unstructured, and hard-to-scale context. Statewave provides AI systems with persistent, structured memory and a clear data lifecycle: ingestion, compilation, retrieval, governance. Everything is organized around "topics," which can be users, accounts, agents, repositories, or any tracked entity.
Key capabilities
- Compiled context packs: generate ranked, token-limited, deterministic context by topic and task; the same topic at the same point in time with the same query always produces the same bytes.
- Provenance tracing: every memory can be traced back to its source event, with receipts using content hashes.
- Pluggable compilers: heuristic compiler (regex, fully local) or LLM compiler (any LiteLLM provider).
- Topic organization: supports user:, repo:, account:, or custom entity prefixes.
- State assembly receipts: immutable, ULID-addressable, recording which memories influenced each pack; HMAC-SHA256 signed, with embedded policy snapshot, and provides POST /v1/receipts/{id}/replay.
- Sensitivity labels and policy engine: declarative YAML policies based on per-memory labels (pii, financial, secret, etc.), supporting deny / redact, with log_only and enforce modes; v0.9 adds suggested labels from heuristic detectors (pii.email/phone, financial.card, secret.token), which require operator review and explicit promotion through the admin application.
- Multi-tenancy: query-scoped data isolation via the X-Tenant-ID request header, supportingper-tenant configuration and policies; v0.9 adds per-tenant region pinning, where tenants pinned to eu receive a 403 when requested in other regions.
- Self-hosted: based on Postgres + pgvector, no vendor lock-in, runs on your own infrastructure.
- No GPU required: the API process uses only CPU; GPUs are only involved when self-hosting an LLM compiler or embedding model.
- Framework-agnostic: works with any AI stack and any language via REST API or typed SDKs.
How to use
The fastest way is to start the server with a one-line command (see the official documentation for the specific command); you can also run it yourself, which by default launches Postgres (pgvector) + API, automatically runs migrations on container startup, and the API is located at http://localhost:8100。默认以演示模式启动，使用基于哈希的桩嵌入 + heuristic compiler, no real semantic search. For LLM-backed behavior, add a .env next to docker-compose.yml and re-run docker compose up -d. You can confirm whether the LLM key was read via GET /readyz. Docker / Helm self-hosting is also supported, and SDK documentation is available for statewave-py (Python) and statewave-ts (TypeScript). All settings use the STATEWAVE_ environment prefix, and you can copy .env.example to .env to get started. The official recommendation is to set STATEWAVE_COMPILER_TYPE to llm, STATEWAVE_EMBEDDING_PROVIDER to litellm, and provide STATEWAVE_LITELLM_API_KEY; Statewave supports 100+ providers through LiteLLM, including OpenAI, Anthropic, Azure, Ollama, Cohere, Gemini, Bedrock, Mistral, Groq, etc., and you only need to set STATEWAVE_LITELLM_MODEL to the corresponding LiteLLM model identifier. The heuristic compiler still works when no LLM key is used.
Statewave is not limited to real-time chat logs; connectors can feed real events into Statewave as events, and connectors are located in a separate repository and are installed modularly. Examples include: a customer support agent (identifying returning customers across sessions, ranked context with a token budget, source tracing, and a handoff package during escalation), a long-running coding agent (multi-session project memory, with tech stack, preferences, and architecture decisions preserved across conversations), and a comparison of stateless and memory-driven agents (using a real LLM). The official examples repository also provides a minimal quick start, an evaluation suite (23 tests, 56 assertions), benchmarks, and framework integrations such as LangChain, CrewAI, AutoGen, etc.
Applicable scenarios
Suitable for teams that need to add persistent, traceable, and governable memory to AI agents, such as customer support, coding agents, multi-session assistants, and enterprise applications that require self-hosting, controllable data flows, multi-tenant isolation, and audit capabilities.
Limitations
According to the official v1.5.0 status: rate limiting is by IP, and the default memory policy is perprocess; multi-replica deployments require STATEWAVE_RATE_LIMIT_STRATEGY=distributed (backed by Postgres), and it is only by IP, not by tenant or API key. Multi-tenancy is at the application layer, and there is no Postgres RLS yet. There is no built-in authentication provider; it only validates the API keys you configure and does not issue keys. There is no admin operational identity yet; the v0.9 automatic tag promotion endpoint records promoted_at and the tag, but promoted_by is null until the admin identity layer is released. There is no visual policy editor; policy packages are written in YAML in git and uploaded through the management process. There is no cross-region federated audit; v0.9 enforces strict regional isolation by design. Replay is "current code + original policy"; byte-level historical reproduction requires memory snapshots, which are not yet provided. Multi-replica production can run (Fly multi-machine + Helm HPA has been verified), and the bottleneck under heavy load is Postgres and the embedding provider. The current version is v1.5.0, under active development.
The above information all comes from the official repository description; facts not mentioned, such as charges, pricing, and specific platform coverage, are not currently provided.
