开源AI工作流

Integration tests (requires Postgres)

PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test pytest tests/integration/ -v

[🚀 Skip to Getting Started →](#documentation)

Quickstart

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)

That's the loop: ingest → compile → use — ranked, token-bounded context with provenance. Run the server below, or self-host with Docker / Helm. Full SDK docs: statewave-py (Python) · statewave-ts (TypeScript).

Use cases

Three runnable examples in statewave-examples:

• Customer support agent — returning customer recognised across sessions, ranked context with token budget, provenance tracing, handoff pack on escalation. (Python · TypeScript)
• Long-running coding agent — multi-session project memory: tech stack, preferences, architecture decisions persist between conversations. (Python · TypeScript)
• Stateless vs memory-powered agent (live LLM) — full loop with a real LLM (any LiteLLM provider) running side by side with and without Statewave so you can A/B the difference yourself. (Python)

Plus the minimal quickstart, docs-grounded support, eval suite (56 assertions across 23 tests), a benchmark, and drop-in framework integrations — LangChain, CrewAI, and AutoGen — in the examples repo.

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.

API

Full reference: API v1 contract.

Pick what you need — every package is independent

npm install @statewavedev/connectors-github npm install @statewavedev/connectors-jira # preview npm install @statewavedev/connectors-database # preview — postgres/mysql/mariadb/mssql 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 markdown \ --path ./docs \ --subject repo:smaramwbc/statewave \ --dry-run

statewave-connectors mcp start ```

Where to go next:

• Connector ecosystem repo: statewave-connectors — published on npm under @statewavedev/connectors-* (incl. preview Jira + database source connectors)
• 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.

FAQ

How is this different from Mem0 / Zep? Mem0 is lean and fast but loses on multi-hop reasoning in our bench. Zep extracts a graph but in our LoCoMo run its retrieval surface returned the same thread summary regardless of the query. Statewave compiles the context once per subject change, with provenance. See statewave-bench for row-level data and a 20-minute reproducibility command against your own keys.

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, …). 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. See LICENSING.md.

Can I self-host? Yes — that's the default. Docker Compose, Helm chart, or bare-metal. See Deployment guide.

Why does it cost more tokens per answer than Mem0? Compiled context bundles are denser than Mem0's fact-store retrieval — that's what buys the higher multi-hop accuracy. If your queries are mostly single-hop and you're cost-sensitive, Mem0 may be the right call. The bench tells you when each system wins.