Memory API

The core read/write surface. Most callers use the MCP tools for the conversational path and the admin HTTP routes for management.

MCP tools

The MCP endpoint is mounted at /api/v1/projects/{projectId}/mcp-server. It exposes the memory tools:

Tool	What it does
`memory_observe`	Send raw text; the engine runs zero-LLM heuristic extraction and decides what to save. Idempotent.
`memory_save`	Write a memory item verbatim with an explicit `kind` and `scope`. Rare — prefer `observe`.
`memory_search`	Relevance retrieval — hybrid semantic + recency + importance, filtered by scope.
`memory_list`	`search` with no query — newest-first items in a scope.
`memory_recall`	Fetch a single memory by id (bumps `lastAccessedAt`). Not semantic retrieval.
`memory_extract_pending`	Return memories whose graph entities aren’t extracted yet, each with an LLM-ready prompt.
`memory_commit_extraction`	Persist the entities + edges your LLM produced; content-hash idempotent.

See Lifecycle for how these fit together and the two-step graph-extraction protocol.

Admin memory (HTTP)

Mounted at /api/v1/projects/{projectId}/admin/memory. All admin routes require WRITE_MEMORY.

Method	Path	Purpose
`GET`	`/admin/memory`	List memories (filter by `type`, `scope`, `status`, `asOf`, …).
`GET`	`/admin/memory/platform`	List platform-scoped memories.
`GET`	`/admin/memory/review`	Review queue (pending / flagged).
`GET`	`/admin/memory/stats`	Corpus stats: counts by scope / status / type, embedding coverage, pattern count.
`GET`	`/admin/memory/insights`	Per-subject recency / silence / importance roll-up.
`POST`	`/admin/memory`	Create a memory (any scope).
`PATCH`	`/admin/memory/:memoryId`	Edit a memory.
`POST`	`/admin/memory/:memoryId/confirm`	Confirm or reject a pending memory.
`POST`	`/admin/memory/:memoryId/promote`	Move a memory to a different scope.
`POST`	`/admin/memory/search`	Semantic search across scopes; `asOf` expands to superseded memories valid then.
`DELETE`	`/admin/memory/:memoryId`	Delete a memory.

The asOf (ISO-8601) parameter on list and search is the time-travel knob — it returns the bi-temporal slice valid at that instant (validFrom <= asOf and validTo null or > asOf).

The knowledge-graph entity/edge routes also live under /admin/memory (/entities, /edges, /graph/*). See the Knowledge Graph API.

Media ingest

POST /api/v1/projects/{projectId}/memory/media

Ingest an image, audio clip, or document as base64. The engine extracts text via LiteLLM (vision + docs through chat-completions, audio through transcription), then runs that text through the same Observe pipeline — so media-derived memories get extraction, graph wiring, and embedding for free.

{
  "mimeType": "image/png",
  "dataBase64": "iVBORw0KGgo…",
  "source": "receipt-2026-07.png"
}

Response:

{
  "saved": [ { "id": "mem_…", "content": "…", "kind": "fact" } ],
  "candidateCount": 3,
  "extractedText": "…",
  "modality": "image",
  "blobUri": ""
}

modality is image | audio | document. blobUri is the retained blob location, empty when the raw bytes aren’t stored.

⚠️

Media ingest requires the MEMORY_MULTIMODAL_ENABLED flag on the engine and enforces the events cap + budget. Without the flag, use POST /memory/attachments, which stores the blob plus a caller-captioned memory but does not run vision/ASR.

Observe v2 (LLM extraction)

By default observe is purely heuristic (regex + structural, zero tokens). When enabled, an additional LLM conversational-extraction pass pulls durable, self-contained facts out of narrative text the heuristics miss (the shape of real chat, not just structured B2B statements).

It is guarded by two gates:

MEMORY_LLM_MEMORY_EXTRACTION_ENABLED — the ops master switch (off by default, so it never silently spends tokens).
FEATURE_MEMORY_INTELLIGENCE — a per-tenant entitlement (the Pro-tier premium path). Free-tier tenants stay on the heuristic pass.

Extracted items join the same saved set and get the same semantic indexing and graph enrichment. The pass is best-effort: any transport or parse error is logged and swallowed — it never fails the parent write.

Overview Typed Attributes