Memory API 实战

Memory 子系统的 HTTP 请求示例：按层写入、查询、搜索、删除、清空、计数、GC 和 Digest。

核心概念

Memory 使用**层（Layer）**而非 scope 提问。七值闭域：

层	含义	可写
`environment`	宿主环境信息	❌（感知器产出）
`consensus`	部门/团队共识	✅（需 admin）
`about_me`	关于我的偏好	✅
`agent_memory`	角色记忆	✅
`session`	会话态	❌（运行时态）
`working`	工作缓存	❌（运行时态）
`unknown`	未识别	❌

1. 保存记忆（按层写入）

POST /cells/{cellID}/memory
Content-Type: application/json

{
  "layer": "about_me",
  "kind": "preference",
  "content": "用户偏好使用 Dark Mode",
  "namespace": ""
}

约束：

environment / session / working 不可写 → ErrLayerNotWritable
consensus 带 actor → ErrLayerShared
agent_memory 空 namespace → ErrLayerNamespaceRequired

2. 列出记忆（按层查询）

GET /cells/{cellID}/memory?layer=about_me&limit=20&offset=0&actor=alice

参数说明：

layer：按层过滤（下推到引擎 SQL，不在客户端过滤）
actor：仅对 admin token 生效，非 admin 取 Principal.Actor
layer 与 scope 同时给出 → ErrMemoryLayerScopeConflict（400）

3. 语义搜索

POST /cells/{cellID}/memory/search
Content-Type: application/json

{
  "query": "编辑器配置偏好",
  "layer": "about_me",
  "limit": 10
}

4. 获取单条

GET /cells/{cellID}/memory/{id}?actor=alice

不存在与不属于你同返 404（记忆 id 会随导出流出，一次读不配得到"它确实存在"的确认）。

5. 删除单条

DELETE /cells/{cellID}/memory/{id}

不属于你返回 403，不存在幂等成功。

6. 清空层

DELETE /cells/{cellID}/memory/layer?layer=about_me&actor=alice

非共享层必须带 actor。不可写的层不许清。

7. 分层计数

GET /cells/{cellID}/memory/counts?actor=alice

返回结果键覆盖全部七层含 0：

{
  "environment": 12,
  "consensus": 3,
  "about_me": 8,
  "agent_memory": 25,
  "session": 0,
  "working": 0,
  "unknown": 0
}

8. 触发 GC

POST /cells/{cellID}/memory/gc

GC 使用 recall-frequency weighted 淘汰（RetentionScore），不是纯 LRU（INV-MEM-26）。

9. 触发 Digest

POST /cells/{cellID}/memory/digest

Digest 执行：BM25 语义去重、冲突检测（detectSupersession）、stale 标记（30+ 天零召回）、条目晋升。

10. 记忆导入

POST /cells/{cellID}/memory
Content-Type: application/json

{
  "layer": "agent_memory",
  "kind": "fact",
  "content": "项目使用 Go 1.22 + React 19",
  "namespace": "code-agent"
}

导入只接受可写层（consensus / about_me / agent_memory）。