分层模型
写入与检索前先理解四层结构：
- Persona
- 谁的记忆（团队默认可不传，由平台绑定）
- Scope
- 粗领域，如 engineering、finance
- Topic
- 领域内话题，如 billing、api-auth
- Atom
- 一条可检索的记忆单元（正文 + 可选附件）
记忆栈（检索模式）
- POST /search — L3 深度语义搜索
- POST /recall — L2 按需召回（可带 scope / topic / persona 过滤）
- POST /wake-up — L0+L1 会话唤醒上下文
鉴权
请求头 Authorization: Bearer <API_KEY>，Scope 需包含 memory:read 或 memory:write。
/api/v1/memory
端点
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /api/v1/memory/atoms | memory:write | 创建 Atom |
| GET | /api/v1/memory/atoms | memory:read | 分页列出 Atom |
| POST | /api/v1/memory/search | memory:read | L3 搜索 |
| POST | /api/v1/memory/recall | memory:read | L2 召回 |
| POST | /api/v1/memory/wake-up | memory:read | 唤醒记忆栈 |
创建 Atom（JSON）
POST /api/v1/memory/atoms
Content-Type: application/json
{
"scope": "engineering",
"topic": "billing",
"document": "客户每月 25 日结账。"
}
// 201 响应（单节点或多节点）
{
"atom": { "id": "…", "scope": "…", "topic": "…", "persona": "…", "document": "…", "metadata": {}, "createdAt": "…" },
"atoms": [ "…全部落盘的 Atom；多 scope/topic 时可能 >1" ]
}multipart/form-data：字段 atom 为 JSON 字符串（含 scope、topic、document），file 为可选附件。遗留路径 /drawers 与 /atoms 行为相同。
异步写入（202）
平台开启摄取队列时，POST /atoms 默认返回 202 Accepted（verbatim 在后台执行）。需要立即拿到落盘结果时用 ?sync=1；显式禁用异步用 ?async=0。任务状态仅在控制台 Admin API 查询；集成方也可稍后 GET /atoms 确认。
// 202 响应（队列已启用）
{
"async": true,
"queue": { "enabled": true, "driver": "local" },
"job": {
"id": "…",
"status": "queued",
"generateMemoryNodes": true,
"scope": "engineering",
"topic": "billing"
}
}
// 同步成功仍为 201，结构与上文 writeJson 示例相同列出 Atom
GET /api/v1/memory/atoms?offset=0&limit=50&persona=<可选>
搜索示例
POST /api/v1/memory/search
{ "query": "结账规则", "k": 8, "scope": "engineering", "topic": "billing" }不在本页范围（控制台）
下列能力无 API Key 公开端点，需登录后在控制台使用（底层为 /api/admin/memory/* + Session）：
开发者实现字段映射（character / wing / room / drawer）见仓库内 packages/agent-memory/docs/技术说明.md §2.0 与 docs/agent-memory-技术说明.md。