Summary

Statewave is an open-source memory runtime designed to provide AI agents with reproducible, provenance-tagged context, addressing the common issue of statelessness in AI applications. It offers a structured approach to memory management, moving beyond fragile, query-time retrieval by compiling context into deterministic bundles. This infrastructure benefits developers building stateful AI systems by ensuring consistent recall, traceable data lineage, and a clear data lifecycle, all self-hostable on standard infrastructure.

How It Works

Statewave operates by ingesting raw events (episodes) into an append-only log, organized around user-defined subjects. These episodes are then compiled into typed memories with confidence scores and provenance. On demand, Statewave assembles token-bounded context bundles from these memories, ensuring that the same query against the same subject at the same time yields identical results. This compile-then-use approach eliminates sampling noise inherent in query-time retrieval, providing deterministic and traceable context crucial for reliable AI agent behavior.

Quick Start & Requirements

• Installation:
  • Server: curl -fsSL https://www.statewave.ai/install | sh (macOS/Linux) or irm https://www.statewave.ai/install.ps1 | iex (Windows PowerShell). Alternatively, git clone and docker compose up -d.
  • Python SDK: pip install statewave
  • TypeScript SDK: npm install @statewavedev/sdk
• Prerequisites: PostgreSQL 14+ with pgvector ≥ 0.4.2.
• Dependencies: CPU-only API process; GPUs are only required if self-hosting LLM compilers or embedding models. LiteLLM support for 100+ LLM providers (OpenAI, Anthropic, Azure, etc.) via environment variables (STATEWAVE_LITELLM_API_KEY, STATEWAVE_LITELLM_MODEL).
• Links: Website & Demo, Python SDK Docs, TypeScript SDK Docs.

Highlighted Details

• Deterministic Context Bundles: Generates ranked, token-bounded context that is byte-for-byte identical for the same task and subject state.
• Provenance Tracking: Every memory traces back to its source episodes, with immutable, ULID-addressable receipts containing signatures and policy snapshots.
• Pluggable Compilers: Supports heuristic (fully local, regex-based) or LLM-based compilation, offering flexibility based on performance and cost needs.
• Subject-Oriented Architecture: Organizes data around entities like users, accounts, or repositories, enabling granular memory management.
• Sensitivity Labels & Policy Engine: Declarative YAML policies for data governance (deny/redact) over tagged memories (e.g., PII, secret), with optional heuristic auto-labeling.
• Extensive Connectors: Modular packages for ingesting data from sources like GitHub, Slack, Notion, Zendesk, Gmail, and n8n into Statewave memory.

Maintenance & Community

Statewave is actively developed (v1.3.0). Community interaction, questions, and roadmap input are encouraged via GitHub Discussions. Bug reports and implementation tasks should be filed as GitHub Issues. Security vulnerabilities should be reported to security@statewave.ai.

Licensing & Compatibility

Statewave is licensed under the permissive Apache License, Version 2.0. This license allows for free use, modification, and distribution, including within proprietary, hosted, or commercial products, without source-disclosure obligations. It includes an explicit patent grant from contributors.

Limitations & Caveats

Current limitations include IP-based rate limiting (not per-tenant), multi-tenancy lacking native Postgres Row-Level Security (RLS), no built-in authentication provider, a YAML-based policy authoring approach without a visual editor, and no built-in federated cross-region audit capabilities. Receipt replay currently uses the original policy against current memories, not full historical memory snapshots.