ListMemories List memories - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

An AgentStorage instance has been created and its status is normal, and the instance endpoint and instance name have been obtained.
An API Key has been created.
Scope rules: You can use the wildcard * at any level (left-prefix rule: fields after * must also be * or empty); empty fields are treated as __default__. We recommend that you provide at least appId.

Request parameters

Field	Type	Required	Description
`memoryStoreName`	string	Yes	The name of the memory store.
`scope`	object	No	The scope. You can use the wildcard `` at any level (left-prefix rule: fields after `` must also be `*` or empty); empty fields are treated as `__default__`. We recommend that you provide at least `appId`.
`filter`	object	No	Scope Filter. Combined with `scope` using an AND relationship, it selects only the conversation scope. Some existing memory stores do not support `filter`; if `INVALID_PARAMETER` is returned, use an exact or wildcard scope instead.
`limit`	int	No	The number of entries to return. Default: 50. Maximum: 100.
`nextToken`	string	No	The pagination token for the next page. It can only be used with the same `scope` and `filter` as the previous page.

Request examples

When you use API Key authentication, pass the instance name and API Key through the x-ots-instancename and x-ots-apikey request headers.

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
}'

Use a filter to list memories across multiple conversations:

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

Response

Field	Description
`memories`	The list of long-term memory units. The unit fields are the same as `results[].unit` of `SearchMemories`.
`nextToken`	The pagination token for the next page. Omitted when there is no more data.
`scope`	The scope used for the query.
`memoryStoreName`	The name of the memory store.

{
  "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": "*" }
}

When filter is used, the results are grouped by scope. Scope groups are sorted in ascending order by the scopeKey generated by the service. Within the same scope, memories are sorted by creation time from newest to oldest; when creation times are equal, they are sorted by memory ID in descending order. A single request scans at most 100 scopes, so the number of returned entries may be less than limit or even empty, but a nextToken may still be returned. The caller should keep paginating until nextToken is empty.

When the scope query capability is temporarily unavailable, the interface returns HTTP 503 and SERVICE_UNAVAILABLE. An invalid, expired, or mixed nextToken used with other query conditions returns HTTP 400 and INVALID_PARAMETER.