REST API
The server serves REST, A2A and MCP on one port (API_PORT, default 3001). Bodies
and responses are JSON, and errors are always {"error": "<message>"}.
Authentication. In the default AUTH_MODE=local no credential is needed (the
server only listens on loopback). In AUTH_MODE=jwt every route except /health
and /ready needs Authorization: Bearer <token>. The examples below leave the
header out; add it for a shared deployment. See
Authentication and tenancy.
| Status | Meaning |
|---|---|
200, 201, 204 | success |
400 | invalid input |
401 | missing or invalid credential (jwt mode) |
403 | credential is valid but outside its scope |
404 | not found, or owned by someone your credential cannot see |
409 | conflict (for example an operation ID reused with another payload) |
500 / 503 | server or storage failure / temporarily unavailable |
Health
| Method and path | Purpose |
|---|---|
GET /health | liveness; static |
GET /ready | readiness: storage, ledger, coordinator, tokenizer, model_executor, search_index; 503 when the database handle is unavailable |
Memory
Base path /api/v1/memory.
| Method and path | Purpose |
|---|---|
POST / | add a memory |
GET / | list one page; filter with ?user_id=&agent_id=&session_id=, page with limit, cursor, include_embeddings |
DELETE / | delete every memory matching the same filters |
GET /{id} | fetch one |
PUT /{id} | replace its content (re-embeds, bumps version) |
DELETE /{id} | delete one |
GET /{id}/history | the change history |
# Add
curl -s -X POST http://127.0.0.1:3001/api/v1/memory -H 'content-type: application/json' \
-d '{"content":"Alice prefers dark mode","user_id":"alice","agent_id":"claude-code",
"session_id":"s-42","categories":["preference"]}'
# List one user's memories, one page at a time
curl -s 'http://127.0.0.1:3001/api/v1/memory?user_id=alice&limit=5'
curl -s 'http://127.0.0.1:3001/api/v1/memory?user_id=alice&limit=5&cursor=memory:0b6c4d1e-1f2a-4c3b-9d8e-7f6a5b4c3d2e'
# Update, then read the history
curl -s -X PUT http://127.0.0.1:3001/api/v1/memory/memory:949ae93e-62b2-467a-8937-51739d240d9a \
-H 'content-type: application/json' -d '{"content":"Alice prefers dark mode and large fonts"}'
curl -s http://127.0.0.1:3001/api/v1/memory/memory:949ae93e-62b2-467a-8937-51739d240d9a/history
POST requires content. Everything else is optional: user_id, agent_id,
session_id, categories. Adding text that is a near-duplicate (cosine similarity
at or above 0.92) of a memory in the same scope updates that memory instead of
creating another. A missing scope field widens the check to every value of it, so
set user_id and agent_id when you want the check to stay narrow.
DELETE / with no filters deletes every memory in the tenant. Always pass a scope.
It deletes in bounded batches of record IDs, expired and archived memories
included, and returns {"deleted": n}. It stops at the first memory it cannot
delete, and the error states how many were deleted before it. Sending the same
request again deletes the rest only once the cause is resolved (for example a
transient database error, or a row that cannot be read); until then a rerun stops
at the same memory.
Listing is paged
Breaking change (issue #62): GET / returns one page object, not a bare
array of every memory:
{ "memories": [ { "id": "memory:…", "content": "…", "embedding": null, "…": "…" } ],
"next_cursor": "memory:0b6c4d1e-1f2a-4c3b-9d8e-7f6a5b4c3d2e",
"has_more": true }
Pass next_cursor back as cursor until it is null (has_more is then
false). Treat a cursor as opaque. A cursor that is not of the form
memory:<key> is a 400; any memory:<key> is accepted as a starting
position, and the owner filters and the caller's scope still decide what is
returned.
| Parameter | Default | Limit |
|---|---|---|
limit | 50 (25 with include_embeddings) | 200; 25 with include_embeddings |
cursor | first page | a previous page's next_cursor |
include_embeddings | false | — |
A limit of 0 or above the maximum is a 400, never silently reduced. Each page
is also capped at 1 MiB of encoded memories: a page may hold fewer than limit
memories while has_more is true, and a single memory larger than that is
returned alone. Embeddings are omitted (null) unless requested.
Pages are ordered by record ID and are not a snapshot. A memory that exists for the whole iteration is returned exactly once; a memory added during it may be missed; a memory deleted or expired during it does not appear afterwards. The owner filters and the caller's verified scope apply to every page, so a cursor cannot reveal another scope's memories. Expired and archived memories never appear.
Search
POST /api/v1/search runs hybrid search (BM25 and HNSW merged by reciprocal rank
fusion).
| Field | Default | Meaning |
|---|---|---|
query | required | the search text |
user_id, agent_id, session_id | none | scope filters |
categories | none | any-match filter, applied to both legs |
limit | 10 | maximum results |
vector_weight / bm25_weight | 0.7 / 0.3 | the blend |
include_embeddings | false | embeddings are large and omitted unless asked for |
curl -s -X POST http://127.0.0.1:3001/api/v1/search -H 'content-type: application/json' \
-d '{"query":"editor theme","user_id":"alice","categories":["preference"],"limit":5}'
Knowledge graph
Base path /api/v1/entities.
| Method and path | Purpose |
|---|---|
POST / · POST /batch | create entities |
GET / | read the whole graph |
GET /search?q=… | search entities |
DELETE /{name} | delete an entity |
POST /{name}/observations | add observations |
GET /{name}/neighbors?depth=&limit= | neighbors up to a depth |
GET /{name}/related?relation_type=&direction=&limit= | related entities |
GET /{name}/path/{to}?max_depth= | shortest path |
POST /relations · POST /relations/batch | create relations |
curl -s -X POST http://127.0.0.1:3001/api/v1/entities -H 'content-type: application/json' \
-d '{"name":"Alice","entity_type":"person","observations":["Prefers dark mode"]}'
curl -s -X POST http://127.0.0.1:3001/api/v1/entities/relations -H 'content-type: application/json' \
-d '{"from":"Alice","to":"Acme","relation_type":"works_at"}'
TaskStreams
Base path /api/v1/taskstreams.
| Method and path | Purpose |
|---|---|
POST / · GET / | create · list |
GET /{name} · DELETE /{name} | fetch · delete |
POST /{name}/archive · POST /{name}/pause | lifecycle |
POST /{name}/memories | add a memory to the stream |
GET /{name}/context | token-budgeted context window |
POST /{name}/summarize | compress the stream |
curl -s -X POST http://127.0.0.1:3001/api/v1/taskstreams -H 'content-type: application/json' \
-d '{"name":"release-1-12","description":"Cut the 1.12 release","agent_id":"claude-code",
"model_id":"gpt-4o","auto_summarize":true}'
Mindmaps
Base path /api/v1/mindmaps.
| Method and path | Purpose |
|---|---|
POST / · GET / | create · list |
GET /{name} · DELETE /{name} | fetch · delete |
POST /{name}/nodes · DELETE /{name}/nodes/{node_id} | nodes |
POST /{name}/edges | add an edge |
GET /{name}/export | export |
POST /generate/persona · POST /generate/ideation | generate |
Keep mindmaps under 500 nodes; see MCP tools.
Durable operations
Base path /api/v2/operations. See Durable operations.
| Method and path | Purpose |
|---|---|
POST / | submit an operation |
GET /{id} | the authoritative receipt |
GET /{id}/events?after=N | ordered state events (server-sent events) |
GET /stats | counts per state, oldest unfinished operation, query cache |
POST /{id}/retry | re-drive now (operator) |
POST /{id}/reject | dead-letter, body {"reason":"…"} (operator) |
Memory Palace (palace feature)
Base path /api/v1/palace: GET /wake, GET /recall, POST /search,
POST /ingest, DELETE /drawer/{id}, GET /status, POST /hybrid-search.
A2A
| Method and path | Purpose |
|---|---|
GET /agent.json | the agent card; advertises bearer authentication |
POST /a2a/tasks/send | create a task: {"skill_id": "…", "input": {…}} |
GET /a2a/tasks/{id} | task status |
MCP over HTTP
| Path | Transport |
|---|---|
/mcp/http | streamable HTTP (current standard) |
/mcp/sse and POST /mcp/messages?sessionId=… | legacy SSE |
Sessions are bound to the principal that opened them. See MCP tools for the tools and example calls.