Agent Memory API

HTTP integration guide. Requests and responses use Persona, Scope, Topic, and Atom. Base path: /api/v1/memory.

Hierarchy

Understand the four layers before you integrate:

Persona: Whose memory (team default is bound by the platform when omitted)
Scope: Broad domain, e.g. engineering, finance
Topic: Subject within the scope, e.g. billing, api-auth
Atom: One retrievable memory unit (body + optional attachment)

Memory stack (retrieval modes)

POST /search — L3 deep semantic search
POST /recall — L2 recall (optional scope / topic / persona filters)
POST /wake-up — L0+L1 session wake-up context

Authentication

Header Authorization: Bearer <API_KEY> with memory:read or memory:write scope.

/api/v1/memory

Endpoints

Method	Path	Scope	Description
POST	/api/v1/memory/atoms	memory:write	Create an Atom
GET	/api/v1/memory/atoms	memory:read	List Atoms (paginated)
DELETE	/api/v1/memory/atoms/{atomId}	memory:write	Delete one Atom
POST	/api/v1/memory/search	memory:read	L3 search
POST	/api/v1/memory/recall	memory:read	L2 recall
POST	/api/v1/memory/wake-up	memory:read	Wake-up stack

Create Atom (JSON)

POST /api/v1/memory/atoms
Content-Type: application/json

{
  "scope": "engineering",
  "topic": "billing",
  "document": "Customers are invoiced on the 25th."
}

// 201 response (one or many nodes)
{
  "atom": { "id": "…", "scope": "…", "topic": "…", "persona": "…", "document": "…", "metadata": {}, "createdAt": "…" },
  "atoms": [ "…all persisted atoms; may be >1 when verbatim splits memoryNodes" ]
}

multipart/form-data: field "atom" is a JSON string (scope, topic, document); "file" is an optional attachment.

Async write (202)

When the platform ingest queue is enabled, POST /atoms returns 202 Accepted by default (verbatim runs in the background). Use ?sync=1 for an immediate 201 with persisted atoms; ?async=0 disables async. Job status is available via dashboard Admin APIs only; integrators may poll GET /atoms after a delay.

// 202 response (queue enabled)
{
  "async": true,
  "queue": { "enabled": true, "driver": "cloudflare" },
  "job": {
    "id": "…",
    "status": "queued",
    "generateMemoryNodes": true,
    "scope": "engineering",
    "topic": "billing"
  }
}

// Synchronous success remains 201 with the same body shape as writeJson above

List Atoms

GET /api/v1/memory/atoms?offset=0&limit=50&persona=<optional>&memoryLibraryId=<library-id>

Delete one Atom

DELETE /api/v1/memory/atoms/{atomId}?memoryLibraryId=<library-id>

// 200 response
{ "ok": true, "atomId": "…" }

Search example

POST /api/v1/memory/search
{ "query": "billing rules", "k": 8, "scope": "engineering", "topic": "billing", "memoryLibraryId": "<library-id>" }

MCP integration

MCP clients (Cursor, Claude Desktop, etc.) can use Streamable HTTP at /api/v1/memory/mcp. Call memory_list_libraries first, then retrieval or write tools.

/api/v1/memory/mcp

→ Full Agent Memory MCP guide

Out of scope (console)

The features below are not available with API keys. Sign in and use the dashboard (backed by /api/admin/memory/* + Session):

Engine implementation details are in packages/agent-memory/docs/技术说明.md and docs/agent-memory-技术说明.md.

Published benchmark results (ENGRA-KB-v1 + MTEB) · → Console · Memory console · Product overview