Agent 记忆库 API

分层模型

写入与检索前先理解四层结构：

Library

隔离的记忆工作区；通过 memoryLibraryId 选择；引擎绑定 libraryKey（library-{uuid}）

Scope

粗领域，如 engineering、finance

Topic

领域内话题，如 billing、api-auth

Atom

一条可检索的记忆单元（正文 + 可选附件）

记忆栈（检索模式）

• POST /quick-search — 快速问答（小 k + 精准片段，适合用户自助查询）
• POST /retrieve — 组合 L2+L3（一次请求；今日底层共享语义检索）
• POST /search — L3 深度语义搜索
• POST /recall — L2 按需召回（可带 scope / topic / libraryKey 过滤）
• POST /wake-up — L0+L1 会话唤醒上下文

鉴权

请求头 Authorization: Bearer <API_KEY>，Scope 需包含 memory:read 或 memory:write。

/api/v1/memory

端点

创建 Atom（JSON）

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

{
  "scope": "engineering",
  "topic": "billing",
  "document": "客户每月 25 日结账。"
}

// 201 响应（单节点或多节点）
{
  "atom": { "id": "…", "scope": "…", "topic": "…", "libraryKey": "…", "document": "…", "metadata": {}, "createdAt": "…" },
  "atoms": [ "…全部落盘的 Atom；多 scope/topic 时可能 >1" ]
}

multipart/form-data（兼容）：字段 atom 为 JSON 字符串，file 为可选附件。大文件推荐直传（见下方）。

推荐直传（绕过网关请求体限制）：

1) POST /api/v1/memory/atoms/upload-url
   { memoryLibraryId, filename, mime, sizeBytes, contentHash, uploadId }

2) PUT <presigned url>  （浏览器直连 r2.cloudflarestorage.com）

3) POST /api/v1/memory/atoms
   { scope, topic, document, memoryLibraryId,
     directUpload: { uploadId, key, filename, mime, sizeBytes, contentHash } }

R2 私有存储与附件

附件与源文件不对公网匿名开放。列表中的 openUrl 指向 GET /source-files/{id}/open（须 memory:read），成功时 302 到约 15 分钟有效的 presigned URL。生产环境应关闭 R2 bucket 公开访问。

异步写入 / 修正（202）

平台开启摄取队列时，POST /atoms 与 PATCH /atoms/{atomId} 默认返回 202 Accepted（verbatim / 修正 / 索引在后台执行）。需要立即拿到落盘或修正结果时用 ?sync=1；显式禁用异步用 ?async=0。MCP memory_save_atom / memory_correct_atom 与 REST 默认行为一致（MCP 1.4.0+）。任务状态仅在控制台 Admin API 查询；集成方也可稍后 GET /atoms 确认。

// 202 响应（队列已启用，POST 或 PATCH）
{
  "async": true,
  "queue": { "driver": "cloudflare", "maxConcurrent": 2 },
  "job": {
    "id": "…",
    "status": "queued",
    "generateMemoryNodes": true,
    "scope": "engineering",
    "topic": "billing"
  }
}

// PATCH 异步额外字段
{
  "async": true,
  "operation": "correct",
  "atomId": "…",
  "job": { "id": "…", "status": "queued", … }
}

// 同步成功：POST 仍为 201（atom/atoms）；PATCH 仍为 200（corrected + atom）

异步写入与可见性

默认异步的设计目标：集成方与 IDE Agent 在提交正文后快速得到确认，而不等待 verbatim 拆分、R2 落盘与向量索引完成。

• 典型时延：纯文本 POST/PATCH 入队通常亚秒级返回 202；完整 pipeline 多在数秒至数十秒内完成（取决于正文长度、是否 generateMemoryNodes、队列负载）。
• 何时可检索：job 完成且向量索引就绪后，POST /search 与 POST /recall 才能稳定命中新内容；202 响应本身不含 atom.id。
• 确认方式：稍后 GET /atoms 按 scope/topic 或正文关键词查找；或登录控制台查看摄取任务（/dashboard/memory → Jobs，Admin API GET /api/admin/memory/jobs/[jobId]）。
• API Key 集成方目前无法通过公开 REST 轮询 job 状态；需要 atom.id 或同步错误时，请对 REST 使用 ?sync=1（MCP 写工具无 sync 参数，可改调 REST）。
• 失败感知：异步 job 失败时 202 仍已成功；需通过控制台 Jobs 或再次 GET /atoms 发现未落盘。同步模式（?sync=1）会在同一请求内返回 4xx/5xx。
• 选用建议：IDE / Agent 会话内落盘 → 默认异步；自动化脚本需 atom.id 或强一致 → REST ?sync=1。

列出 Atom

GET /api/v1/memory/atoms?offset=0&limit=50&libraryKey=<可选>&memoryLibraryId=<library-id>（legacy query persona 仍接受）

删除单条 Atom

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

// 200 响应
{ "ok": true, "atomId": "…" }

修正 Atom（版本控制）

PATCH /api/v1/memory/atoms/{atomId}?memoryLibraryId=<library-id>
Content-Type: application/json

{
  "document": "修正后的完整正文",
  "expectedVersion": 2,
  "scope": "engineering",
  "topic": "billing"
}

// 200 响应（?sync=1 或 ?async=0）
{
  "corrected": true,
  "atom": {
    "id": "…",
    "version": 3,
    "scope": "engineering",
    "topic": "billing",
    "document": "…",
    "metadata": { "version": 3 }
  }
}

// 202 响应（默认异步，见上方 asyncWriteJson）

// 409 version_conflict — 重新 GET 列表/检索获取最新 version 后重试

搜索示例

跨库语义（search / recall / quick-search / retrieve）：
- memoryLibraryId（或 Label）：主库（必填）
- 省略 memoryLibraryIds / Labels → 主库 Cross-library Search Defaults（若启用）
- memoryLibraryIds: [] → 仅主库（并关闭 shared-common 自动合并）
- 非空 memoryLibraryIds / Labels → 主库 + 列表（Common Knowledge 须显式列入）
- allAccessible: true → 覆盖 API Key 可 list 的全部库（与 Ids/Labels 互斥，400）
每条 hit 可含 memoryLibraryId / memoryLibraryName / source（team | platform_shared）。
响应可含 searchedLibraryIds、crossLibraryIncluded。

POST /api/v1/memory/quick-search
{ "query": "结账日是哪天？", "k": 3, "memoryLibraryId": "<library-id>" }

// 200 响应
{
  "query": "结账日是哪天？",
  "answer": "客户每月 25 日结账。",
  "snippets": [
    { "id": "…", "path": "engineering / billing", "excerpt": "客户每月 25 日结账。", "similarity": 0.91 }
  ]
}

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

POST /api/v1/memory/retrieve
{
  "query": "结账规则",
  "memoryLibraryId": "<primary-library-id>",
  "allAccessible": true,
  "layers": ["recall", "search"],
  "k": 8
}
// 200：recall / search 各含 hits（今日 L2/L3 共享语义引擎，一次 ANN）

MCP 接入

Cursor / Claude Desktop 等 MCP 客户端推荐使用边缘端点 https://mcp.engra.ai/api/v1/memory/mcp（兼容 https://engra.ai/api/v1/memory/mcp）。在 mcp.json 中除 Authorization 外，还需设置 Accept: application/json, text/event-stream 与 Content-Type: application/json（缺省常见 HTTP 406）。先调用 memory_list_libraries 获取 memoryLibraryId，再调用检索或写入工具。团队库检索默认合并 Common Knowledge 共享常识库（可配置关闭）。

https://mcp.engra.ai/api/v1/memory/mcp

兼容旧路径：https://engra.ai/api/v1/memory/mcp

→ 记忆库 MCP 完整文档 · → Common Knowledge 共享常识库

不在本页范围（控制台）

下列能力无 API Key 公开端点，需登录后在控制台使用（底层为 /api/admin/memory/* + Session）：

• 记忆库 — Backlink graph、Layer2 摘要、异步入队任务、控制台写入
• Memory 设置 — verbatim / 摘要模型、摄取队列、LLM Provider