通过 HTTP JSON 协议直接调用记忆存储服务,覆盖记忆库管理、长期记忆读写、短期记忆与审计查询、记忆整理(Dream)任务,适用于无 SDK 的自定义集成场景。
接口列表
按功能分类,全部接口如下。
记忆库管理
接口 | 说明 |
| 创建记忆库。 |
| 获取记忆库详情。 |
| 更新记忆库描述。 |
| 删除记忆库。 |
| 列出记忆库。 |
长期记忆
接口 | 说明 |
| 写入对话消息或文本,并生成长期记忆。 |
| 检索长期记忆。 |
| 列出长期记忆。 |
| 获取单条长期记忆。 |
| 更新单条长期记忆。 |
| 删除单条长期记忆。 |
短期记忆与审计
接口 | 说明 |
| 查询短期记忆,即原始会话消息。 |
| 查询记忆库请求审计记录。 |
异步任务与 Scope
接口 | 说明 |
| 查询异步抽取任务状态与结果。 |
| 列出异步抽取任务。 |
| 列出记忆库中已存在的 Scope。 |
记忆整理(Dream)
接口 | 说明 |
| 创建记忆整理任务。 |
| 查询记忆整理任务进度。 |
| 列出记忆整理任务。 |
| 列出整理任务产生的动作(提案)。 |
| 应用整理动作提案。 |
| 取消记忆整理任务。 |
通用对象
记忆库接口在请求和响应中复用以下数据结构。
Scope
Scope 表示记忆数据的归属层级,由四级字段组成。
字段 | 类型 | 说明 |
| string | 应用标识。 |
| string | 租户或用户标识。 |
| string | Agent 标识。 |
| string | 会话、运行或任务标识。 |
不同接口对 Scope 字段的必填性和通配符 * 支持规则不同。
场景 | 必填字段 | 通配符 |
写入( |
| 其他字段为空时补 |
检索长期记忆( |
|
|
查询短期记忆( | 四级 Scope 全部必填 | 不允许使用 |
获取、更新、删除单条长期记忆( | 四级 Scope 全部必填 | 不允许使用 |
列表查询( |
| 支持按层级使用 |
示例:
{
"appId": "app-001",
"tenantId": "user-001",
"agentId": "assistant",
"runId": "session-001"
}Message
AddMemories 接口的 messages 字段使用以下结构。
字段 | 类型 | 必填 | 说明 |
| string | 是 | 消息角色,例如 |
| string | 是 | 消息内容。 |
| string | 否 | 消息 ID,最长 256 个字符。 |
| string | 否 | RFC3339 格式时间。 |
| object | 否 | 消息级元数据,键和值均为字符串。 |
Metadata
Metadata 为字符串键值对,用于附加业务标签。在检索接口中,Metadata 用于字符串键值的精确匹配过滤。
限制项 | 取值 |
单次请求最多键数 | 16 个 |
键长度上限 | 64 个字符 |
值长度上限 | 1024 个字符 |
示例:
{
"source": "chat",
"topic": "preference"
}CreateMemoryStore
创建一个记忆库。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称,只能包含字母、数字和下划线,最长 32 个字符。 |
| string | 否 | 记忆库描述,最长 1024 个字符。 |
| string | 否 | 记忆库自定义抽取指令,最长 4096 个字符。 |
请求示例
{
"memoryStoreName": "agent_memory",
"description": "Agent 长期记忆库",
"extractInstructions": "重点关注用户的饮食偏好与出行习惯"
}GetMemoryStore
获取记忆库详情。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
请求示例
{
"memoryStoreName": "agent_memory"
}UpdateMemoryStore
更新记忆库描述。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 | 新描述,最长 1024 个字符。 |
| string | 否 | 新的自定义抽取指令,最长 4096 个字符;传空字符串清除,不传保持不变。 |
DeleteMemoryStore
删除记忆库。
删除记忆库会一并删除该记忆库下的全部数据,操作不可逆。生产环境请谨慎执行。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
ListMemoryStores
列出记忆库。
请求参数
字段 | 类型 | 必填 | 说明 |
| int | 否 | 返回数量。 |
| string | 否 | 下一页标记。 |
AddMemories
写入对话消息或文本。服务保存原始消息作为短期记忆,并从输入中提取长期记忆。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 目标记忆库名称。 |
| object | 是 | Scope。写入时 |
| array | 与 | 对话消息数组,最多 20 条;总内容长度不超过 32000 个字符。 |
| string | 与 | 文本内容,最长 32000 个字符。 |
| object | 否 | 写入级元数据,最多 16 个键,键最长 64 个字符,值最长 1024 个字符。 |
| boolean | 否 | 是否同步等待记忆抽取完成,默认 |
各项上限的完整说明,请参见 限制与注意事项。
请求示例:写入消息
{
"memoryStoreName": "agent_memory",
"scope": {
"appId": "app-001",
"tenantId": "user-001",
"agentId": "assistant",
"runId": "session-001"
},
"messages": [
{
"role": "user",
"content": "我喜欢喝咖啡"
},
{
"role": "assistant",
"content": "好的,我记住了"
}
],
"metadata": {
"source": "chat"
},
"sync": true
}请求示例:写入文本
{
"memoryStoreName": "agent_memory",
"scope": {
"appId": "app-001",
"tenantId": "user-001"
},
"text": "用户喜欢喝咖啡,偏好简洁的回答风格"
}响应字段
字段 | 说明 |
| 请求 ID。 |
| 请求状态。异步写入通常返回 |
| 接收的消息数量。 |
| 实际写入使用的 Scope。 |
| 记忆库名称。 |
| 同步写入时返回,表示创建的记忆片段数量。 |
| 同步写入时返回,表示创建的长期记忆单元数量。 |
SearchMemories
检索长期记忆。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 目标记忆库名称。 |
| string | 是 | 查询文本。 |
| object | 是 | Scope。检索时 |
| int | 否 | 返回数量,默认 |
| boolean | 否 | 是否在结果中附带短期记忆源证据( |
| float | 否 | 相似度过滤阈值,取值范围 |
| boolean | 否 | 是否启用 Rerank,默认 |
| object | 否 | 元数据精确匹配过滤条件,键和值均为字符串。 |
topK 取值上限的完整说明,请参见 限制与注意事项。
请求示例
{
"memoryStoreName": "agent_memory",
"scope": {
"appId": "app-001",
"tenantId": "user-001",
"agentId": "*",
"runId": "*"
},
"query": "用户喜欢什么饮品",
"topK": 5,
"enableRerank": true,
"includeEvidence": true,
"metadata": {
"source": "chat"
}
}响应字段
字段 | 说明 |
| 检索结果列表。 |
| 长期记忆单元,字段定义见下表。 |
| 相关性分数。 |
| 查询与记忆的归一化余弦相似度( |
| 命中来源,例如 |
| 当 |
| 查询使用的 Scope。 |
| 记忆库名称。 |
results[].unit 内部字段如下。
字段 | 说明 |
| 长期记忆单元 ID。 |
| 关联的会话键。 |
| 记忆所属 Scope,对象包含 |
| 记忆片段 ID。 |
| 记忆单元类型。 |
| 记忆文本。 |
| 用于检索的文本。 |
| 来源消息 ID 列表。 |
| 类型标签。 |
| 日期分桶。 |
| 元数据,JSON 字符串。 |
| 是否已删除。 |
| 创建时间。 |
| 显著性分数。 |
| 版本号。 |
ListMemories
列出长期记忆。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| object | 是 | Scope。 |
| int | 否 | 返回数量。 |
| string | 否 | 下一页标记。 |
请求示例
{
"memoryStoreName": "agent_memory",
"scope": {
"appId": "app-001",
"tenantId": "*",
"agentId": "*",
"runId": "*"
},
"limit": 20
}GetMemory
获取单条长期记忆。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 | 记忆 ID。 |
| object | 是 | 完整 Scope,4 字段全部必填,不允许使用通配符 |
UpdateMemory
更新单条长期记忆。text 和 metadata 至少提供一个。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 | 记忆 ID。 |
| object | 是 | 完整 Scope,4 字段全部必填,不允许使用通配符 |
| string | 否 | 新记忆文本。 |
| object | 否 | 新元数据。 |
DeleteMemory
删除单条长期记忆。
删除单条长期记忆为不可逆操作。生产环境请谨慎执行。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 | 记忆 ID。 |
| object | 是 | 完整 Scope,4 字段全部必填,不允许使用通配符 |
ListMemoryStoreMessages
查询短期记忆,即原始会话消息。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| object | 是 | 完整 Scope,4 字段全部必填,不允许使用通配符 |
| int | 否 | 返回数量。 |
| string | 否 | 下一页标记。 |
| string | 否 | 最小时间,RFC3339 格式。 |
| string | 否 | 最大时间,RFC3339 格式。 |
请求示例
{
"memoryStoreName": "agent_memory",
"scope": {
"appId": "app-001",
"tenantId": "user-001",
"agentId": "assistant",
"runId": "session-001"
},
"limit": 100
}响应示例
{
"session": {
"scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
"messages": [
{
"messageId": "d0d9dd778a27e8cde773a243a5bab13c",
"role": "user",
"speaker": "user",
"content": "[10:00 AM on 13 May, 2026] 我以后出差都优先订靠窗座位",
"timestamp": "2026-05-13T10:00:00Z",
"metadata": { "channel": "chat", "source": "chat" }
}
]
}
}记忆库存在但该 Scope 暂无消息时,返回 200 与空的 messages 列表。
ListMemoryStoreRequests
查询记忆库请求审计记录。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| object | 是 | Scope,可按层级使用通配符 |
| string | 否 | 操作名称,例如 |
| int | 否 | 返回数量。 |
| string | 否 | 下一页标记。 |
| string | 否 | 最小时间,RFC3339 格式。 |
| string | 否 | 最大时间,RFC3339 格式。 |
请求示例
{
"memoryStoreName": "agent_memory",
"scope": {
"appId": "app-001",
"tenantId": "*",
"agentId": "*",
"runId": "*"
},
"operation": "AddMemories",
"limit": 50
}响应字段
字段 | 说明 |
| 请求 ID。 |
| 操作名称。 |
| 请求使用的 Scope。 |
| 请求摘要。 |
| 响应状态。 |
| 处理耗时,单位毫秒。 |
| 操作目标 ID,例如记忆 ID。 |
| 记录创建时间。 |
GetMemoryTask
查询异步抽取任务的状态与结果,传入 AddMemories 返回的 requestId。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 |
|
| object | 否 | 校验任务归属的 Scope,可按层级使用 |
请求示例
{
"memoryStoreName": "agent_memory",
"requestId": "4b41a912f8c8a66202896e880a505d4a"
}响应示例
{
"memoryStoreName": "agent_memory",
"task": {
"requestId": "4b41a912f8c8a66202896e880a505d4a",
"eventType": "ingest",
"memoryStoreName": "agent_memory",
"conversationKey": "app-001/user-001/assistant/session-001",
"scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
"status": "completed",
"acceptedMessages": 2,
"derivedMemcellId": "b1bb4faec235b0d55bc8830da8ffa9f2",
"derivedUnitIds": ["88432eb9d28e0787791625da916d6a20", "480230ab0806e88fd69e0804599552a4"],
"createdAt": "2026-06-17T07:19:59.962Z",
"updatedAt": "2026-06-17T07:20:08.749Z",
"finishedAt": "2026-06-17T07:20:08.749Z"
}
}任务状态 status 取值:queued、running、completed、failed、needs_reconcile。首次写入后任务索引建立期间,本接口可能返回 409 CONFLICT(ingest task index is still building, please retry shortly),稍后重试即可。
ListMemoryTasks
列出异步抽取任务。响应在 tasks 数组中返回任务对象,元素结构与 GetMemoryTask 响应中的 task 一致。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| object | 是 | Scope,可按层级使用 |
| string | 否 | 任务状态过滤: |
| int | 否 | 返回数量,默认 |
| string | 否 | 下一页标记。 |
| string | 否 | 最小时间,Unix 毫秒时间戳(不支持 RFC3339)。 |
| string | 否 | 最大时间,Unix 毫秒时间戳(不支持 RFC3339)。 |
请求示例
{
"memoryStoreName": "agent_memory",
"scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
"limit": 5
}ListMemoryStoreScopes
列出记忆库中已存在的 Scope,可查看某应用或租户下有哪些 Agent 和会话产生过记忆。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| object | 是 | Scope,可按层级使用 |
| int | 否 | 返回数量,默认 |
| string | 否 | 下一页标记。 |
请求示例
{
"memoryStoreName": "agent_memory",
"scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
"limit": 10
}响应示例
{
"memoryStoreName": "agent_memory",
"scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
"scopes": [
{ "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
{ "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" }
]
}CreateMemoryDreamTask
创建记忆整理(Dream)任务,对已写入记忆进行二次提炼、归并与技能/画像提取。任务异步执行。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| array | 是 | 待整理的 Scope 列表,最多 20 个。 |
| string | 否 | 任务类型: |
| string | 否 | 应用模式: |
| string | 否 | 整理结果归属: |
| object | 否 | 各动作的自动应用置信度阈值,键为 |
| string | 否 | 整理的时间范围,Unix 毫秒时间戳(不支持 RFC3339)。 |
| int | 否 | 输入规模上限,取值范围见限制文档。 |
| int | 否 | Scope 展开上限, |
| string | 否 | 自定义整理指令,最长 4000 个字符。 |
| boolean | 否 | 是否增量整理,默认 |
| string | 否 | 幂等 Token。 |
请求示例
{
"memoryStoreName": "agent_memory",
"scopes": [ { "appId": "app-001", "tenantId": "user-001" } ],
"taskType": "memory",
"applyMode": "proposal"
}响应示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"status": "queued",
"createdAt": "2026-06-17T07:21:25.329Z"
}GetMemoryDreamTask
查询记忆整理任务的进度与结果概览。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 | 整理任务 ID。 |
请求示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7"
}响应示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"taskType": "memory",
"applyMode": "proposal",
"scopeOutputMode": "preserve_scope",
"status": "completed",
"actions": { "total": 2, "proposed": 2, "applied": 0, "skipped": 0, "failed": 0 },
"input": { "scopes": [ { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" } ], "sessionCount": 1, "messageCount": 1, "memoryCount": 2, "incremental": false },
"lastError": "",
"createdAt": "2026-06-17T07:21:25.329Z",
"updatedAt": "2026-06-17T07:21:32.276Z",
"finishedAt": "2026-06-17T07:21:32.276Z"
}任务状态 status 取值:queued、running、planning、applying、completed、completed_with_failures、failed、cancelled。
ListMemoryDreamTasks
列出记忆整理任务。响应在 tasks 数组中返回任务对象,包含 dreamId、status、taskType、actionCount、proposedCount、confidenceThresholds、createdAt 等字段。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| object | 是 | Scope,可按层级使用 |
| string | 否 | 任务状态过滤。 |
| int | 否 | 返回数量,默认 |
| string | 否 | 下一页标记。 |
| string | 否 | 时间范围,Unix 毫秒时间戳(不支持 RFC3339)。 |
请求示例
{
"memoryStoreName": "agent_memory",
"scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
"limit": 10
}ListMemoryDreamActions
列出整理任务产生的动作(提案)。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 否 | 整理任务 ID(与 |
| object | 否 | 按 Scope 查询(与 |
| string | 否 | 动作状态过滤: |
| string | 否 | 动作类型过滤: |
| float | 否 | 置信度过滤, |
| string | 否 | 排序: |
| int | 否 | 返回数量,默认 |
| string | 否 | 下一页标记。 |
请求示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"limit": 20
}响应示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"actions": [
{
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"actionId": "968768529cdfde8d56686a71e1c28227",
"action": "UPDATE",
"status": "proposed",
"targetScope": { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
"targetMemoryId": "d16fd038835d89ae8586f7814e5256c1",
"newMemory": { "text": "User prefers concise responses.", "unitType": "atomic_fact" },
"reason": "改写为更准确的 atomic_fact 表述。",
"confidence": 0.95,
"createdAt": "2026-06-17T07:21:32.161Z"
}
]
}两种查询模式互斥:按 dreamId 查询该任务下所有动作;按 scope + actionType(仅 EMIT_SKILL、EMIT_PROFILE)查询该范围内累积生成的技能或画像。
ApplyMemoryDreamActions
应用记忆整理任务产生的提案动作(applyMode=proposal 时)。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 | 整理任务 ID。 |
| array | 是 | 待应用的动作 ID 列表,不可为空,单次最多 100 个。 |
| string | 否 | 应用者标识,记录在审计中。 |
请求示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"actionIds": ["968768529cdfde8d56686a71e1c28227", "a0f4715245920ea7b6a34c1828c6f1ae"]
}响应示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"applied": 2,
"failed": 0,
"results": [
{ "actionId": "968768529cdfde8d56686a71e1c28227", "status": "applied", "memoryId": "bd14a67ed215c114896325d912c8fa71" },
{ "actionId": "a0f4715245920ea7b6a34c1828c6f1ae", "status": "applied", "memoryId": "fa253856113f78d51a3b84a1fdf2d110" }
]
}EMIT_SKILL、EMIT_PROFILE 动作由整理任务直接写入,没有手动 apply 流程,混入此类动作 ID 会被拒绝。actionIds 为空数组时返回 403。
CancelMemoryDreamTask
取消尚未完成的记忆整理任务。
请求参数
字段 | 类型 | 必填 | 说明 |
| string | 是 | 记忆库名称。 |
| string | 是 | 整理任务 ID。 |
请求示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7"
}响应示例
{
"memoryStoreName": "agent_memory",
"dreamId": "2a528008111f5dc3500c73fd965089f7",
"status": "cancelled",
"taskType": "memory"
}仅可取消未完成的任务;已进入终态(completed、failed、cancelled)的任务,响应仍返回 200,status 保持原值,任务本身不做处理。