ContextDB Data API 记忆管理-云数据库 RDS(RDS)-阿里云帮助中心

本文介绍RDS ContextDB的记忆管理Data API，包括记忆写入与检索、实体卡管理、记忆演进和自定义提示词。

公共信息

基础地址

https://context-database.aliyuncs.com

鉴权方式

所有数据面接口通过workspace级API Key鉴权，以下三种方式任选其一：

方式	Header格式
X-API-Key	`X-API-Key: <YOUR_API_KEY>`
Bearer	`Authorization: Bearer <YOUR_API_KEY>`
Token	`Authorization: Token <YOUR_API_KEY>`

说明

workspace_id 与 member_id 由服务端从API Key鉴权上下文注入，任何接口的请求参数中都不接受、也不能覆盖这两个字段。mem0口径的 user_id / agent_id / app_id / run_id 只是业务作用域标识（meta），不代表租户成员身份。

响应结构

数据面接口有两种响应形态：

mem0兼容接口（/v3/memories/*、/v1/memories/{id} 系列、session-context、dream、entities 查询、entity-relations）直接返回业务JSON，无外层信封。
统一信封接口（BatchDeleteMemories、CreateEntity、UpdateEntity、custom_prompt 系列）返回如下信封，业务数据在 data 中；下文这些接口的「返回参数」只列 data 内字段。

名称	类型	描述	示例值
errorCode	integer	整数错误码，成功固定为 `0`；失败为非 `0` 的服务端错误码	`0`
errorMessage	string	错误描述，成功时为 `null`	`null`
requestId	string	请求ID，排查问题时提供	`a1b2c3d4-...`
data	object	业务数据，无数据时为 `null`	见各接口

说明

失败时 errorCode 取服务端错误码整数（1000 内部错误、1001 参数错误、1003 冲突、2001 记忆不存在、4001~4008 鉴权失败等），errorMessage 形如 COMMON_BAD_REQUEST: bad request，data 为 null。信封形态只覆盖 custom_prompt 系列、session-context、dream、entities 这几个路径；其余mem0兼容路径（/v3/memories/*、/v1/memories/{id}、entity-relations、按ID批量删除等）的错误响应为 {"detail": "..."}，不含 errorCode。

Data API概览

下表列出本文介绍的接口及其功能概述。

API	描述
AddMemories	向ContextDB写入对话消息并异步提取记忆。
GetMemories	分页查询记忆。
SearchMemories	根据 `query` 和作用域执行语义或Agent-based检索。
GetMemory	查询单条记忆详情，返回当前成员可访问的记忆对象。
UpdateMemory	更新单条记忆文本、元数据或业务时间戳。
DeleteMemory	删除单条记忆。
DeleteMemories	按作用域批量删除记忆。
BatchDeleteMemories	按ID批量删除记忆。
GetMemoryHistory	按记忆ID返回创建和更新历史，响应为裸数组（不含分页信封）。
SessionContext	返回适合零查询注入的上下文信息：当前作用域下名为 `User` 的用户实体卡，以及按 `final_score` 降序的top-N实体卡。
TriggerDream	为当前成员触发一次记忆Dream演进任务。
ListEntities	列出或检索记忆实体卡，有两种互斥模式：。
CreateEntity	插入人工记忆实体卡。
UpdateEntity	按稳定 `entity_id` 更新人工记忆实体卡，字段级替换语义：传了即整体替换，没传不动。
ListEntityRelations	返回记忆知识图谱中的实体和关系（与知识库/文档图谱无关）。
GetCustomPrompt	查询当前成员的自定义记忆提取提示词。
PutCustomPrompt	创建或覆盖当前成员的记忆提取提示词。
DeleteCustomPrompt	删除当前成员配置的记忆提取提示词，接口幂等：未配置时同样返回成功。

Memory API

说明

接口路径通常兼容有无尾部 / 的形式，本文采用请求语法所示的标准路径。

AddMemories

接口说明

向ContextDB写入对话消息并异步提取记忆。至少提供 user_id、agent_id、app_id 或 run_id 中的一个作用域。接口同步写入原始会话切片后立即返回 event_id，事实提取在后台完成，可用 GET /v1/event/{event_id} 轮询进度。

请求语法

POST /v3/memories/add

请求参数

名称	类型	必填	描述	示例值
messages	array	是	对话消息列表，每项含 `role` 和 `content`，二者均不可为空，否则返回400	`[{"role":"user","content":"我叫张三"}]`
user_id	string	否*	应用内用户标识	`user-001`
agent_id	string	否*	Agent标识	`agent-chat`
app_id	string	否*	应用标识	`app-main`
run_id	string	否*	运行标识	`run-abc123`
metadata	object	否	自定义元数据，随记忆存储并在查询时回显	`{"channel":"app"}`
infer	boolean	否	是否推理提取事实，默认 `true`；`false` 表示直接存储	`true`
memory_type	string	否	记忆分类透传	`preference`
source_type	string	否	消息来源，取值 `user`/`assistant`/`user+assistant`；未传时按消息的 `role` 自动派生（全为user → `user`，全为assistant → `assistant`，两者混合 → `user+assistant`），非法值返回400	`user`
custom_instructions	string	否	自定义提取指令，补充引导记忆提取	`请重点关注用户偏好`
timestamp	string	否	ISO-8601时间串或Unix时间戳，映射到记忆 `record_time`；无法解析返回400	`2026-07-01T08:00:00Z`

说明

Scope约束：user_id/agent_id/run_id/app_id 至少出现一个，否则返回400。

返回参数

名称	类型	描述	示例值
message	string	操作结果描述	`Memory processing has been queued for background execution`
status	string	事件状态	`PENDING`
event_id	string	异步事件ID，可用于轮询进度	`evt-abc123`

GetMemories

接口说明

分页查询记忆。该端点只按filters、时间区间和分页参数列出记忆，不执行写入或语义检索；写入记忆请使用 /v3/memories/add，语义检索请使用 /v3/memories/search。

请求语法

POST /v3/memories

请求参数

名称	类型	必填	描述	示例值
filters	object	是*	过滤对象，支持 `user_id`/`agent_id`/`app_id`/`run_id`、时间区间和高级过滤语法	`{"user_id":"user-001"}`
page	integer	否	页码，默认 `1`，小于1时按1处理；可放query或body，query优先	`1`
page_size	integer	否	每页条数，默认 `100`，自动钳制到 `[1, 200]`（越界不报错）；可放query或body，query优先	`20`
start_date	string	否	起始日期，等价于 `created_at >=`（也可放在filters内，filters内优先）	`2026-01-01`
end_date	string	否	结束日期，等价于 `created_at <=`（也可放在filters内，filters内优先）	`2026-07-01`
filters.keyword	string	否	关键词过滤，必须与 `filters.mode` 成对出现；按分词后的连续短语匹配记忆内容	`咖啡`
filters.mode	string	否	关键词匹配模式，当前仅支持 `fuzzy`，其他值返回400	`fuzzy`
filters.created_at	object / string	否	时间区间，支持 `gte`/`gt`/`lte`/`lt`（同时接受 `$gte`、`>=` 等写法）；传标量时表示精确匹配该时刻	`{"gte":"2026-01-01"}`
sort_by	string	否	排序字段，仅支持通过query string传入（放在请求体内无效）；当前仅接受 `importance`，其他值返回400	`importance`
sort_order	string	否	排序方向，仅支持通过query string传入；`asc` 或 `desc`，默认 `desc`；只传 `sort_order` 不传 `sort_by` 返回400	`desc`

返回参数

名称	类型	描述	示例值
count	integer	满足条件的总条数	`42`
next	string	下一页query串，无下一页为 `null`	`?page=2&page_size=10`
previous	string	上一页query串，无上一页为 `null`	`null`
results	array	记忆列表，元素结构见下表	见下表

results数组元素

名称	类型	描述	示例值
id	string	记忆ID	`mem-8f3a...`
memory	string	记忆内容	`用户喜欢喝手冲咖啡`
hash	string	内容哈希，缺失时不返回	`9c1f...`
created_at	string	创建时间	`2026-07-01T08:00:00Z`
updated_at	string	更新时间，必返；缺失时兜底为 `created_at`	`2026-07-02T09:10:00Z`
importance	float	重要度，缺失时不返回	`0.8`
user_id	string	应用内用户标识，缺失时不返回	`user-001`
agent_id	string	Agent标识，缺失时不返回	`agent-chat`
run_id	string	运行标识，缺失时不返回	`run-abc123`
categories	array	记忆分类，必返；无分类时为空数组	`["preference"]`
metadata	object	元数据，必返；强制包含 `user_id`/`agent_id`/`app_id`/`run_id` 四个键（缺失为 `null`）	`{"user_id":"user-001","agent_id":null,"app_id":null,"run_id":null}`
recall_count	integer	累计召回次数，无统计时为 `0`	`3`
recall_count_7d	integer	近7天召回次数	`1`
recall_count_30d	integer	近30天召回次数	`2`
last_recalled_at	string	最近召回时间，从未召回为 `null`	`2026-08-20T03:00:00Z`
source_chunk_id	string	来源会话切片ID，缺失时不返回	`chunk-001`
evidence_type	string	证据类型，缺失时不返回	`source_chunk_linked`
match_sources	array	命中来源，缺失时不返回	`["vector"]`
source_excerpt	string	来源原文摘录，缺失时不返回	`我平时只喝手冲`
source_created_at	string	来源创建时间，缺失时不返回	`2026-07-01T07:59:00Z`
candidate_type	string	候选类型，缺失时不返回	`memory`

说明

filters高级语法：支持 AND / OR（值为条件对象数组）与 NOT（值为条件对象）嵌套；字段值支持比较运算符 in、gte、lte、gt、lt、ne、contains、icontains（gte/lte/gt/lt/ne 同时接受 $ 前缀写法），数组值等价于 in，值为 "*" 表示该字段存在即匹配。可直接过滤的顶层字段：user_id、agent_id、app_id、run_id、status、doc_type、hash、batch_id、level、source_type、memory_type、created_at、updated_at；categories 会同时匹配顶层与 metadata.categories；其余键一律按 metadata.<key> 解析。

SearchMemories

接口说明

根据 query 和作用域执行语义或Agent-based检索。顶层 user_id/agent_id/app_id/run_id 与非空 filters 互斥，同时提供返回400。

请求语法

POST /v3/memories/search

请求参数

名称	类型	必填	描述	示例值
query	string	是	检索查询，为空返回400	`用户的咖啡偏好`
filters	object	否*	过滤对象，支持逻辑组合与比较运算符，语法同GetMemories	`{"user_id":"user-001"}`
top_k	integer	否	返回条数，默认 `10`；负数或大于 `1000` 返回400；传 `0` 直接返回空列表	`5`
threshold	float	否	相似度阈值，默认 `0.5`，必须在 `[0, 1]` 内，越界返回400；传 `0.0` 禁用过滤	`0.3`
method	string	否	检索模式：`semantic`（默认）或 `agentic`，其他值返回400	`semantic`
rerank	boolean	否	是否启用重排，默认 `true`；`false` 跳过重排	`true`

说明

使用filters指定作用域时，其中的 user_id、agent_id、run_id、app_id 至少提供一个，否则返回HTTP 400。

返回参数

名称	类型	描述	示例值
results	array	检索结果列表，元素结构随 `method` 不同，见下表	见下表

results数组元素（method=semantic）

名称	类型	描述	示例值
id	string	记忆ID	`mem-8f3a...`
memory	string	记忆内容	`用户喜欢喝手冲咖啡`
hash	string	内容哈希，缺失时不返回	`9c1f...`
score	float	相似度得分，保留2位小数	`0.87`
created_at	string	创建时间，截断到整秒	`2026-07-01T08:00:00Z`
updated_at	string	更新时间，截断到整秒	`2026-07-02T09:10:00Z`
categories	array	记忆分类，无分类时为空数组	`["preference"]`
metadata	object	元数据，必含四个作用域键（缺失为 `null`）	`{"user_id":"user-001","agent_id":null,"app_id":null,"run_id":null}`

说明

top_k >= 4 且有命中结果时，可能在结果列表首位插入一条实体卡增强项：memory 为实体卡核心信息的JSON字符串（含 entity_name/entity_type/attributes/relations_summary），categories 为 [ ]，metadata 中仅 agent_id 可能非空。插入后整体仍截断到 top_k 条。

results数组元素（method=agentic，固定返回单条合成结果）

名称	类型	描述	示例值
id	string	合成结果ID，固定 `agentic:` 前缀	`agentic:1f2e3d`
memory	string	Agent合成的召回结论	`用户偏好手冲咖啡，不喝速溶`
event	string	固定为 `AGENTIC_RECALL`	`AGENTIC_RECALL`
score	float	固定为 `1.0`	`1.0`
member_id	string	当前成员ID（由服务端注入）	`member-001`
metadata	object	含 `method`、`mode` 与四个作用域键	`{"method":"agentic","mode":"agent_recall","user_id":"user-001","agent_id":null,"app_id":null,"run_id":null}`

GetMemory

接口说明

查询单条记忆详情，返回当前成员可访问的记忆对象。记忆不存在、不属于当前成员、已删除或非记忆类型文档，均返回404。该接口不返回召回统计字段（recall_count 等仅在GetMemories列表中富化）。

请求语法

GET /v1/memories/{id}

请求参数

名称	类型	必填	描述	示例值
id	string	是	路径参数，记忆ID	`mem-8f3a...`

返回参数

名称	类型	描述	示例值
id	string	记忆ID	`mem-8f3a...`
memory	string	记忆内容	`用户喜欢喝手冲咖啡`
hash	string	内容哈希，缺失时不返回	`9c1f...`
created_at	string	创建时间	`2026-07-01T08:00:00Z`
updated_at	string	更新时间，必返；缺失时兜底为 `created_at`	`2026-07-02T09:10:00Z`
importance	float	重要度，缺失时不返回	`0.8`
user_id	string	应用内用户标识，缺失时不返回	`user-001`
agent_id	string	Agent标识，缺失时不返回	`agent-chat`
run_id	string	运行标识，缺失时不返回	`run-abc123`
categories	array	记忆分类，必返；无分类时为空数组	`["preference"]`
metadata	object	元数据，必返；强制包含四个作用域键（缺失为 `null`）	`{"user_id":"user-001","agent_id":null,"app_id":null,"run_id":null}`

说明

溯源类可选字段 source_chunk_id、evidence_type、match_sources、source_excerpt、source_created_at、candidate_type 与GetMemories的results元素一致，存在时返回。

UpdateMemory

接口说明

更新单条记忆文本、元数据或业务时间戳。text、metadata、timestamp 至少提供一个，全部缺失返回400；记忆不存在或不属于当前成员返回404。metadata 为合并语义（与现有元数据逐键覆盖，未提供的键保留），不是整体替换。传入 text 会重算内容哈希与向量，并把记忆演进阶段回退到 refined、清空已关联实体，等待下一次Dream重新抽取。

请求语法

PUT /v1/memories/{id}

请求参数

名称	类型	必填	描述	示例值
id	string	是	路径参数，记忆ID	`mem-8f3a...`
text	string	否*	新的记忆内容	`用户喜欢喝拿铁`
metadata	object	否*	元数据，按键合并到现有元数据	`{"channel":"app"}`
timestamp	string	否*	ISO-8601时间串或Unix时间戳，写入 `record_time`；无法解析返回400	`2026-07-01T08:00:00Z`

说明

*text / metadata / timestamp 至少提供一个，否则返回400。

返回参数

名称	类型	描述	示例值
id	string	记忆ID	`mem-8f3a...`
memory	string	更新后的记忆内容	`用户喜欢喝拿铁`
text	string	与 `memory` 同值，mem0兼容字段	`用户喜欢喝拿铁`
hash	string	内容哈希，`text` 变更后同步刷新	`7be2...`
created_at	string	创建时间	`2026-07-01T08:00:00Z`
updated_at	string	更新时间	`2026-08-28T10:00:00Z`
categories	array	记忆分类	`["preference"]`
metadata	object	合并后的元数据，必含四个作用域键	`{"channel":"app","user_id":"user-001","agent_id":null,"app_id":null,"run_id":null}`

说明

其余可选字段（importance、顶层 user_id/agent_id/run_id、溯源类字段）与GetMemory一致。

DeleteMemory

接口说明

删除单条记忆。接口先校验归属，再下发删除事件由后台异步硬删除，因此返回成功后短时间内仍可能查到该记忆。记忆不存在、不属于当前成员或已删除返回404。

请求语法

DELETE /v1/memories/{id}

请求参数

名称	类型	必填	描述	示例值
id	string	是	路径参数，记忆ID	`mem-8f3a...`

返回参数

名称	类型	描述	示例值
message	string	操作结果描述	`Memory deleted successfully!`

DeleteMemories

接口说明

按作用域批量删除记忆。Query参数 user_id、agent_id、app_id、run_id 至少提供一个，否则返回400。删除范围恒定收敛在当前成员内，实际删除由后台事件异步执行，接口只返回受理结果，不返回 event_id。

请求语法

DELETE /v1/memories

请求参数

名称	类型	必填	描述	示例值
user_id	string	否*	Query参数，应用内用户标识	`user-001`
agent_id	string	否*	Query参数，Agent标识	`agent-chat`
app_id	string	否*	Query参数，应用标识	`app-main`
run_id	string	否*	Query参数，运行标识	`run-abc123`

说明

* 四个参数至少提供一个，全部缺失返回400 At least one identifier is required.。

返回参数

名称	类型	描述	示例值
message	string	操作结果描述	`All relevant memories deleted`

BatchDeleteMemories

接口说明

按ID批量删除记忆。请求体 ids 必填，单次最多50条，超出返回400；整批只下发一个删除事件，逐条校验结果在 data.results 中返回，部分失败不影响其他条目。响应使用统一信封结构。

请求语法

DELETE /v1/memories/batch

请求参数

名称	类型	必填	描述	示例值
ids	array	是	待删除的记忆ID列表，至少1条、最多50条；元素自动trim，含空白项返回400；重复ID自动去重	`["mem-1","mem-2"]`

返回参数

以下为 data 内字段，外层信封见「响应结构」。

名称	类型	描述	示例值
total	integer	去重后处理的ID总数	`2`
succeeded	integer	成功受理条数	`1`
failed	integer	失败条数	`1`
results	array	逐条结果，元素结构见下表	见下表

results数组元素

名称	类型	描述	示例值
id	string	记忆ID	`mem-1`
success	boolean	该条是否受理成功	`true`
error	string	失败原因，成功时不返回；取值 `not found`（不存在或不属于当前成员）、`not a memory document`、`already deleted`	`not found`

GetMemoryHistory

接口说明

按记忆ID返回创建和更新历史，响应为裸数组（不含分页信封）。当前实现为MVP：基于记忆当前文档合成一条历史记录，尚未接入完整版本追踪。记忆不存在时返回空数组 [ ] 而非404；存在但不属于当前成员返回404。

请求语法

GET /v1/memories/{id}/history

请求参数

名称	类型	必填	描述	示例值
id	string	是	路径参数，记忆ID	`mem-8f3a...`

返回参数

数组元素结构如下：

名称	类型	描述	示例值
id	string	历史记录ID，格式为 `{memory_id}:history:add`	`mem-8f3a:history:add`
memory_id	string	记忆ID	`mem-8f3a`
old_memory	string	变更前内容，当前实现恒为 `null`	`null`
new_memory	string	变更后内容	`用户喜欢喝手冲咖啡`
event	string	事件类型，已删除记忆为 `DELETE`，否则 `ADD`	`ADD`
created_at	string	创建时间	`2026-07-01T08:00:00Z`
updated_at	string	更新时间	`2026-07-02T09:10:00Z`
is_deleted	boolean	是否已删除	`false`
actor_id	string	行为主体ID，无则为 `null`	`null`
role	string	消息角色，缺失时回落 `source_type`	`user`
input	array	原始 `messages`，无则为 `null`	`[{"role":"user","content":"我叫张三"}]`

SessionContext

接口说明

返回适合零查询注入的上下文信息：当前作用域下名为 User 的用户实体卡，以及按 final_score 降序的top-N实体卡。适用于Session启动时一次性注入记忆背景。该接口不做作用域必填校验，user_id/agent_id 全部缺失时按当前成员的全量可见范围取卡。

请求语法

POST /v1/memories/session-context

请求参数

名称	类型	必填	描述	示例值
user_id	string	否	应用内用户标识，用于限定实体卡范围	`user-001`
agent_id	string	否	Agent标识，用于限定实体卡范围	`agent-chat`
top_n	integer	否	返回实体卡数量，请求体未传时默认 `10`；服务端不做上下限校验、不截断，原值直接作为ES查询的size下传	`5`

说明

top_n 没有取值范围校验：传 0 时 entity_cards 为空数组、total_entities 为 0（user_card 仍照常返回）；负数或超大值也不会返回400，而是原样下传ES，被ES拒绝时表现为500（errorCode1000）。

返回参数

名称	类型	描述	示例值
user_card	object	名为 `User` 的用户实体卡原文；不存在时为 `null`	`{"entity_name":"User","attributes":["偏好手冲咖啡"]}`
entity_cards	array	top-N实体卡原文列表，按 `final_score` 降序	`[{"entity_name":"张三"}]`
total_entities	integer	本次返回的实体卡条数（等于 `entity_cards` 长度，不是全量总数）	`5`

说明

user_card 与 entity_cards 返回的是实体卡存储文档原文（含 entity_name、entity_type、attributes、relations_summary 等），字段集合与ListEntities的规范化输出不完全一致。

TriggerDream

接口说明

为当前成员触发一次记忆Dream演进任务。请求体可选（可整体省略），当前只消费 agent_id；agent_id 为空或空白时按member级别触发。任务异步执行，接口只返回事件受理信息。

请求语法

POST /v1/memories/dream

请求参数

名称	类型	必填	描述	示例值
agent_id	string	否	限定演进范围的Agent标识；为空或未传时按member级别触发	`agent-chat`

说明

请求体整体可省略。member_id 由服务端按API Key注入，请求体中不可传。

返回参数

名称	类型	描述	示例值
message	string	操作结果描述	`Dream event dispatched`
event_id	string	异步事件ID，可用于轮询进度	`evt-abc123`
member_id	string	当前成员ID（服务端注入）	`member-001`
agent_id	string	本次生效的Agent标识；按member级别触发时为 `null`	`agent-chat`

ListEntities

接口说明

列出或检索记忆实体卡，有两种互斥模式：

列表模式（keyword 为空）：分页返回，排除archived与无属性无关系的空壳卡；默认按创建时间倒序（created_at DESC，同值时按 entity_name 升序兜底），可用 sortBy/order 改变排序。
检索模式（keyword 非空）：按实体名称检索，exact 为大小写敏感精确匹配，fuzzy 为大小写不敏感模糊匹配（默认 fuzzy）；结果按 entity_name 升序稳定排序（同值按 entity_id 升序兜底，与检索相关性无关），sortBy/order 被忽略；from/size 生效做分页（size 钳制到 [1, 100]，from 钳制到 [0, 9900]，越界值自动钳制不报错），不传时默认返回前100条；total 为满足条件的真实命中总数，命中超过单页上限时 total 大于本页返回条数。

请求语法

GET /v1/memories/entities

请求参数

名称	类型	必填	描述	示例值
from	integer	否	起始偏移，默认 `0`；检索模式下生效并钳制到 `[0, 9900]`	`0`
size	integer	否	返回数量，默认 `500`；检索模式下生效并钳制到 `[1, 100]`	`100`
keyword	string	否	实体名称关键词；非空即切换为检索模式	`张三`
mode	string	否	检索匹配方式，`exact` 或 `fuzzy`，默认 `fuzzy`，其他值返回400	`fuzzy`
user_id	string	否	应用内用户ID过滤	`user-001`
agent_id	string	否	Agent ID过滤	`agent-chat`
app_id	string	否	应用ID过滤，仅检索模式生效	`app-main`
run_id	string	否	运行标识过滤，仅检索模式生效	`run-abc123`
sortBy	string	否	列表模式排序字段，camelCase：`createdAt`/`updatedAt`/`entityName`/`entityType`/`hotnessScore`/`finalScore`/`hitCount`/`importance`；未传默认 `createdAt`，非法值返回400；检索模式下忽略	`finalScore`
order	string	否	列表模式排序方向，`asc` 或 `desc`，默认 `desc`，非法值返回400；检索模式下忽略	`desc`

说明

sortBy 与 order 使用camelCase，与本接口其余snake_case参数不同，这是与管控台实体列表对齐的历史约定。

返回参数

名称	类型	描述	示例值
entities	array	实体卡列表，元素结构见下表	见下表
total	integer	满足条件的总条数；检索模式下命中超过单页上限时大于本页返回条数	`12`

entities数组元素

名称	类型	描述	示例值
id	string	存储文档ID	`card-9a8b...`
entity_id	string	稳定实体ID，改名与改类型均不变	`ent-0f21...`
entity_name	string	实体名称	`张三`
entity_type	string	实体类型	`person`
attributes	array	属性列表，缺失时不返回	`["偏好手冲咖啡"]`
state	string	卡状态	`active`
hotness_score	float	热度分，缺失时不返回	`1.5`
final_score	float	综合分，输出层保留2位小数（`HALF_UP`），缺失时不返回	`0.86`
importance	float	重要度，建卡初始值（用户实体 `1.0`，其他 `0.5`），缺失时不返回	`0.5`
hit_count	integer	命中次数，建卡初始化为 `0`（检索回写尚未启用），老卡缺字段时不返回	`0`
aliases	array	别名列表，缺失时不返回	`["小张"]`
relations_summary	string	关系摘要，缺失时不返回	`与李四是同事`
user_id	string	应用内用户标识，为空时不返回	`user-001`
agent_id	string	Agent标识，为空时不返回	`agent-chat`
app_id	string	应用标识，为空时不返回	`app-main`
run_id	string	运行标识，为空时不返回	`run-abc123`
source	string	卡来源，`manual` 为人工卡，自动卡由Dream管线生成	`manual`
updated_at	string	更新时间，ISO-8601 UTC，缺失时不返回	`2026-08-20T03:00:00Z`
match_type	string	仅检索模式返回，命中方式	`exact`

说明

四个业务meta（user_id/agent_id/app_id/run_id）只有人工卡（source=manual）才会有非空值并输出。

CreateEntity

接口说明

插入人工记忆实体卡。entity_name 归一化后命中当前成员下任何已有卡（不论 entity_type，含自动卡）时返回409并携带已有卡的 entity_id/entity_type（幂等更新请走PUT）；未命中才建卡。同名唯一性在多节点并发极端窗口内为best-effort，同名扫描上限500张；embedding失败整体失败，可安全重试。请求体不可携带、不可覆盖 workspace_id / member_id。写入的卡为人工卡，Dream/evolve管线对其值做保护。

请求语法

POST /v1/memories/entities

请求参数

名称	类型	必填	描述	示例值
entity_name	string	是	实体名称，1-128字符	`张三`
entity_type	string	是	实体类型，1-64字符	`person`
attributes	array	是	属性列表，1-200条；每项trim后非空，单条最长20480字符（下游LLM场景消费时单条截断至512）	`["偏好手冲咖啡"]`
aliases	array	否	别名列表，最多20条，每条上限128字符；按小写去重	`["小张"]`
user_id	string	否*	应用内用户标识	`user-001`
agent_id	string	否*	Agent标识	`agent-chat`
app_id	string	否*	应用标识	`app-main`
run_id	string	否*	运行标识	`run-abc123`

说明

*user_id/agent_id/app_id/run_id 至少一个非空，否则返回400。

返回参数

以下为 data 内字段，外层信封见「响应结构」。

名称	类型	描述	示例值
entity_id	string	稳定实体ID	`ent-0f21...`
entity_name	string	实体名称	`张三`
entity_type	string	实体类型	`person`
aliases	array	别名列表	`["小张"]`
attributes	array	属性列表	`["偏好手冲咖啡"]`
user_id	string	应用内用户标识	`user-001`
agent_id	string	Agent标识	`agent-chat`
app_id	string	应用标识	`app-main`
run_id	string	运行标识	`run-abc123`
created	boolean	本接口恒为 `true`（新建卡）	`true`
created_at	string	创建时间，ISO-8601 UTC	`2026-08-28T10:00:00Z`
updated_at	string	更新时间，ISO-8601 UTC	`2026-08-28T10:00:00Z`

UpdateEntity

接口说明

按稳定 entity_id 更新人工记忆实体卡，字段级替换语义：传了即整体替换，没传不动。entity_id、entity_name、entity_type 必填；entity_id 缺失或空白返回400，未命中返回404，绝不建卡。支持改名与改 entity_type（名称+类型组合变化时文档搬家，entity_id 恒不变；仅大小写差异原地更新），改名时旧名自动并入 aliases；新名归一化后命中其他 entity_id 的已有卡（不论类型）返回409。四项业务meta作为一组：任一非null字段被提供则整组替换，未提供的置 null；全部未提供则保持现值。

请求语法

PUT /v1/memories/entities

请求参数

名称	类型	必填	描述	示例值
entity_id	string	是	稳定实体ID，用于定位现卡；缺失返回400，未命中返回404	`ent-0f21...`
entity_name	string	是	实体名称，1-128字符；与现名不同即改名	`张三`
entity_type	string	是	实体类型，1-64字符	`person`
attributes	array	否	属性列表，传入时整体替换，须1-200条且每项非空、单条最长20480字符；现卡属性为空且本次未传返回400	`["偏好拿铁"]`
aliases	array	否	别名列表，传入时整体替换，最多20条、每条上限128字符	`["小张"]`
user_id	string	否	应用内用户标识，与其余三项作为一组整体替换	`user-001`
agent_id	string	否	Agent标识，与其余三项作为一组整体替换	`agent-chat`
app_id	string	否	应用标识，与其余三项作为一组整体替换	`app-main`
run_id	string	否	运行标识，与其余三项作为一组整体替换	`run-abc123`

返回参数

data 字段结构同CreateEntity，其中 created 恒为 false。

名称	类型	描述	示例值
entity_id	string	稳定实体ID，更新前后不变	`ent-0f21...`
entity_name	string	更新后的实体名称	`张三`
entity_type	string	更新后的实体类型	`person`
aliases	array	更新后的别名列表（改名时含旧名）	`["小张","张叁"]`
attributes	array	更新后的属性列表	`["偏好拿铁"]`
user_id	string	应用内用户标识，未提供整组时保持现值，否则可能为 `null`	`user-001`
agent_id	string	Agent标识	`agent-chat`
app_id	string	应用标识	`null`
run_id	string	运行标识	`null`
created	boolean	恒为 `false`（命中已有卡）	`false`
created_at	string	创建时间，ISO-8601 UTC	`2026-08-20T03:00:00Z`
updated_at	string	更新时间，ISO-8601 UTC	`2026-08-28T10:00:00Z`

ListEntityRelations

接口说明

返回记忆知识图谱中的实体和关系（与知识库/文档图谱无关）。锚点实体继承 /v1/memories/entities 的可见性过滤，archived与无属性无关系的空壳卡不作为图锚点。max_nodes 自动钳制到 [50, 8000]（默认2000），max_edges 自动钳制到 [100, 20000]（默认5000），越界不会返回400。

请求语法

GET /v1/memories/entity-relations

请求参数

名称	类型	必填	描述	示例值
user_id	string	否	应用内用户ID过滤	`user-001`
agent_id	string	否	Agent ID过滤	`agent-chat`
max_nodes	integer	否	实体锚点数量上限，默认 `2000`，钳制到 `[50, 8000]`	`500`
max_edges	integer	否	返回关系数量上限，默认 `5000`，钳制到 `[100, 20000]`	`1000`

返回参数

名称	类型	描述	示例值
relations	array	关系列表，元素结构见下表	见下表
total	integer	关系总数	`36`

relations数组元素

名称	类型	描述	示例值
id	string	关系记录ID	`rel-77c1...`
from_entity_id	string	起点实体ID	`ent-0f21...`
from_entity_name	string	起点实体名称	`张三`
from_entity_type	string	起点实体类型	`person`
to_entity_id	string	终点实体ID	`ent-3b99...`
to_entity_name	string	终点实体名称	`李四`
to_entity_type	string	终点实体类型	`person`
relation	string	关系名	`同事`
strength	float	关系强度，缺失时不返回	`0.7`
state	string	关系状态	`active`
source_fact_ids	array	支撑该关系的记忆ID列表，缺失时不返回	`["mem-8f3a"]`
user_id	string	应用内用户标识，为空时不返回	`user-001`
agent_id	string	Agent标识，为空时不返回	`agent-chat`
created_at	string	创建时间，缺失时不返回	`2026-08-20T03:00:00Z`
updated_at	string	更新时间，缺失时不返回	`2026-08-25T06:00:00Z`

GetCustomPrompt

接口说明

查询当前成员的自定义记忆提取提示词。未配置时 data 为 null。响应使用统一信封结构。

请求语法

GET /v1/memories/custom_prompt

请求参数

无请求参数。

返回参数

以下为 data 内字段，外层信封见「响应结构」；未配置时 data 整体为 null。

名称	类型	描述	示例值
content	string	提示词内容	`请重点关注用户的饮食偏好`
workspace_id	string	所属workspace ID（服务端注入）	`ws-001`
member_id	string	所属成员ID（服务端注入）	`member-001`
created_at	string	创建时间	`2026-08-20T03:00:00Z`
updated_at	string	更新时间	`2026-08-28T10:00:00Z`

PutCustomPrompt

接口说明

创建或覆盖当前成员的记忆提取提示词。content 必填，trim后不能为空，且trim后最长512字符，超长返回400。写入的是trim后的内容。响应使用统一信封结构。

请求语法

PUT /v1/memories/custom_prompt

请求参数

名称	类型	必填	描述	示例值
content	string	是	提示词内容，trim后非空且不超过512字符	`请重点关注用户的饮食偏好`

返回参数

data 字段结构同GetCustomPrompt。

名称	类型	描述	示例值
content	string	写入后的提示词内容（已trim）	`请重点关注用户的饮食偏好`
workspace_id	string	所属workspace ID（服务端注入）	`ws-001`
member_id	string	所属成员ID（服务端注入）	`member-001`
created_at	string	创建时间	`2026-08-20T03:00:00Z`
updated_at	string	更新时间	`2026-08-28T10:00:00Z`

DeleteCustomPrompt

接口说明

删除当前成员配置的记忆提取提示词，接口幂等：未配置时同样返回成功。响应使用统一信封结构。

请求语法

DELETE /v1/memories/custom_prompt

请求参数

无请求参数。

返回参数

以下为 data 内字段，外层信封见「响应结构」。

名称	类型	描述	示例值
deleted	boolean	恒为 `true`（幂等）	`true`