Skip to content

product.md

Latest commit

 

History

History
102 lines (79 loc) · 6.64 KB

product.md

File metadata and controls

102 lines (79 loc) · 6.64 KB
Raw

What is Statewave?

Statewave is an 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.

It gives your AI system durable, structured memory — so it can remember what happened, learn from past interactions, and retrieve relevant context at task time.

Core idea

Most AI applications treat context as disposable. Statewave treats it as infrastructure.

  1. Ingest raw events (episodes) — conversations, tool calls, decisions, observations
  2. Compile durable memories — typed, summarised, confidence-scored, with provenance back to source episodes
  3. Retrieve relevant context — filtered, scored, and token-budgeted for your prompt
  4. Inspect and delete by subject — full timeline visibility and GDPR-style erasure

Everything is organised around subjects — a user, account, workspace, repo, ticket, or agent.

What Statewave is

  • A self-hosted API server you run alongside your application
  • A structured memory store backed by Postgres + pgvector
  • A context assembly engine that returns prompt-ready bundles with token estimates
  • A provenance system that traces every memory back to its source episodes
  • A governance layer (receipts + sensitivity labels & policy) that records which memories influenced each agent response with byte-level integrity hashes, and filters per-memory access by caller identity through declarative YAML policy
  • Framework-neutral — works with any AI stack, any language

What Statewave is not

  • Not a chatbot or agent framework
  • Not a vector database (it uses one internally, but that's an implementation detail)
  • Not a RAG pipeline (retrieval is one capability, not the whole product)
  • Not an SDK wrapper around an LLM provider
  • Not a hosted SaaS (you run it yourself)

Best current use cases

  • Support agents that remember customer history across sessions ← primary focus
  • Coding agents that accumulate project knowledge over time
  • Workflow automation that needs to recall decisions and outcomes
  • Any AI application where "what happened before" matters for "what to do next"

Current focus: Statewave is purpose-built for support-agent workflows first. The eval and benchmark prove context quality for this use case.

Looking for ideas? The Use Cases map at statewave.ai/use-cases is the broader inventory — categorized workflows, connector/import patterns (existing data → episodes → compiled memory → context), and frontier directions. The list above is what's strongest today; the map is what the platform makes possible.

Current limitations

Statewave is on its first stable public developer release line (v1.3.0). We document these honestly:

Limitation Impact Status
Multi-tenant is app-layer only Real query-level isolation, no Postgres RLS yet Future: row-level security
Rate limiting is per-IP only No per-tenant or per-API-key limits yet Future: per-tenant limits
Single-Postgres only Multi-replica API deployments supported and verified since v0.8 (Fly multi-machine + Helm HPA); cross-region / multi-Postgres clustering not in v1.0 Not in v1.0; not currently committed to a release
Admin console is early Dashboards plus policy/tenant-config management; no memory editing or advanced ops Active development

What works well today:

  • Episode ingestion (single + batch, append-only, durable)
  • Memory compilation (heuristic or LLM via LiteLLM — 100+ providers)
  • Context assembly (ranked, token-bounded, with provenance)
  • Memory expiry — per-kind global TTL windows; retrieval filters expired memories immediately, hourly cleanup tombstones soft-deleted rows (memory-ttl.md)
  • Subject lifecycle (timeline, search, deletion)
  • Self-hosted deployment (Docker, Fly.io, bare metal)

API surface

Endpoint Purpose
POST /v1/episodes Ingest a single episode
POST /v1/episodes/batch Ingest up to 100 episodes
POST /v1/memories/compile Compile memories from episodes
GET /v1/memories/search Search memories by query
POST /v1/context Assemble a context bundle
POST /v1/handoff Generate a handoff context pack (health-aware)
GET /v1/subjects/{id}/health Customer health score + explainable factors
GET /v1/subjects/{id}/sla SLA metrics — response time, resolution time, breach flags
webhook: subject.health_degraded Fires when health state worsens (healthy→watch, watch→at_risk)
webhook: subject.health_improved Fires when health state recovers (at_risk→watch, watch→healthy)
GET /v1/receipts/{id} Fetch one state-assembly receipt by ULID
GET /v1/receipts List receipts for a subject (cursor-paginated)
GET /v1/receipts/{id}/verify Verify a receipt's HMAC signature
POST /v1/receipts/{id}/replay Re-run a receipt against current memories with its original policy
GET /v1/version Public, unauthenticated server version discovery
PATCH /v1/memories/{id}/labels Set per-memory sensitivity labels
GET /v1/timeline View subject timeline
GET /v1/subjects List subjects with counts
DELETE /v1/subjects/{id} Delete all data for a subject
GET / PATCH /admin/tenants/{id}/config Per-tenant config — receipts emission, retention, policy_mode, caller-identity gate
POST /admin/policy/bundles Upload (and optionally activate) a YAML policy bundle
POST /admin/policy/activate Switch active bundle for a scope
GET /v1/memory-templates List bundled memory templates (declarative scaffolds for recurring patterns)
GET /v1/memory-templates/{id} Fetch a single memory template — fields, types, content scaffold
POST /v1/memory-templates/{id}/apply Validate field values against a template and ingest the resulting episode

SDKs

  • Python — pip install statewave · sync and async clients, Pydantic models · source
  • TypeScript — npm install @statewavedev/sdk · fetch-based client, full type definitions · source

Getting started

See the getting started guide for setup instructions, or jump to examples.