通用对象-表格存储 Tablestore(Tablestore)-阿里云帮助中心

记忆存储接口复用以下 Scope、Agent Scope、Scope Filter、Message 和 Metadata 数据结构。

Scope

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

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

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

场景	Scope 规则
写入（`AddMemories`）	`appId` 必填；其他字段省略时补 `__default__`；不允许使用 `*`。
检索（`SearchMemories`）	`appId` 必填且不能为 ``；其他字段省略时补 `__default__`，只有显式传入 `` 才通配。
查询短期消息（`ListMemoryStoreMessages`）	四级字段全部必填，不允许使用 `*`。
获取、更新、删除单条长期记忆	`scope` 可选；提供时四级字段全部必填，不允许使用 `*`。
精确文件操作	四级字段全部必填，不允许使用 `*`。服务生成的只读文件仅支持精确 Scope。
应用管理文件的列表和范围操作	`appId`、`tenantId` 必填；`agentId`、`runId` 支持按层级使用 `*`。
批量删除文件版本（DeleteItemVersions）	`appId`、`tenantId` 必须为确定值；必须包含通配符，建议显式填写 `runId=""`，`agentId` 为确定值或 ``；不支持精确 Scope 或跨租户删除。
`ListMemoryStoreScopes`	`scope` 可选并支持按层级使用 `*`；也可以使用结构化 `filter`。
其他列表查询	Scope 可按层级指定；省略的字段按 `__default__` 处理，支持按层级使用 `*`。

一旦某个层级使用 *，后续层级也必须使用 * 或省略。例如 app-001/user-001/*/* 有效，app-001/*/assistant/* 无效。

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

Agent Scope

Wiki 使用三段 Agent Scope，只包含 appId、tenantId 和 agentId。三个字段均必填、最长 128 字节，不能包含 /，不允许使用 *。Wiki 请求不能传入 runId。

同一 Agent Scope 在一个记忆库中只有一个 Wiki，不同 runId 的会话共享该 Wiki。

Scope Filter

SearchMemories、ListMemories 和 ListMemoryStoreScopes 支持使用 filter 对 Scope 做结构化过滤。scope 与 filter 同时提供时，两者按 AND 关系生效。filter 仅匹配 Scope，不匹配记忆正文或 Metadata。

`op`	字段	说明
`and`、`or`	`conditions`	`conditions` 为一个或多个子条件。
`not`	`condition`	`condition` 为一个子条件。也兼容只包含一个元素的 `conditions` 写法。
`eq`	`field`、`value`	精确匹配字符串。虚拟字段 `text` 也使用该操作符。
`in`	`field`、`values`	匹配字符串数组中的任意一个值，`values` 不得为空。
`exists`	`field`	匹配包含该字段的 Scope。

可过滤字段包括 scopeType、scopeKey、appId、tenantId、agentId、runId、wikiId 和虚拟字段 text。conversation Scope 使用 agentId、runId，Wiki Scope 使用 wikiId。普通字段只支持精确匹配；不支持 prefix、wildcard 和 range 操作符。

text 在 Scope 的字段值中进行短片段匹配，仅支持 op: "eq"。其 value 可使用 * 匹配任意长度的字符序列、使用 ? 匹配一个 Unicode 字符，例如 *abc*。模式不能为空，最长 32 个 Unicode 字符；除 * 外的字符总数不能超过 4。

{
  "op": "and",
  "conditions": [
    { "op": "eq", "field": "appId", "value": "app-001" },
    { "op": "eq", "field": "text", "value": "*abc*" }
  ]
}

filter 最多嵌套 8 层，最多包含 64 个叶子条件。分页请求必须保持 scope 和 filter 不变，不能将同一个 nextToken 用于其他查询条件。

filter 依赖目标记忆库的 Scope 查询能力。部分存量记忆库不支持 filter，或不支持 text 虚拟字段。返回 INVALID_PARAMETER 时，请改用精确或通配 Scope；返回 SERVICE_UNAVAILABLE 时请先退避重试，如 text 条件持续不可用，再改用普通字段的 eq、in、exists 条件。

Message

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

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

Metadata

Metadata 为字符串键值对，用于附加业务标签。在 SearchMemories 中，Metadata 用于完整字符串的精确匹配过滤；传入多个键值对时，结果必须同时匹配全部条件。*、?、逗号和等号等字符按普通字符处理，不表示通配。

限制项	取值
单个 Metadata 对象最多键数	16 个
键长度上限	64 个 Unicode 字符
单个 Metadata 对象的 JSON 大小上限	65536 字节（UTF-8，64 KiB）

AddMemories 的顶层 metadata，以及顶层与每条消息的 metadata 合并后得到的消息级 Metadata，均需分别满足上述限制。写入的单个值没有单独的 1024 字符上限；但 SearchMemories.metadata 中每个查询值最多为 1024 个 Unicode 字符。超过该长度的已存值可以读取，但不能作为 Metadata 检索条件。

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

outputTypes 包含 structured 的记忆库支持上述完整精确匹配，适合检索 UUID、追踪 ID 等长值。