Statewave Agent Memory Runtime

What does this agent do, and when should you use it?

Statewave is an open-source memory runtime for AI agents, self-hosted on Postgres + pgvector, built around a compile-then-use model rather than per-query similarity search. It records append-only episodes per subject (user:, repo:, account:, or any prefix), compiles them into typed memories with confidence scores and provenance using either a fully local heuristic compiler or an LLM compiler, then assembles ranked, token-bounded context bundles for a given task. Every bundle comes with an immutable state-assembly receipt that traces back to source episodes, supports HMAC-SHA256 signing and POST /v1/receipts/{id}/replay. The server runs on port 8100 behind a REST API with a full OpenAPI surface, and ships Python (pip install statewave) and TypeScript (npm install @statewavedev/sdk) SDKs. It boots in demo mode with stub embeddings and the heuristic compiler, so no LLM key or GPU is needed to start; enabling semantic search and stronger extraction means pointing LiteLLM at any of 100+ providers.

The runtime is organised around subjects, and the end-to-end loop is ingest → compile → use. Ingestion uses POST /v1/episodes or POST /v1/episodes/batch (up to 100 at a time) to append raw events. Compilation calls POST /v1/memories/compile, which extracts typed, summarised memories with confidence scores and provenance, and is idempotent so recompiling produces no duplicates. Retrieval calls POST /v1/context to assemble a ranked, token-bounded bundle for a named task; the same query against the same subject at the same point in time yields the same bytes. Governance endpoints include GET /v1/timeline, GET /v1/subjects, DELETE /v1/subjects/{id} for subject-level deletion, POST /v1/handoff for a compact handoff pack, plus GET /v1/subjects/{id}/health for an explainable health score and /sla for response and resolution metrics. Search is served by GET /v1/memories/search across kind, text or semantic similarity, and POST /v1/resolutions tracks issue state per session. Compliance features include a declarative YAML policy engine (deny / redact) over memory tags such as pii, financial and secret, v0.9 heuristic auto-labeling with suggested_labels and operator promotion, multi-tenant isolation via the X-Tenant-ID header, and per-tenant region pinning that returns HTTP 403 residency.mismatch to processes in the wrong region.

1. Support teams that need returning customers recognised across sessions, ranked context inside a token budget, and a handoff pack via POST /v1/handoff when a case escalates.
2. Long-running coding agents that persist project memory — tech stack, preferences and architecture decisions — across separate conversations under a repo: subject.
3. Platform teams that want to self-host memory on their own Postgres and wire any language or framework to it over the REST API, keeping data inside their network.
4. Compliance and risk teams that need deny/redact policies over pii, financial and secret tags plus signed receipts showing which memories influenced each assembled bundle.
5. Organisations with data-residency rules that pin tenants to a region so requests hitting the wrong region are refused outright.
6. Teams building memory from non-chat sources by syncing GitHub, Slack, Notion, Zendesk or Gmail events into episodes with the @statewavedev/connectors-* packages, dry-run first.

How do you install or deploy this agent?

The fastest path is the official install script or npx; you can also run it yourself with Docker Compose.

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

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

Self-managed install:

git clone https://github.com/smaramwbc/statewave && cd statewave
docker compose up -d

This brings up Postgres (with pgvector) plus the API; migrations run on container start and the API is served at http://localhost:8100. The default is demo mode (stub embeddings + heuristic compiler). For LLM-backed behaviour, place a .env next to docker-compose.yml and re-run docker compose up -d:

STATEWAVE_EMBEDDING_PROVIDER=litellm
STATEWAVE_LITELLM_API_KEY=sk-...            # any LiteLLM provider
STATEWAVE_LITELLM_MODEL=gpt-4o-mini
STATEWAVE_LITELLM_EMBEDDING_MODEL=text-embedding-3-small

Requirements: PostgreSQL 14+ with pgvector ≥ 0.4.2; SDKs need Python 3.11+ or Node.js.

How do you use this agent?

Check readiness, then run the ingest → compile → use loop from the SDK or over HTTP.

curl http://localhost:8100/readyz
curl http://localhost:8100/healthz

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)

Interactive API docs live at http://localhost:8100/docs (Swagger) and /redoc. Key endpoints: POST /v1/episodes, POST /v1/memories/compile, POST /v1/context, GET /v1/timeline, GET /v1/subjects, DELETE /v1/subjects/{id}. Connector example (dry-run by default, nothing is ingested):

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

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ