ListMemories List memories - Tablestore - Centre de documentation Alibaba Cloud

Prérequis

Vous avez créé une instance AgentStorage dont le statut est normal, et vous avez obtenu le nom de l'instance ainsi que son endpoint.
Vous avez créé une API Key.
Règles de portée : vous pouvez utiliser le caractère générique * à n'importe quel niveau (règle du préfixe gauche : les champs situés après * doivent également être * ou vides) ; les champs vides sont traités comme __default__. Nous vous recommandons de fournir au moins appId.

Paramètres de requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Nom du magasin de mémoires.

scope

object

Non

Portée. Vous pouvez utiliser le caractère générique * à n'importe quel niveau (règle du préfixe gauche : les champs situés après * doivent également être * ou vides) ; les champs vides sont traités comme __default__. Nous vous recommandons de fournir au moins appId.

filter

object

Non

Filtre de portée. Combiné avec scope via une relation ET, il sélectionne uniquement la portée de conversation. Certains magasins de mémoires existants ne prennent pas en charge filter ; si INVALID_PARAMETER est renvoyé, utilisez une portée exacte ou avec caractères génériques à la place.

limit

int

Non

Nombre d'entrées à renvoyer. Valeur par défaut : 50. Maximum : 100.

nextToken

string

Non

Jeton de pagination pour la page suivante. Il ne peut être utilisé qu'avec les mêmes valeurs scope et filter que celles de la page précédente.

Exemples de requêtes

Lorsque vous utilisez l'authentification par API Key, transmettez le nom de l'instance et la clé API via les en-têtes de requête x-ots-instancename et x-ots-apikey.

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

Utilisez un filtre pour répertorier les mémoires sur plusieurs conversations :

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

Réponse

Champ

Description

memories

Liste des unités de mémoire à long terme. Les champs de l'unité sont identiques à ceux de results[].unit dans SearchMemories.

nextToken

Jeton de pagination pour la page suivante. Omis lorsqu'il n'y a plus de données.

scope

Portée utilisée pour la requête.

memoryStoreName

Nom du magasin de mémoires.

{
  "memories": [
    {
      "id": "3a8d77658e7e92522f2f3ebefb16290e",
      "text": "The user is based in Hangzhou.",
      "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": "*" }
}

Lorsque filter est utilisé, les résultats sont regroupés par portée. Les groupes de portée sont triés par ordre croissant selon la valeur scopeKey générée par le service. Au sein d'une même portée, les mémoires sont triées par date de création, de la plus récente à la plus ancienne ; lorsque les dates de création sont identiques, elles sont triées par ID de mémoire par ordre décroissant. Une seule requête analyse au maximum 100 portées, de sorte que le nombre d'entrées renvoyées peut être inférieur à limit ou même nul, mais un nextToken peut toujours être renvoyé. L'appelant doit continuer la pagination jusqu'à ce que nextToken soit vide.

Lorsque la fonctionnalité de requête de portée est temporairement indisponible, l'interface renvoie le code HTTP 503 et SERVICE_UNAVAILABLE. Un nextToken invalide, expiré ou mixte utilisé avec d'autres conditions de requête renvoie le code HTTP 400 et INVALID_PARAMETER.