记忆 API 指南

知办AI 的记忆中台（F17）对外开放：召回相关记忆、写入记忆事件。底层引擎（MemMachine）凭证只在 Agent Bus，调用方不持有引擎凭证——和知识库是同一套中转模式。

记忆设计上是「Agent 自己决定何时读写，知办AI服务器只提供干净接口 + 租户隔离 + 审计」：知办AI服务器不自动往 prompt 里塞记忆，调用方（接入方 Agent 服务 / 租户自建 Agent Runtime）在需要时显式调用。

想直接试一下？

API 在线调试 (Scalar) 顶部填 Bearer ek_...，左侧选 memory → Try it out。

能力总览

┌─────────────────────────────────────────────────────────┐
│                  记忆中台 (Memory) 对外能力              │
└─────────────────────────────────────────────────────────┘

   召回           ┌────────────────────────────────┐
   ┌────────────▶│  POST   /memories/recall        │  ← 核心,RAG 式语义召回
   │             └────────────────────────────────┘
   │   写入        ┌────────────────────────────────┐
 你的系统 ───────▶│  POST   /memories/events        │  ← 写一条记忆事件
   │             └────────────────────────────────┘
   │   列举        ┌────────────────────────────────┐
   ├────────────▶│  GET    /memories               │  ← 检视某 scope 下已存记忆
   │             └────────────────────────────────┘
   │   遗忘        ┌────────────────────────────────┐
   └────────────▶│  DELETE /memories/{id}          │  ← 删一条(按归属校验)
                  └────────────────────────────────┘

路径前缀都是 /api/external/v1/memories（下文简写为 /memories）。审计 / 跨用户接口暂未开放，见 路线图。

五维上下文与「谁能决定什么」

记忆按五维上下文 {tenant_id, user_id, agent_id, session_id, group_id} 隔离。关键边界：

维度	谁提供	说明
tenant_id	凭证（token）	永远从 ek_ / st_ 解出，调用方传了也会被忽略，杜绝跨租户伪造
user_id / agent_id / session_id	调用方 body	接入方自有后端按业务传；三者必填
group_id	调用方 body（可选）	群聊场景传真实 group；缺省按 none 处理

tenant 以下的 user/agent/session 由调用方提供后，Agent Bus 注入 scope filter + 对底层引擎返回结果二次过滤，再返回——即便底层引擎漏过滤也不会跨范围泄漏。

鉴权与权限范围

所有记忆接口都需要 Authorization: Bearer <token>，凭证可以是 API Key (ek_) 或 Session Token (st_)，详见 鉴权与凭证。

操作	需要 scope
召回 recall	tenant.memory.read
列举 list	tenant.memory.read
写入 events	tenant.memory.write
遗忘 forget	tenant.memory.write

申请凭证时按最小权限勾选。

记忆作用域（scope）

召回时可用 scopes 收窄范围（只能收窄，不能放大；省略则用平台默认集）：

scope	含义
user_long_term	同租户同用户、跨 agent 的长期记忆
agent_private	同租户同用户同 agent 的私有记忆
session	当前会话内的记忆
group_shared	同 group 内共享的记忆（需传真实 group_id）

SDK 方法映射

Python / Go SDK 都已覆盖本页接口，不想手写 HTTP 时直接用：

SDK 方法	API	用途
client.memory.recall(...)	POST /memories/recall	语义召回相关记忆
client.memory.remember(...)	POST /memories/events	写入一条记忆事件
client.memory.list(...)	GET /memories	列举(检视)某 scope 下记忆
client.memory.forget(id, ...)	DELETE /memories/{id}	删除一条记忆(按归属校验)

SDK 安装与初始化见 自定义 Agent Runtime 接入 · SDK 对外能力。

典型场景

场景 1：接入方 Agent 服务在对话中用记忆

接入方 Agent 服务处理知办AI数字员工会话时，自己决定何时召回、何时写回。

1. 启动时拿 Session Token        POST /oauth/token   (memory.read + memory.write scope)
2. 收到用户提问 → Agent 判断「这可能和历史偏好/事实有关」：
   - 召回相关记忆                POST /memories/recall   (memory.read)
   - 把召回结果作为 context 喂模型（没召回到就别编造）
3. 模型回答；若产生值得记住的事实/偏好：
   - 写入记忆                    POST /memories/events   (memory.write)

召回是 RAG 式核心——返回相关性最高的若干记忆项（含 score）。是否召回、是否写入都由 Agent 决定，平台不强制注入。

场景 2：租户自建 Agent Runtime turn-内自查

租户自建 Agent Runtime 在推理中途想查记忆时，可以用 Agent SDK 凭证换出的短期 st_ 调本页接口。tenant_id 仍从 st_ 解出；user_id / agent_id / session_id 由 Agent 服务按当前会话上下文传入。详见 自定义 Agent Runtime 接入。

完整接口详解

1. 召回记忆（核心）

POST /api/external/v1/memories/recall

给一个 query + 五维里 tenant 以下的标识，返回 top-K 最相关的记忆项。

curl

curl -X POST -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u-123",
    "agent_id": "agt-销售助手",
    "session_id": "sess-abc",
    "query": "用户的付款备注是什么",
    "scopes": ["user_long_term", "session"],
    "limit": 5
  }' \
  https://zhiban.creditease.corp/api/external/v1/memories/recall

Python

res = client.memory.recall(
    user_id="u-123",
    agent_id="agt-销售助手",
    session_id="sess-abc",
    query="用户的付款备注是什么",
    scopes=["user_long_term", "session"],  # 可选,省略用默认集
    limit=5,
)
for item in res.items:
    print(item.score, item.content)
if res.degraded:
    print("注意: 底层引擎部分失败,结果是降级子集")

Go

res, err := client.Memory().Recall(ctx, zhibansdk.RecallRequest{
    UserID:    "u-123",
    AgentID:   "agt-销售助手",
    SessionID: "sess-abc",
    Query:     "用户的付款备注是什么",
    Scopes:    []string{zhibansdk.ScopeUserLongTerm, zhibansdk.ScopeSession},
    Limit:     5,
})

请求字段：

字段	类型	默认	说明
user_id	string	—	必填，目标用户标识
agent_id	string	—	必填，数字员工标识
session_id	string	—	必填，会话标识
group_id	string	none	群聊场景传真实 group
query	string	—	必填，召回查询
scopes	string[]	平台默认集	收窄召回范围；见作用域
limit	int	10	单 scope 召回上限

返回：

{
  "success": true, "code": 200, "data": {
    "items": [
      {
        "id": "mem-a1b2...",
        "content": "用户的付款备注是 codex-pay-0629",
        "score": 0.91
      }
    ],
    "degraded": false
  }
}

degraded: true 表示某些 scope 的底层引擎调用失败，返回的是降级子集——不抛错（避免阻断对话），但调用方应感知结果可能不全。

调优技巧

• query 写具体比写宽泛好（「用户付款备注」优于「备注」）
• 召回结果是 context，不是答案——没召回到就别让模型编造记忆
• 不确定查哪几个 scope 时省略 scopes，用平台默认集

2. 写入记忆事件

POST /api/external/v1/memories/events

写一段自然语言，底层引擎自行抽取 / 沉淀为可召回的记忆。

curl

curl -X POST -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u-123",
    "agent_id": "agt-销售助手",
    "session_id": "sess-abc",
    "content": "请记住用户的付款备注是 codex-pay-0629"
  }' \
  https://zhiban.creditease.corp/api/external/v1/memories/events

Python

client.memory.remember(
    user_id="u-123",
    agent_id="agt-销售助手",
    session_id="sess-abc",
    content="请记住用户的付款备注是 codex-pay-0629",
)

Go

err := client.Memory().Remember(ctx, zhibansdk.WriteRequest{
    UserID:    "u-123",
    AgentID:   "agt-销售助手",
    SessionID: "sess-abc",
    Content:   "请记住用户的付款备注是 codex-pay-0629",
})

请求字段：

字段	类型	默认	说明
user_id / agent_id / session_id	string	—	必填，同召回
group_id	string	none	群聊场景传真实 group
content	string	—	必填，要记住的内容（自然语言）

返回：

{ "success": true, "code": 200, "data": { "ok": true } }

写什么由 Agent 判断

平台不会自动把每轮对话写进记忆。只写真正值得长期记住的事实 / 偏好 / 决定——把每句话都写进去会污染后续召回。

3. 列举记忆（检视）

GET /api/external/v1/memories?user_id=&agent_id=&session_id=&scope=&limit=

列出某 scope 下已存的记忆,用于自查「到底记了啥」。GET 无 body,五维里 tenant 以下的标识走 query 参数。

curl

curl -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/memories?user_id=u-123&agent_id=agt-销售助手&session_id=sess-abc&scope=user_long_term&limit=20"

Python

res = client.memory.list(
    user_id="u-123",
    agent_id="agt-销售助手",
    session_id="sess-abc",
    scope="user_long_term",  # 省略走 user_long_term
    limit=20,
)
for item in res.items:
    print(item.id, item.content)

Go

res, err := client.Memory().List(ctx, zhibansdk.ListRequest{
    UserID:    "u-123",
    AgentID:   "agt-销售助手",
    SessionID: "sess-abc",
    Scope:     zhibansdk.ScopeUserLongTerm,
    Limit:     20,
})

查询参数：user_id / agent_id / session_id 必填;scope 省略走 user_long_term;limit 默认 10。返回结构同召回(items[{id, content, score}] + degraded),id 可直接用于下面的遗忘。

4. 遗忘记忆

DELETE /api/external/v1/memories/{id}?user_id=&agent_id=&session_id=

按 id(先前召回 / 列举拿到的)删除一条记忆。id 走 path,五维里 tenant 以下的标识走 query。

curl

curl -X DELETE -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/memories/mem-a1b2?user_id=u-123&agent_id=agt-销售助手&session_id=sess-abc"

Python

res = client.memory.forget(
    "mem-a1b2",
    user_id="u-123", agent_id="agt-销售助手", session_id="sess-abc",
)
print(res)  # {"deleted": 1, "rejected": 0}

Go

res, err := client.Memory().Forget(ctx, "u-123", "agt-销售助手", "sess-abc", "", "mem-a1b2")

返回 { "deleted": <实删数>, "rejected": <被拒数> }。

归属校验,不是有 id 就能删

服务端会先在本租户本用户范围内确认这个 id 确实属于你,才真正删除;不属于你的 id(别人的 / 不存在 / 跨 scope)计入 rejected,不会被删。所以拿到别人的 id 也删不掉别人的记忆。

错误处理

HTTP	code	含义	怎么处理
401	invalid_api_key / invalid_session_token	凭证不对 / 已撤销 / 过期	后台查凭证状态；Session Token 重新换
403	scope_denied	凭证范围不含 tenant.memory.read / write	改 API Key 的 scope 或换一把
400	invalid_params	缺 user_id / agent_id / session_id / query / content	看 message 字段定位
429	rate_limited	触发限流	退避重试，遵守 Retry-After 头
500	internal_error	服务端异常	联系运维，附上响应里的 traceId
503	service_unavailable	底层引擎不可用	召回会降级返回（degraded: true）；写入可退避重试

401 错误不暴露具体原因

出于安全（防爆破），401 统一返 invalid api key / invalid session token，不区分「不存在」/「过期」/「撤销」。本地排查时对照后台凭证状态。

限流与配额

维度	默认配额
单 API Key	100 QPS
单 Session Token	50 QPS
同租户聚合	500 QPS
召回 limit	1-50

超限返 429 rate_limited，响应头 Retry-After 给建议退避秒数。需要更高配额联系运维提配。

最佳实践

1. 鉴权与隔离

• 生产用 HTTPS，HTTP 仅限本地测试
• API Key 放环境变量 / Vault / KMS，不要进 Git
• 不要在 body 里传 tenant_id——传了也会被忽略；tenant 由凭证决定
• 按最小权限勾 scope——只召回就别勾 tenant.memory.write

2. 召回

• 由 Agent 按需召回，别每轮都召回（浪费 token、污染上下文）
• query 写具体；没召回到结果时别编造记忆
• 关注 degraded 标记，降级时结果可能不全

3. 写入

• 只写值得长期记住的事实 / 偏好 / 决定
• 写入失败（5xx / 503）做退避重试；不要把失败当致命错误阻断对话

路线图

后端尚未实现的能力（仅 docs 不够，需要研发补）：

能力	影响	优先级
GET /memories/audit 记忆操作审计	合规追溯（需先在服务端发审计事件）	中
跨用户记忆审计接口（对齐 KB 场景 3）	租户管理员审计	中
group 冲突裁决 / 晋升到用户长期记忆	多 Agent 群聊记忆治理	中
gRPC / MCP 协议入口	多协议统一（ADR-0029）	低

跟产品对优先级时把上面列出来。

相关链接

• 知识库 API 指南 — 同套中转模式，可对照
• API 列表 — 全部对外接口（含鉴权 / 路线图）
• API 在线调试 (Scalar) — 浏览器里发请求
• 鉴权与凭证 — API Key vs Session Token / 错误码
• 自定义 Agent Runtime 接入 — Session Token + backchannel 工具的完整流程
• F17 · 统一记忆中台 — 架构与设计权威