Statewave

Open-source memory runtime for AI agents. Statewave 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.

Primary focus: support-agent workflows — where structured memory clearly outperforms naive history stuffing and simple RAG. Statewave gives your support agent durable customer context across sessions, with provenance, ranked retrieval, and token budgets.

The problem

Most AI applications have no memory. Every conversation starts from scratch. Context is lost between sessions, decisions aren't remembered, and user history disappears the moment a session ends. Bolting on a vector database or dumping chat logs into a prompt doesn't solve this — it creates fragile, unstructured context that degrades as it scales.

What Statewave does

Statewave gives your AI system durable, structured memory with a clear data lifecycle:

1. Ingest — record raw events (episodes) as they happen, append-only
2. Compile — extract typed, summarised memories with confidence scores and provenance
3. Retrieve — assemble ranked, token-bounded context bundles ready for your prompts
4. Govern — inspect subject timelines, trace every memory to its source, delete by subject

Everything is organised around subjects — a user, account, agent, repo, or any entity you track.

Why Statewave

• Your AI remembers — preferences, decisions, history persist across sessions
• Context is structured, not dumped — ranked retrieval with token budgets, not raw chat log stuffing
• Provenance is built in — every memory traces back to its source episodes
• You own the storage — self-hosted, open source, no vendor lock-in. Episodes and compiled memories live in your Postgres. The default heuristic compiler runs fully local; choose an LLM compiler or hosted embeddings if you want them. See Privacy & Data Flow.
• No GPU required — the API process is CPU-only. GPUs only enter the picture if you self-host an LLM compiler or embedding model. See Hardware & Scaling.
• Framework-neutral — works with any AI stack, any language, via REST API or typed SDKs

Statewave is not a chatbot framework, a vector database, a RAG pipeline, or a hosted service. It is infrastructure you run alongside your application.

Status: v0.7.1 — actively developed. Full support-agent intelligence stack: session-aware context, resolution tracking, handoff packs, health scoring, SLA tracking, proactive alerts. See current limitations below.

🎯 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 the same question, one stateless and one backed by Statewave.

Documentation

Capabilities

• Episode ingestion — append-only raw event recording, single or batch (up to 100)
• Pluggable compilers — heuristic (regex) or LLM (any LiteLLM-supported provider) memory extraction
• Idempotent compilation — recompiling the same subject produces no duplicates
• Semantic search — pgvector cosine similarity with text-search fallback
• Token-bounded context — context bundles respect a configurable token budget
• Ranked retrieval — kind priority × recency × task relevance × temporal validity × semantic similarity
• Memory conflict resolution — auto-supersede older overlapping memories
• Provenance — every memory traces back to its source episodes
• Subject management — list subjects with counts, inspect timelines, permanently delete all data by subject
• Authentication — optional API key via X-API-Key header
• Rate limiting — per-IP fixed-window, distributed (Postgres-backed) or in-memory
• Multi-tenant — optional X-Tenant-ID header with real query-scoped data isolation
• Webhooks — persistent HTTP callbacks with retries and dead-letter on episode, compile, and delete events
• OpenTelemetry tracing — optional spans on key operations (requires [otel] extra)
• Structured logging — structlog with JSON output in production, console in development
• Structured errors — consistent JSON error format with request-ID correlation
• Session-aware context — active session boosted, resolved sessions deprioritized
• Resolution tracking — mark issues open/resolved, surface resolution history
• Handoff context packs — compact escalation briefs with health, SLA, and issue context
• Customer health scoring — deterministic 0–100 score with explainable factors
• SLA tracking — first-response time, resolution time, breach detection
• Proactive health alerts — webhooks on health state transitions (degradation + recovery)
• Repeat-issue detection — surfaces prior resolutions when patterns recur

Quick start

# Start Postgres (pgvector)
docker compose up db -d

# Create virtualenv and install
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,llm]"

# Run migrations
alembic upgrade head

# Start the server
uvicorn server.app:app --host 0.0.0.0 --port 8100

The API is available at http://localhost:8100.

See the full getting started guide for step-by-step setup including environment configuration.

API

Full reference: API v1 contract.

Connectors

Statewave is not limited to live chat transcripts. Connectors feed real-world events into Statewave as episodes, so your agents can build memory from repos, communities, docs, support tools, email, and workflows — without you hand-writing an ingest path for each source.

Connectors live in their own repository so this core stays focused on the runtime. They are modular — install only what you need:

# Pick what you need — every package is independent
npm install @statewavedev/connectors-github
npm install @statewavedev/connectors-markdown
npm install @statewavedev/connectors-slack
npm install @statewavedev/connectors-n8n
npm install @statewavedev/connectors-zapier
npm install @statewavedev/mcp-server

A convenience meta-package @statewavedev/connectors re-exports the official connectors for the rare case where you want them all at once. It is not required for normal usage.

Quick examples (dry-run-first — nothing is ingested without your say-so):

statewave-connectors sync github \
  --repo smaramwbc/statewave \
  --subject repo:smaramwbc/statewave \
  --dry-run

statewave-connectors sync markdown \
  --path ./docs \
  --subject repo:smaramwbc/statewave \
  --dry-run

statewave-connectors mcp start

Where to go next:

• Connector ecosystem repo: statewave-connectors (Phase-1 packages — core, CLI, MCP server, GitHub, Markdown — landing soon; npm publication is a follow-up)
• Connector docs: statewave-docs/connectors
• SDKs (custom ingestion paths): Python · TypeScript

No connector code lives in this repo. Connectors talk to Statewave through the same public HTTP API documented above. If you don't need any of them, you don't install any of them.

Configuration

All settings use the STATEWAVE_ env prefix. Copy .env.example to .env to get started.

For best results: Set STATEWAVE_COMPILER_TYPE=llm and STATEWAVE_EMBEDDING_PROVIDER=litellm with an STATEWAVE_LITELLM_API_KEY. Statewave uses LiteLLM as its single provider abstraction, so you can use any supported provider — OpenAI, Anthropic, Azure, Ollama, Cohere, Gemini, Bedrock, Mistral, Groq, and 100+ others — by setting STATEWAVE_LITELLM_MODEL to any LiteLLM model identifier (e.g. gpt-4o-mini, claude-3-haiku-20240307, ollama/llama3, azure/gpt-4). The heuristic compiler still works without any LLM API key.

Running tests

# Unit tests (no DB required)
pytest tests/test_*.py -v

# Integration tests (requires Postgres)
PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test
pytest tests/integration/ -v

# All tests
pytest tests/ -v

Current limitations

Statewave is in active development (v0.7.1). Honest status:

• Rate limiting is per-IP — distributed (Postgres-backed), but keyed by IP only, not per-tenant or per-API-key yet
• Multi-tenant is app-layer — real query-scoped isolation (v0.5), no Postgres RLS yet
• Single-node only — no clustering, no horizontal scaling yet
• PostgreSQL required — no alternative storage backends
• No built-in auth provider — validates API keys you configure, doesn't issue them

See the roadmap for what's being fixed and when.

Community

Statewave is built in the open. Where to post what:

• GitHub Discussions — questions, ideas, RFCs, integrations, roadmap input, what you're building
• GitHub Issues — confirmed, reproducible bugs and concrete implementation tasks
• Security vulnerabilities — email [email protected] (do not post publicly; see SECURITY.md)
• Commercial / private licensing terms — email [email protected] (general licensing questions are welcome in Discussions)

The full community guide — categories, RFC process, moderation — lives in statewave-docs/community/discussions.md. Copy-paste templates for questions, feature requests, RFCs, and show-and-tell are in discussion-templates.md.

Ecosystem

Licensing

Statewave is dual-licensed:

• AGPLv3 — for open-source / community use.
• Commercial license — for proprietary, SaaS,
  embedded, hosted, or enterprise use.

This allows Statewave to stay open and community-driven while protecting
the project from unmanaged commercial hosting or closed-source
redistribution. If you want to use Statewave in a proprietary product,
SaaS platform, managed service, or enterprise environment without AGPL
obligations, contact us for a commercial license.

A startup-friendly commercial tier is available for early-stage companies
under a qualifying threshold.

• Quick decision guide: LICENSING.md
• Commercial license overview: COMMERCIAL-LICENSE.md
• Tiers (Community / Startup / Growth / Enterprise): docs/licensing.md
• Trademark policy: TRADEMARKS.md
• Contributing under dual licensing: CONTRIBUTING.md
• Contact: [email protected]

This repository describes Statewave's licensing model and is not legal
advice. Consult qualified counsel before adopting Statewave in a
commercial product.