记忆存储服务 HTTP JSON 接口规范、参数与 Scope 必填规则速查 - 表格存储

记忆存储服务通过 HTTP JSON 协议提供 13 个接口，覆盖记忆库管理、长期记忆读写、短期记忆与审计查询，适用于无 SDK 的自定义集成场景。

接口列表

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

记忆库管理

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

长期记忆

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

短期记忆与审计

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

通用对象

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

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 全部必填	不允许使用 `*`。
列表查询（`ListMemories`、`ListMemoryStoreRequests`）	`appId`	支持按层级使用 `*`。

示例：

{
  "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 个字符。

请求示例

{
  "memoryStoreName": "agent_memory",
  "description": "Agent 长期记忆库"
}

GetMemoryStore

获取记忆库详情。

请求参数

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

请求示例

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

更新记忆库描述。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`description`	string	是	新描述，最长 1024 个字符。

DeleteMemoryStore

删除记忆库。

警告

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

请求参数

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

ListMemoryStores

列出记忆库。

请求参数

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

AddMemories

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

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	目标记忆库名称。
`scope`	object	是	Scope。写入时 `appId` 必填，不允许使用通配符 `*`。
`messages`	array	与 `text` 二选一	对话消息数组，最多 20 条；总内容长度不超过 32000 个字符。
`text`	string	与 `messages` 二选一	文本内容，最长 32000 个字符。
`metadata`	object	否	写入级元数据，最多 16 个键，键最长 64 个字符，值最长 1024 个字符。
`sync`	boolean	否	是否同步等待记忆抽取完成，默认 `false`。

各项上限的完整说明，请参见限制与注意事项。

请求示例：写入消息

{
  "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` 可使用通配符 `*`。
`topK`	int	否	返回数量，默认 `10`，取值范围 `1~50`。
`enableRerank`	boolean	否	是否启用 Rerank，默认 `true`。
`metadata`	object	否	元数据精确匹配过滤条件，键和值均为字符串。

topK 取值上限的完整说明，请参见限制与注意事项。

请求示例

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

响应字段

字段	说明
`results`	检索结果列表。
`results[].unit`	长期记忆单元，字段定义见下表。
`results[].score`	相关性分数。
`scope`	查询使用的 Scope。
`memoryStoreName`	记忆库名称。

results[].unit 内部字段如下。

字段	说明
`id`	长期记忆单元 ID。
`conversation_key`	关联的会话键。
`scope`	记忆所属 Scope，对象包含 `appId`、`tenantId`、`agentId`、`runId` 四个字段。
`memcell_id`	记忆片段 ID。
`unit_type`	记忆单元类型。
`text`	记忆文本。
`search_text`	用于检索的文本。
`source_turn_ids`	来源消息 ID 列表。
`type_label`	类型标签。
`date_bucket`	日期分桶。
`metadata_json`	元数据，JSON 字符串。
`deleted`	是否已删除。
`created_at`	创建时间。
`salience`	显著性分数。
`version`	版本号。

ListMemories

列出长期记忆。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	是	Scope。`appId` 和 `tenantId` 必填，`agentId` 和 `runId` 可使用通配符 `*`。
`limit`	int	否	返回数量。
`nextToken`	string	否	下一页标记。

请求示例

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

GetMemory

获取单条长期记忆。

请求参数

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

UpdateMemory

更新单条长期记忆。text 和 metadata 至少提供一个。

请求参数

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

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
}

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`	记录创建时间。