Developer Quickstart

For developers

Run MemState in two commands.

Install the package, boot the service, then exercise the two calls your agent needs: send an observation into memory and ask for relevant context. MemState applies ingest, revise, and forget policy internally. Everything here runs against a local instance.

Install & run API reference ← Product overview
Contract vs wire format. Product-wise, the agent only emits observations and questions; MemState decides how to persist, merge, and fade memory. The runnable examples below still show explicit placement (and similar) fields accepted by this reference build until observation-first routing is fully automatic in the service.
Step 1

Install and boot.

MemState is distributed as a Python package with an embedded Kuzu store. You get a complete service on localhost — no external database to provision. 

python -m pip install -e .
uvicorn memstate.api.main:app --reload

The service listens on http://127.0.0.1:8000. The web UI is served at /ui, and the OpenAPI schema is at /openapi.json.

Step 2

Observation in, context out.

Two endpoints cover the agent boundary: persist what was observed, then query for what matters. Revise and forget are not separate agent calls; the reasoner runs them after ingest and query complete. 

POST /v1/ingest
{
  "placement": "new_topic",
  "title":    "Launch plan",
  "summary":  "Q3 public release milestones",
  "fields": [
    { "name": "owner",       "value": "Aya",         "provenance": "ui"   },
    { "name": "status",      "value": "in_progress", "provenance": "ui"   },
    { "name": "target_date", "value": "2026-07-01",  "field_type": "date" }
  ]
}
POST /v1/ingest
{
  "placement": "version_field",
  "topic_id":  "t_8a3b...",
  "fields": [
    {
      "name":  "status",
      "value": "shipped",
      "provenance":  "ui",
      "why_changed": "launch went live"
    }
  ]
}
POST /v1/query
{
  "q":      "what is launch plan status?",
  "top_k":  5
}

// -> { candidates: [{ topic_id, title, fields: [{ name, current: "shipped" }], ... }] }
POST /v1/query
{
  "q":       "how did launch status change?",
  "stages":  ["semantic", "structural", "temporal"],
  "explain": true
}

// -> fields: [{
//      name: "status",
//      current: { value: "shipped",      valid_from: "2026-07-01" },
//      history: [
//        { value: "shipped",     valid_from: "2026-07-01", provenance: "ui" },
//        { value: "in_progress", valid_from: "2026-05-12", provenance: "ui" }
//      ]
//    }]
Step 3

Use the Python client.

For in-process use, the bundled client gives you a typed wrapper around the same endpoints. Same semantics, no HTTP boilerplate. 

from memstate.client import MemoryClient

client = MemoryClient(base_url="http://127.0.0.1:8000")

client.ingest({
    "placement": "new_topic",
    "title":    "Launch plan",
    "summary":  "Q3 public release",
    "fields":   [{"name": "owner", "value": "Aya"}],
})

client.query({ "q": "who owns the launch plan?", "top_k": 3 })
Know the surfaces

Three API surfaces, one store.

All three surfaces read and write the same underlying memory. Pick the one that matches the caller.

  • /v1 — Client API. Stable contract for agent integrations: observation-shaped POST /v1/ingest and context POST /v1/query. Revise and forget stay inside MemState. primary
  • /api/ui — UI API. Lower-level endpoints used by the bundled web UI. Expose raw topic, field, and link operations for inspection and administration. tooling
  • /api/llm/chat — LLM API. A chat-style surface where a model forwards observations and context questions through natural-language requests. optional
Go deeper

Where to go next.

  • API reference — every endpoint, every field.
  • Ingest — observation payload, executor behavior, placement fields in this build.
  • Query — context retrieval stages, history, explain.
  • Data model — topics, fields, and links in detail.
  • Architecture — service, reasoner, and store.
  • Run & configuration — env vars, ports, storage paths.