ListMemories 列出记忆 - 表格存储

使用 ListMemories 接口列出长期记忆。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
Scope 规则：可按层级使用通配符 *（左前缀规则：* 之后的字段必须也是 * 或为空）；空字段按 __default__ 处理。建议至少提供 appId。

请求参数

字段	类型	必填	说明
`memoryStoreName`	string	是	记忆库名称。
`scope`	object	否	Scope。可按层级使用通配符 ``（左前缀规则：`` 之后的字段必须也是 `*` 或为空）；空字段按 `__default__` 处理。建议至少提供 `appId`。
`filter`	object	否	Scope Filter。与 `scope` 按 AND 关系生效，仅选择 conversation Scope。部分存量记忆库不支持 `filter`，返回 `INVALID_PARAMETER` 时请改用精确或通配 Scope。
`limit`	int	否	返回数量，默认 50，最大 100。
`nextToken`	string	否	下一页标记。只能用于与上一页相同的 `scope` 和 `filter`。

请求示例

使用 API Key 认证时，通过 x-ots-instancename 和 x-ots-apikey 请求头传入实例名和 API Key。

curl -X POST https://<endpoint>/ListMemories \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "limit": 20
}'

使用 Filter 列出多个会话中的记忆：

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "filter": {
    "op": "eq",
    "field": "text",
    "value": "*sess*"
  },
  "limit": 20
}

响应

字段	说明
`memories`	长期记忆单元列表，单元字段与 `SearchMemories` 的 `results[].unit` 一致。
`nextToken`	下一页标记；没有更多数据时省略。
`scope`	查询使用的 Scope。
`memoryStoreName`	记忆库名称。

{
  "memories": [
    {
      "id": "3a8d77658e7e92522f2f3ebefb16290e",
      "text": "用户常驻杭州。",
      "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-002" },
      "unit_type": "atomic_fact",
      "created_at": "2026-09-20T03:28:50Z"
    }
  ],
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" }
}

使用 filter 时，结果按 Scope 分组，Scope 组按服务生成的 scopeKey 升序排列；同一 Scope 内按创建时间从新到旧排列，创建时间相同时按记忆 ID 降序排列。单次请求最多扫描 100 个 Scope，因此返回数量可能少于 limit，甚至为空，但仍可能携带 nextToken。调用方应持续翻页，直到 nextToken 为空。

Scope 查询能力暂时不可用时，接口返回 HTTP 503 和 SERVICE_UNAVAILABLE。无效、过期或与其他查询条件混用的 nextToken 返回 HTTP 400 和 INVALID_PARAMETER。