记忆存储服务 HTTP JSON API 接口参考-表格存储 Tablestore(Tablestore)-阿里云帮助中心

记忆存储服务通过 HTTP JSON 协议提供 30 个接口，覆盖记忆库管理、长期记忆读写、短期记忆与审计查询、异步任务、记忆整理（Dream）、文件记忆与文件视图，适用于无 SDK 的自定义集成场景。

接口列表

按功能分类，全部接口如下。

记忆库管理

接口	说明
`CreateMemoryStore`	创建记忆库。
`GetMemoryStore`	获取记忆库详情。
`UpdateMemoryStore`	更新记忆库描述。
`DeleteMemoryStore`	删除记忆库。
`ListMemoryStores`	列出记忆库。

长期记忆

接口	说明
`AddMemories`	写入对话消息或文本，并生成长期记忆。
`SearchMemories`	检索长期记忆。
`ListMemories`	列出长期记忆。
`GetMemory`	获取单条长期记忆。
`UpdateMemory`	更新单条长期记忆。
`DeleteMemory`	删除单条长期记忆。

短期记忆与审计

接口	说明
`ListMemoryStoreMessages`	查询短期记忆，即原始会话消息。
`ListMemoryStoreRequests`	查询记忆库请求审计记录。

异步任务与 Scope

接口	说明
`GetMemoryTask`	查询异步抽取任务状态与结果。
`ListMemoryTasks`	列出异步抽取任务。
`ListMemoryStoreScopes`	列出记忆库中已存在的 Scope。

记忆整理（Dream）

接口	说明
`CreateMemoryDreamTask`	创建记忆整理任务。
`GetMemoryDreamTask`	查询记忆整理任务进度。
`ListMemoryDreamTasks`	列出记忆整理任务。
`ListMemoryDreamActions`	列出整理任务产生的动作（提案）。
`ApplyMemoryDreamActions`	应用整理动作提案。
`CancelMemoryDreamTask`	取消记忆整理任务。

文件记忆与文件视图

接口	说明
`AddItem`	新增记忆文件。
`ListItems`	按路径前缀分页列出文件。
`GetItem`	读取文件内容或仅获取元数据。
`UpdateItem`	更新文件内容或重命名文件。
`DeleteItem`	删除文件。
`ListItemVersions`	分页列出文件的历史版本。
`GetItemVersion`	读取指定历史版本。
`RedactItemVersion`	不可逆地脱敏指定历史版本。

通用对象

记忆库接口在请求和响应中复用以下数据结构。

Scope

Scope 表示记忆数据的归属层级，由四级字段组成。

字段	类型	说明
`appId`	string	应用标识。
`tenantId`	string	租户或用户标识。
`agentId`	string	Agent 标识。
`runId`	string	会话、运行或任务标识。

不同接口对 Scope 字段的必填性和通配符 * 支持规则不同。

场景	必填字段	通配符 `*` 规则
写入（`AddMemories`）	`appId`	其他字段为空时补 `__default__`，不允许使用 `*`。
检索长期记忆（`SearchMemories`）	`appId`、`tenantId`	`agentId` 和 `runId` 可使用 `*`。
查询短期记忆（`ListMemoryStoreMessages`）	四级 Scope 全部必填	不允许使用 `*`。
获取、更新、删除单条长期记忆（`GetMemory`、`UpdateMemory`、`DeleteMemory`）	四级 Scope 全部必填	不允许使用 `*`。
文件记忆与文件视图（Item 接口）	四级 Scope 全部必填	不允许使用 `*`。
列表查询（`ListMemories`、`ListMemoryStoreScopes`、`ListMemoryTasks`、`ListMemoryStoreRequests`、`ListMemoryDreamTasks`）	无（建议至少提供 `appId`，为空的字段按 `__default__` 处理）	支持按层级使用 `*`。

示例：

{
  "appId": "app-001",
  "tenantId": "user-001",
  "agentId": "assistant",
  "runId": "session-001"
}

Message

AddMemories 接口的 messages 字段使用以下结构。

字段	类型	必填	说明
`role`	string	是	消息角色，例如 `user`、`assistant`、`system`。
`content`	string	是	消息内容。
`messageId`	string	否	消息 ID，最长 256 个字符。
`timestamp`	string	否	RFC3339 格式时间。
`metadata`	object	否	消息级元数据，键和值均为字符串。

Metadata

Metadata 为字符串键值对，用于附加业务标签。在检索接口中，Metadata 用于字符串键值的精确匹配过滤。

限制项	取值
单次请求最多键数	16 个
键长度上限	64 个字符
值长度上限	1024 个字符

示例：

{
  "source": "chat",
  "topic": "preference"
}

记忆库管理

CreateMemoryStore

创建一个记忆库。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称，只能包含字母、数字和下划线，最长 32 个字符。
`description`	string	否	记忆库描述，最长 1024 字节（UTF-8）。
`extractInstructions`	string	否	自定义记忆抽取指令，注入抽取提示词，影响该库后续写入的长期记忆抽取，最长 4096 个字符。
`storageMode`	string	否	记忆能力：`ots`（默认，结构化记忆）/`file+ots`（同时提供结构化记忆与只读文件视图）/`filemem`（直接输入和管理记忆文件）。创建后不可变更。

请求示例

{
  "memoryStoreName": "agent_memory",
  "description": "Agent 长期记忆库",
  "extractInstructions": "重点关注用户的饮食偏好与出行习惯"
}

创建直接输入记忆文件的记忆库：

{
  "memoryStoreName": "agent_files",
  "storageMode": "filemem"
}

响应示例

{
  "otsInstance": "mem-test-01",
  "memoryStoreName": "agent_memory",
  "description": "Agent 长期记忆库",
  "extractInstructions": "重点关注用户的饮食偏好与出行习惯",
  "storageMode": "ots",
  "createdAt": "2026-06-17T07:19:48.935Z",
  "updatedAt": "2026-06-17T07:19:48.935Z"
}

GetMemoryStore

获取记忆库详情。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。

请求示例

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

更新记忆库描述或自定义抽取指令。采用 PATCH 语义：仅更新传入的字段，未传入的字段保持不变；传入空字符串表示清除该字段。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`description`	string	否	新描述，最长 1024 字节（UTF-8）；传空字符串清除，不传保持不变。
`extractInstructions`	string	否	新的自定义抽取指令，最长 4096 个字符；传空字符串清除，不传保持不变。

DeleteMemoryStore

删除记忆库。

警告

删除记忆库会一并删除该记忆库下的全部数据，操作不可逆。生产环境请谨慎执行。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。

ListMemoryStores

列出记忆库。

请求参数

字段	类型	必填	说明
`limit`	int	否	返回数量。
`nextToken`	string	否	下一页标记。

长期记忆

AddMemories

写入对话消息或文本。服务保存原始消息作为短期记忆，并从输入中提取长期记忆。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	目标记忆库名称。
`scope`	object	是	Scope。写入时 `appId` 必填，不允许使用通配符 `*`。
`messages`	array	与 `text` 二选一	对话消息数组，最多 20 条；总内容长度不超过 32000 字节（UTF-8）。
`text`	string	与 `messages` 二选一	文本内容，最长 32000 字节（UTF-8）。
`metadata`	object	否	写入级元数据，最多 16 个键，键最长 64 个字符，值最长 1024 个字符。
`sync`	boolean	否	是否同步等待记忆抽取完成，默认 `false`。
`referenceTime`	string	否	RFC3339 格式的会话基准时间（"as-of"锚点）。设置后，未携带 `timestamp` 的消息以该时间作为事件时间（而非服务器当前时间），适用于历史或批量导入场景。

AddMemories 的各项上限以限制与注意事项为准。

开启 reconcile_enabled 时，写入链路会先用既有向量候选召回，再在同一次 DecideMemoryActions 调用中决定 ADD/NOOP/UPDATE/DELETE/MERGE，不会为 MERGE 额外调用一次模型。

在线 MERGE 由服务端 reconcile_merge_mode 控制：off（默认）不提议合并，shadow 只校验和观测，safe_auto 才应用安全合并。它只接受同一个完整四级 Scope 内、连同新记忆共 2～3 条来源的高置信度结果，并保守检查实体、说话人、极性、类型、明确时间、metadata 和版本。

off、shadow、被拒绝或不安全的提案让原始新记忆继续走 ADD；已接受计划的批量重新 Embedding 失败或响应格式异常时，同批计划全部还原为原始 ADD，写入继续。

若包含合并结果的 PutMemories 失败，接口返回持久化错误，且不会执行来源 CAS 删除，不能视为 ADD 成功。

合并结果落库后，所有来源终结错误都对本次写入非致命，新结果保持持久化；ErrConflict 或其他发生在行应用前的 CAS/后端错误通常让对应旧来源继续有效，留待重试或 Dream，其他来源仍可独立完成。

类型化的 row-applied/事件持久化错误表示来源 tombstone 已持久化且缓存已反映删除，仅审计事件仍不完整；该事件缺口由同一终结计划的幂等重放或运维修复补齐，Dream 不重建在线审计事件，只负责仍有效的旧来源、重复库存与收敛。

任何已成功的来源操作都不会回滚，过渡期的并存重复可由搜索语义去重隐藏。

状态改变且有替代状态时使用 UPDATE，仅撤回且无替代状态时使用 DELETE，不能使用 MERGE。更大来源集、跨会话、复杂冲突与修复由 Dream 处理。

请求示例：写入消息

{
  "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": "用户喜欢喝咖啡，偏好简洁的回答风格"
}

响应字段

字段	说明
`requestId`	请求 ID。
`status`	请求状态。异步写入通常返回 `running`。
`acceptedMessages`	接收的消息数量。
`scope`	实际写入使用的 Scope。
`memoryStoreName`	记忆库名称。
`memcellsCreated`	同步写入时返回，表示创建的记忆片段数量。
`unitsCreated`	同步写入时返回，表示创建的长期记忆单元数量。

SearchMemories

检索长期记忆。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	目标记忆库名称。
`query`	string	是	查询文本。
`scope`	object	是	Scope。检索时 `appId` 和 `tenantId` 必填，`agentId` 和 `runId` 可使用通配符 `*`。
`contextScope`	object	否	当前会话的完整 Scope，用作软排序信号。四个字段必须全部为精确值、不得含 `*`，且必须被 `scope` 包含。省略时保持原检索行为。
`topK`	int	否	最多返回数量，默认 10，上限 50；相关性过滤或语义去重后结果可能少于 topK。
`enableRerank`	boolean	否	是否启用 Rerank，默认 `true`。
`includeEvidence`	boolean	否	是否在结果中附带短期记忆源证据（`evidence` 字段），默认 `false`。
`minSimilarity`	float	否	相关性过滤阈值，取值范围 `0~1`，默认 `0`（不过滤）；大于 `0` 时过滤掉相关性分数（`results[].score`）低于该值的结果。启用 Rerank（默认）时该分数为重排相关性分数，关闭 Rerank 时为归一化余弦相似度。
`metadata`	object	否	元数据精确匹配过滤条件，键和值均为字符串。

服务端开启 search_semantic_dedup_enabled 后，只对公开 SearchMemories 当前已融合的长期记忆候选池进行语义去重；Answer 和内部搜索不受影响。

去重在 Rerank 和证据扩展前执行，使用结构保护的保守 complete-link 聚类，每簇只保留一个代表，因此重复长期记忆不会占用 Rerank 预算，evidence 短期证据仍保持独立。它不会扩大 candidateK，不发起第二次检索、额外 Embedding、补位或 LLM 聚类；topK 是返回上限，结果不足时接受 underfill，也不会从同簇补位。

语义去重不修改存储行或 ListMemories 的结果，历史库存仍由 Dream 清理。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "contextScope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "query": "用户喜欢什么饮品",
  "topK": 5,
  "enableRerank": true,
  "includeEvidence": true,
  "metadata": {
    "source": "chat"
  }
}

响应字段

字段	说明
`results`	检索结果列表。
`results[].unit`	长期记忆单元，字段定义见下表。
`results[].score`	规范相关性分数（`0~1`）。启用 Rerank（默认）时为重排相关性分数，关闭时为归一化余弦相似度；`minSimilarity` 始终先基于该字段过滤。session 软排序不会改写该字段。
`results[].similarity`	查询与记忆的归一化余弦相似度（`0~1`），仅供参考；关闭 Rerank 时与 `score` 相同。
`results[].rankingScore`	可选的最终排序分数。仅服务端 session affinity 模式为 `on` 且请求携带有效 `contextScope` 时返回；结果按该字段排序。
`results[].rankingSignals`	可选的排序解释，包含 `sameSession` 与服务端使用的 `sessionAffinityWeight`。与 `rankingScore` 同时返回。
`results[].source`	命中来源，例如 `vector`、`vector+text`。
`evidence`	当 `includeEvidence=true` 时返回的短期记忆源证据列表，元素结构与 `results` 相同；无可用证据时为 `[]`。
`scope`	查询使用的 Scope。
`memoryStoreName`	记忆库名称。

results[].unit 内部字段如下。ListMemories、GetMemory 返回的记忆单元字段与此一致。embedding 向量不会在响应中返回。

字段	说明
`id`	长期记忆单元 ID。
`conversation_key`	关联的会话键。
`scope`	记忆所属 Scope，对象包含 `appId`、`tenantId`、`agentId`、`runId` 四个字段。
`memcell_id`	记忆片段 ID。
`unit_type`	记忆单元类型，例如 `atomic_fact`、`entity_fact`、`temporal_anchor`。
`title`	记忆名称，最多 64 个字符；旧数据或字段为空时客户端可回退展示 `text`。
`text`	记忆文本。
`search_text`	用于检索的文本。
`keywords`	关键词列表，最多 8 个，每个最多 32 个字符。
`source_turn_ids`	来源消息 ID 列表。
`type_label`	类型标签。
`date_bucket`	日期分桶。
`metadata`	元数据对象（写入时提供的键值对）。
`metadata_json`	元数据，JSON 字符串。
`metadata_flat`	元数据扁平化字符串，用于过滤。
`deleted`	是否已删除。
`created_at`	创建时间。
`effective_at`	事实、事件或计划所描述的生效时间；可能早于或晚于记忆写入时间。
`updated_at`	记忆单元最近一次服务端更新的时间。
`time_source`	时间来源，例如 `explicit_event`、`source_message`、`legacy_created_at`、`manual`。
`time_precision`	`effective_at` 的原始精度：`second`、`day`、`month`、`year` 或 `unknown`。
`salience`	显著性分数。
`version`	版本号。
`speaker`	记忆涉及的说话人（字段非空时返回）。
`topic`	主题标签（字段非空时返回）。
`entities`	相关实体列表（字段非空时返回）。
`time_anchor`	时间锚点信息（字段非空时返回）。
`source_turn_refs`	来源消息引用列表，元素含 `messageId` 与 `timestampMs`（字段非空时返回）。
`superseded_by` / `supersedes_id`	记忆被合并/更新时的替代链信息（字段非空时返回）。
`dream_id` / `dream_action_id` / `dream_reason` / `dream_source_message_ids` / `dream_source_memory_ids`	由记忆整理（Dream）产生或改写的记忆携带的溯源字段（字段非空时返回）。

同 session 采用有界软加权：精确匹配完整 contextScope 时，rankingScore = score + (1-score) × sessionAffinityWeight；其他结果的 rankingScore 等于 score。权重由服务端控制，默认 0.10、最大 0.25，请求不能覆盖。该信号只打破相关度接近的候选，不替代语义相关性与 minSimilarity 门槛。

兼容性提示：旧服务端对 JSON 使用严格未知字段校验，会拒绝 contextScope。滚动升级时必须先完成所有服务副本升级，再让客户端发送该字段。只读 SDK 可仅在明确收到 unknown-field 错误时去掉 contextScope 重试一次；不要对写接口做这种降级重试。

ListMemories

列出长期记忆。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	是	Scope。可按层级使用通配符 ``（左前缀规则：`` 之后的字段必须也是 `*` 或为空）；为空的字段按 `__default__` 处理。建议至少提供 `appId`。
`limit`	int	否	返回数量。
`nextToken`	string	否	下一页标记。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "limit": 20
}

响应在 memories 数组中返回长期记忆单元，单元字段与 SearchMemories 的 results[].unit 一致；分页时返回 nextToken。

GetMemory

获取单条长期记忆。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`memoryId`	string	是	记忆 ID。
`scope`	object	是	完整 Scope，4 字段全部必填，不允许使用通配符 `*`。

UpdateMemory

更新单条长期记忆，采用 PATCH 语义：未传字段保持不变；title 传空字符串、keywords 传空数组可显式清空。至少传入一个可更新字段。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`memoryId`	string	是	记忆 ID。
`scope`	object	是	完整 Scope，4 字段全部必填，不允许使用通配符 `*`。
`text`	string	否	新记忆文本。
`metadata`	object	否	新元数据。
`title`	string	否	新记忆名称，最多 64 个字符。
`keywords`	array	否	新关键词列表，最多 8 个，每项最多 32 个字符。
`effectiveAt`	string	与 `timePrecision` 同时提供	新生效时间。`second` 使用 RFC3339；`day`、`month`、`year` 分别使用 `YYYY-MM-DD`、`YYYY-MM`、`YYYY`。
`timePrecision`	string	与 `effectiveAt` 同时提供	`second`、`day`、`month` 或 `year`。

服务端未启用 memory_unit_v2_write_enabled 时，携带 title、keywords、effectiveAt 或 timePrecision 的更新会返回 409 CONFLICT，避免混合版本副本互相覆盖 V2 字段。

DeleteMemory

删除单条长期记忆。

警告

删除单条长期记忆为不可逆操作。生产环境请谨慎执行。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`memoryId`	string	是	记忆 ID。
`scope`	object	是	完整 Scope，4 字段全部必填，不允许使用通配符 `*`。

短期记忆与审计

ListMemoryStoreMessages

查询短期记忆，即原始会话消息。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	是	完整 Scope，4 字段全部必填，不允许使用通配符 `*`。
`limit`	int	否	返回数量。
`nextToken`	string	否	下一页标记。
`minTimestamp`	string	否	最小时间，RFC3339 格式。
`maxTimestamp`	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

查询记忆库请求审计记录。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	是	Scope，可按层级使用通配符 `*`。
`operation`	string	否	操作名称，例如 `AddMemories` 或 `SearchMemories`。
`limit`	int	否	返回数量。
`nextToken`	string	否	下一页标记。
`minTimestamp`	string	否	最小时间，RFC3339 格式。
`maxTimestamp`	string	否	最大时间，RFC3339 格式。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "operation": "AddMemories",
  "limit": 50
}

响应字段

字段	说明
`requestId`	请求 ID。
`operation`	操作名称。
`scope`	请求使用的 Scope。
`requestSummary`	请求摘要。
`responseStatus`	响应状态。
`latencyMs`	处理耗时，单位毫秒。
`targetId`	操作目标 ID，例如记忆 ID。
`createdAt`	记录创建时间。

异步任务与 Scope

GetMemoryTask

查询异步抽取任务的状态与结果，传入 AddMemories 返回的 requestId。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`requestId`	string	是	`AddMemories` 返回的请求 ID。
`scope`	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": "98ebdf1de01b620bfa96f55c8925061f",
    "derivedUnitIds": ["9ce29432d101aab04253a862c8a11022", "6172bac2ca37b6b82f5224de116f030f"],
    "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

列出异步抽取任务。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	是	Scope，可按层级使用 `*`。
`status`	string	否	任务状态过滤：`queued`/`running`/`completed`/`failed`/`needs_reconcile`。
`limit`	int	否	返回数量，默认 `50`，最大 `100`。
`nextToken`	string	否	下一页标记。
`minTimestamp`	string	否	最小时间，Unix 毫秒时间戳（不支持 RFC3339）。
`maxTimestamp`	string	否	最大时间，Unix 毫秒时间戳（不支持 RFC3339）。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
  "limit": 5
}

响应在 tasks 数组中返回任务对象，字段同 GetMemoryTask 的 task。

ListMemoryStoreScopes

列出记忆库中已存在的 Scope，用于发现某应用/租户下有哪些 Agent 和会话产生过记忆。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	是	Scope，可按层级使用 `*`。
`limit`	int	否	返回数量，默认 `100`，最大 `100`。
`nextToken`	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" }
  ]
}

记忆整理（Dream）

CreateMemoryDreamTask

创建记忆整理（Dream）任务，对已写入记忆进行二次提炼、归并与技能/画像提取。任务异步执行；记忆整理（Dream）使用介绍说明了完整任务流程。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scopes`	array	是	待整理的 Scope 列表，最多 20 个。
`taskType`	string	否	任务类型：`memory`（默认）/`skill`/`profile`。
`applyMode`	string	否	应用模式：`proposal`（默认，仅生成提案）/`safe_auto`（自动应用安全动作）。仅 `taskType=memory` 支持。
`scopeOutputMode`	string	否	整理结果归属：`preserve_scope`（默认）/`promote_scope`。
`confidenceThresholds`	object	否	各动作的自动应用置信度阈值，键为 `add`/`update`/`merge`，值取值范围 `0~1`。
`minTimestamp` / `maxTimestamp`	string	否	整理的时间范围，Unix 毫秒时间戳（不支持 RFC3339）。
`maxSessions` / `maxMessages` / `maxMemories`	int	否	输入规模上限，取值范围见限制文档。
`expandedScopeLimit`	int	否	Scope 展开上限，`0~1000`。
`instructions`	string	否	自定义整理指令，最长 4000 字节（UTF-8）。
`incremental`	boolean	否	是否增量整理（从上次成功水位续跑），默认 `false`（全量）。
`clientToken`	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

查询记忆整理任务的进度与结果概览。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`dreamId`	string	是	整理任务 ID。

响应示例

{
  "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

列出记忆整理任务。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	是	Scope，可按层级使用 `*`。
`status`	string	否	任务状态过滤。
`limit`	int	否	返回数量，默认 `50`，最大 `100`。
`nextToken`	string	否	下一页标记。
`minTimestamp` / `maxTimestamp`	string	否	时间范围，Unix 毫秒时间戳（不支持 RFC3339）。

响应在 tasks 数组中返回任务对象，包含 dreamId、status、taskType、actionCount、proposedCount、confidenceThresholds、createdAt 等字段。

ListMemoryDreamActions

列出整理任务产生的动作（提案）。支持两种查询模式：按 dreamId 查询，或按 scope+actionType 查询（仅 EMIT_SKILL/EMIT_PROFILE）；两者互斥。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`dreamId`	string	否	整理任务 ID（与 `scope` 二选一）。
`scope`	object	否	按 Scope 查询（与 `dreamId` 二选一），此时 `actionType` 必填且仅支持 `EMIT_SKILL`/`EMIT_PROFILE`。
`actionType`	string	否	按 `scope` 查询时必填，仅支持 `EMIT_SKILL`/`EMIT_PROFILE`。
`targetScope`	object	否	按动作的目标 Scope 过滤，可按层级使用 `*`。
`sourceMemoryId`	string	否	按动作的来源记忆 ID 过滤。
`status`	string	否	动作状态过滤：`proposed`/`applied`/`skipped`/`failed`。
`action`	string	否	动作类型过滤：`ADD`/`UPDATE`/`DELETE`/`MERGE`/`NOOP`。
`minConfidence` / `maxConfidence`	float	否	置信度过滤，`0~1`。
`orderBy`	string	否	排序：`created_at_asc`（默认）/`created_at_desc`/`confidence_desc`。
`limit`	int	否	返回数量，默认 `100`，最大 `100`。
`nextToken`	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"
    }
  ]
}

ApplyMemoryDreamActions

应用记忆整理任务产生的提案动作（applyMode=proposal 时）。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`dreamId`	string	是	整理任务 ID。
`actionIds`	array	是	待应用的动作 ID 列表，单次最多 100 个。
`applier`	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 会被拒绝。

CancelMemoryDreamTask

取消尚未完成的记忆整理任务。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`dreamId`	string	是	整理任务 ID。

文件记忆与文件视图接口

文件记忆与文件视图共用 8 个 Item 接口。所有接口均使用固定 URL 的 POST JSON 请求，不使用动态 URL path 或 query 参数。

直接输入记忆文件时，可以新增、读取、更新、重命名、删除文件，并查询或脱敏历史版本。
使用结构化记忆时，可以通过同一组列表和读取接口访问服务生成的只读文件视图。ListItems 响应中的 readOnly: true 表示该视图只读。

Agent Storage SDK 会自动补充 Item 类型。直接调用 HTTP API 时，必须显式传入下列公共字段。

公共请求字段

字段	类型	必填	说明
`type`	string	是	当前固定为 `memoryfile`；缺失或使用其他值返回 `400 VALIDATION_ERROR`。
`memoryStoreName`	string	是	目标记忆库名称。
`scope`	object	是	文件归属范围，必须完整填写 `appId`、`tenantId`、`agentId`、`runId`，不支持通配符。

公共字段示例：

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  }
}

Item 响应对象

字段	类型	说明
`type`	string	固定为 `memoryfile`；单文件响应在顶层回显。
`itemId`	string	文件的稳定标识，查询历史版本时使用。
`path`	string	Scope 内的文件路径。
`content`	string	文件内容。`ListItems` 和元数据读取不返回该字段；空文件在内容读取响应中返回空字符串。
`contentSha256`	string	内容 SHA-256，小写十六进制，无前缀。
`contentSizeBytes`	int64	内容的 UTF-8 字节数。
`latestSeq`	int64	最近一次文件变更的序号。
`createdAt`	string	文件创建时间，RFC3339 格式。
`updatedAt`	string	文件最近更新时间，RFC3339 格式。

ItemVersion 响应对象

字段	类型	说明
`type`	string	固定为 `memoryfile`；单版本响应在顶层回显。
`versionId`	string	版本 ID。
`itemId`	string	文件 ID。
`versionSeq`	int64	版本序号。读取或脱敏单个版本时，需与 `versionId` 一起传入。
`operation`	string	产生版本的操作：`created`、`modified` 或 `deleted`。
`path`	string	该版本对应的文件路径；脱敏后为空字符串。
`content`	string	该版本的内容。版本列表和已脱敏版本不返回该字段。
`contentSha256`	string	该版本的内容摘要；脱敏后为空字符串。
`contentSizeBytes`	int64	该版本的内容字节数；脱敏后为 `0`。
`sessionId`	string	产生该版本的调用方会话标识，未提供时省略。
`createdAt`	string	版本创建时间，RFC3339 格式。
`redacted`	bool	是否已脱敏，仅脱敏后返回。
`redactedAt`	string	首次脱敏时间，RFC3339 格式，仅脱敏后返回。
`redactedBy`	string	首次脱敏请求的 `sessionId`；请求提供 `sessionId` 时返回。

AddItem

新增记忆文件。文件路径在同一个 Scope 内必须唯一。

请求参数

除公共请求字段外，支持以下字段。

字段	类型	必填	说明
`path`	string	是	文件路径。缺少前导 `/` 时服务会自动补充。
`content`	string	否	UTF-8 文件内容，可为空；未提供时创建空文件。
`sessionId`	string	否	调用方会话或操作标识，写入版本记录。

请求示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "content": "# 用户偏好\n\n- 喜欢美式咖啡\n",
  "sessionId": "session-001"
}

响应示例

{
  "type": "memoryfile",
  "itemId": "fmem_019c12345678abcd1234",
  "path": "/profile/preferences.md",
  "content": "# 用户偏好\n\n- 喜欢美式咖啡\n",
  "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
  "contentSizeBytes": 37,
  "latestSeq": 1784786400123456,
  "createdAt": "2026-07-23T10:00:00Z",
  "updatedAt": "2026-07-23T10:00:00Z"
}

ListItems

按路径字节序分页列出文件。列表项不包含 content。

请求参数

字段	类型	必填	说明
`pathPrefix`	string	否	仅列出指定路径前缀下的文件；空值表示全部文件。
`nextToken`	string	否	上一页返回的不透明分页游标，必须与原 `pathPrefix` 一起使用。
`limit`	int	否	单页数量，默认 `100`，最大 `500`。

请求示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "pathPrefix": "/profile/",
  "limit": 100
}

响应示例

{
  "type": "memoryfile",
  "items": [
    {
      "itemId": "fmem_019c12345678abcd1234",
      "path": "/profile/preferences.md",
      "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
      "contentSizeBytes": 37,
      "latestSeq": 1784786400123456,
      "createdAt": "2026-07-23T10:00:00Z",
      "updatedAt": "2026-07-23T10:00:00Z"
    }
  ],
  "nextToken": "L3Byb2ZpbGUvcHJlZmVyZW5jZXMubWQ"
}

nextToken 为空或省略表示已经列完。结构化记忆生成的只读文件视图会在响应顶层额外返回 "readOnly": true；直接输入的文件记忆不返回该字段。

GetItem

按路径读取一个文件。默认返回文件内容，也可以只读取元数据。

请求参数

字段	类型	必填	说明
`path`	string	是	文件路径。
`includeContent`	bool	否	是否返回 `content`，默认 `true`；设为 `false` 时仅返回元数据。

请求示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md"
}

响应示例

{
  "type": "memoryfile",
  "itemId": "fmem_019c12345678abcd1234",
  "path": "/profile/preferences.md",
  "content": "# 用户偏好\n\n- 喜欢美式咖啡\n",
  "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
  "contentSizeBytes": 37,
  "latestSeq": 1784786400123456,
  "createdAt": "2026-07-23T10:00:00Z",
  "updatedAt": "2026-07-23T10:00:00Z"
}

includeContent=false 时响应形状相同，但省略 content。空文件在内容读取响应中明确返回 "content": ""。

UpdateItem

更新文件内容或重命名文件。content 与 newPath 必须恰好提供一个；同时提供或都不提供会返回 400 VALIDATION_ERROR。

请求参数

字段	类型	必填	说明
`path`	string	是	当前文件路径。
`content`	string	条件必填	新的 UTF-8 内容，可为空字符串；与 `newPath` 二选一。
`newPath`	string	条件必填	重命名后的路径；与 `content` 二选一。
`overwrite`	bool	否	重命名时是否允许替换已存在的目标文件，默认 `false`。
`expectedSha256`	string	否	当前内容摘要。提供后，摘要不匹配会返回 `409 SHA_MISMATCH`。
`sessionId`	string	否	调用方会话或操作标识。

更新内容示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "content": "# 用户偏好\n\n- 喜欢拿铁\n",
  "expectedSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece"
}

重命名示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "newPath": "/profile/user-preferences.md",
  "overwrite": false,
  "expectedSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc"
}

两种操作均返回变更后的完整 Item（包含 content）。未传 expectedSha256 时，服务仍会基于最新状态执行受保护的有限次重试，并非无条件覆盖；高并发下仍可能返回 409 SHA_MISMATCH。多个写入方修改同一路径时，建议始终传入最近一次读取到的摘要。

DeleteItem

删除当前文件，并保留可查询的删除版本。

请求参数

字段	类型	必填	说明
`path`	string	是	要删除的文件路径。
`expectedSha256`	string	否	当前内容摘要，用于并发保护。
`sessionId`	string	否	调用方会话或操作标识。

请求示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/user-preferences.md",
  "expectedSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc"
}

响应示例

{
  "type": "memoryfile"
}

ListItemVersions

按时间倒序分页列出一个文件的历史版本。列表项不包含 content。

请求参数

字段	类型	必填	说明
`itemId`	string	是	文件 ID。
`path`	string	否	当前文件路径；通常无需传入。
`nextToken`	string	否	上一页返回的不透明分页游标。
`limit`	int	否	单页数量，默认 `100`，最大 `500`。
`operation`	string	否	按 `created`、`modified` 或 `deleted` 筛选。

请求示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "limit": 20
}

响应示例

{
  "type": "memoryfile",
  "versions": [
    {
      "versionId": "fmver_019c12349999abcd5678",
      "itemId": "fmem_019c12345678abcd1234",
      "versionSeq": 1784786700123456,
      "operation": "modified",
      "path": "/profile/user-preferences.md",
      "contentSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc",
      "contentSizeBytes": 31,
      "sessionId": "session-001",
      "createdAt": "2026-07-23T10:05:00Z"
    }
  ]
}

GetItemVersion

读取一个指定历史版本。必须同时传入列表响应中的 itemId、versionId 和 versionSeq。

请求参数

字段	类型	必填	说明
`itemId`	string	是	文件 ID。
`versionId`	string	是	版本 ID。
`versionSeq`	int64	是	大于 `0` 的版本序号。

请求示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "versionId": "fmver_019c12349999abcd5678",
  "versionSeq": 1784786700123456
}

响应示例

{
  "type": "memoryfile",
  "versionId": "fmver_019c12349999abcd5678",
  "itemId": "fmem_019c12345678abcd1234",
  "versionSeq": 1784786700123456,
  "operation": "modified",
  "path": "/profile/user-preferences.md",
  "content": "# 用户偏好\n\n- 喜欢拿铁\n",
  "contentSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc",
  "contentSizeBytes": 31,
  "sessionId": "session-001",
  "createdAt": "2026-07-23T10:05:00Z"
}

已脱敏版本仍返回 200，并带有脱敏标记与审计字段，但不返回 content。

RedactItemVersion

不可逆地脱敏一个历史版本。脱敏不会修改当前文件，不会改变 latestSeq，也不会产生新版本。

请求参数

字段	类型	必填	说明
`itemId`	string	是	文件 ID。
`versionId`	string	是	版本 ID。
`versionSeq`	int64	是	大于 `0` 的版本序号。
`sessionId`	string	否	脱敏操作方标识，记录到 `redactedBy`。

请求示例

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "versionId": "fmver_019c12349999abcd5678",
  "versionSeq": 1784786700123456,
  "sessionId": "privacy-job-001"
}

响应示例

{
  "type": "memoryfile",
  "versionId": "fmver_019c12349999abcd5678",
  "itemId": "fmem_019c12345678abcd1234",
  "versionSeq": 1784786700123456,
  "operation": "modified",
  "path": "",
  "contentSha256": "",
  "contentSizeBytes": 0,
  "sessionId": "session-001",
  "createdAt": "2026-07-23T10:05:00Z",
  "redacted": true,
  "redactedAt": "2026-07-23T11:00:00Z",
  "redactedBy": "privacy-job-001"
}

脱敏请求幂等。重复请求返回当前脱敏状态，redactedAt 和 redactedBy 保留首次成功请求的值。

文件能力差异

操作	文件记忆	结构化记忆的文件视图
新增、更新、重命名、删除	支持	返回 `409 READ_ONLY_STORE`
列出、读取	支持	支持；`ListItems` 返回 `readOnly: true`
列出、读取、脱敏历史版本	支持	不可用，返回 `400`

文件接口常见错误

HTTP 状态码	错误码	触发条件
`400`	`VALIDATION_ERROR`	Item 类型、Scope、路径、分页游标、更新分支或版本参数无效；当前文件视图不提供版本能力。
`400`	`INVALID_PARAMETER`	对不提供文件能力的记忆库调用 Item 接口。
`404`	`NOT_FOUND`	文件或历史版本不存在。
`409`	`PATH_EXISTS`	新建路径或重命名目标已存在。
`409`	`SHA_MISMATCH`	`expectedSha256` 与当前内容不匹配，或高并发更新未能完成。
`409`	`LOCK_CONFLICT`	同一 Scope 正在发生并发变更，可短暂退避后重试。
`409`	`QUOTA_EXCEEDED`	当前 Scope 的文件数量达到上限。
`409`	`READ_ONLY_STORE`	尝试修改结构化记忆生成的只读文件视图。
`413`	`PAYLOAD_TOO_LARGE`	文件内容超过单文件大小限制。

发生 SHA_MISMATCH 或 LOCK_CONFLICT 时，重新读取最新文件后再决定是否重试。文件接口的完整限制以限制与注意事项为准。SDK 接入方式见 Agent Storage SDK。