Statewave Documentation

June 25, 2026 · View on GitHub

Statewave is the open-source memory runtime for AI agents. It compiles raw events into ranked, token-bounded context bundles with full provenance — so your AI stops forgetting across sessions. Self-hosted on Postgres, no vendor lock-in.

This repo contains the architecture docs, product specs, API contracts, and development coordination for the Statewave workspace.

This repo contains no production runtime code.

📋 Issues & feature requests: statewave/issues (centralized tracker)

Install

Fastest — one line to a running server:

# macOS / Linux
npx @statewavedev/statewave
# or
curl -fsSL https://www.statewave.ai/install | sh

# Windows (PowerShell)
irm https://www.statewave.ai/install.ps1 | iex

Prefer to run it yourself? The Getting Started guide walks through the manual git clone + docker compose up -d path in about 5 minutes.

🎯 Try it

The interactive comparison demo is embedded directly in the website at statewave.ai — open the chat widget to see two identical AI agents answer side by side, one stateless and one backed by Statewave.

Got a question about Statewave? Ask Statewave Support → — a docs-grounded agent that answers from this very docs corpus and cites the pages it used (read-only; built on the docs memory pack).

Getting Started ← start here
What is Statewave?
Why Statewave? — technical comparison for support-agent workflows
Design partner onboarding — 30-minute setup, evaluation checklist, success criteria, FAQ — for teams adopting Statewave early
Use Cases map — categorized inventory of what you can build (support, coding, workspace, account, voice, agent infrastructure, connectors, frontier ideas)
Connectors — feed real-world events (GitHub, Markdown/ADRs, MCP, and more) into Statewave as normalized episodes
Subject Design — the architectural treatment of subjects (entity granularity, tenancy, modelling)
Architecture Overview
Repo Map
API v1 Contract
State-assembly receipts — the immutable audit artifact emitted on each context assembly
Sensitivity labels & policy — per-memory capability tags + bundled rules consulted on every assembly call
Deployment Guide
Deployment Sizing Guide — hardware profiles by tier, topology patterns, bottleneck guidance
Capacity Planning & Tuning Checklist — diagnostic flow when load grows, tuning order, when to move up a tier
Default support docs memory pack — the docs-only knowledge base shipped for out-of-the-box support agents
Roadmap
Development Conventions
License — Apache-2.0

Community

Community guide — where to post what, how to write good questions and RFCs, tone and moderation
Discussion templates — Q&A, feature request, RFC, show-and-tell, integration, research
Pinned discussion drafts — ready-to-copy posts (welcome, what-are-you-building, roadmap priorities, RFCs)
Operator setup checklist — for maintainers configuring categories, pins, and recurring review

GitHub Discussions live on the core repo: statewave/discussions.

ADRs

Ecosystem

Project	Description
Server	Core server — API, domain model, DB, compilation, search
Python SDK	`pip install statewave` — sync + async client
TypeScript SDK	`npm install @statewavedev/sdk` — fetch-based client
Connectors	`@statewavedev/connectors-*` — GitHub, Markdown/docs, MCP server, modular packages
Docs	This repo — architecture, specs, ADRs (no runtime code)
Examples	Runnable examples, evals, benchmarks
Website + demo	Marketing website + embedded comparison demo (statewave.ai)
Admin	Operator console — system health, jobs, usage (read-only)

Current status

v1.3.0 — hybrid retrieval (pgvector + Postgres BM25, on by default with a hybrid=false opt-out) and compile-pipeline recall improvements (dedup/reconcile), plus provider-aware LLM key routing. The /v1/* API contract and governance surfaces (HMAC-signed receipts, receipt-driven replay, per-memory sensitivity labels + declarative YAML policy, opt-in detector-suggested labels, per-region data residency) remain stable, as do the v1.2 additions (dynamic settings endpoint for topology-agnostic hot-reload, a production-readiness probe, SSRF + DNS-rebinding protection on the webhook URL probe, LIKE metachar escaping in admin search, and six admin inspection endpoints). Both SDKs ship alongside: statewave (PyPI) v1.2.0 adds per-call timeout overrides and CancelledError propagation; @statewavedev/sdk (npm) v1.2.0 adds AbortSignal support on all HTTP methods. See roadmap and CHANGELOG.