Limites et quotas de Memory Storage : mémoire de fichier, Scope, SDK et CLI -

Disponibilité du service et limites des ressources

Régions

Memory Storage est disponible uniquement dans les régions Chine (Pékin) et Chine (Hangzhou).

Limites des magasins de mémoire

Élément

Limite

Caractères autorisés dans le nom du magasin de mémoire

Lettres, chiffres et traits de soulignement uniquement

Longueur du nom du magasin de mémoire

Jusqu'à 32 caractères

Longueur de la description du magasin de mémoire

Jusqu'à 1 024 octets en UTF-8

Longueur des instructions d'extraction personnalisées extractInstructions

Jusqu'à 4 096 caractères

Après avoir créé un magasin de mémoire, attendez la fin de l'initialisation de l'index avant d'écrire ou de rechercher des données.

extractInstructions spécifie des instructions d'extraction de mémoire personnalisées au niveau du magasin de mémoire. Ces instructions sont injectées dans l'invite d'extraction et influencent l'extraction ultérieure de la mémoire à long terme dans le magasin de mémoire. Définissez ces instructions lors de l'appel à CreateMemoryStore ou modifiez-les en appelant UpdateMemoryStore. Pour effacer les instructions, transmettez une chaîne vide. Si vous omettez ce champ, les instructions existantes restent inchangées.

Limites des opérations de mémoire

Règles de périmètre (Scope)

Opération

Exigence de périmètre (Scope)

Joker * autorisé

Ajouter des mémoires

appId est requis. Les niveaux inférieurs vides sont automatiquement définis sur __default__.

Non

Rechercher des mémoires à long terme

appId et tenantId sont requis.

Autorisé pour agentId et runId

Interroger des mémoires à court terme

Les quatre niveaux de périmètre (Scope) sont requis.

Non

Obtenir une mémoire à long terme

Les quatre niveaux de périmètre (Scope) sont requis.

Non

Mettre à jour une mémoire à long terme

Les quatre niveaux de périmètre (Scope) sont requis.

Non

Supprimer une mémoire à long terme

Les quatre niveaux de périmètre (Scope) sont requis.

Non

Lister des mémoires à long terme

Spécifiez le périmètre (Scope) par niveau.

Oui

Lister les valeurs de périmètre (Scope) (ListMemoryStoreScopes)

Spécifiez le périmètre (Scope) par niveau.

Oui

Interroger les tâches d'extraction (ListMemoryTasks)

Spécifiez le périmètre (Scope) par niveau.

Oui

Interroger les audits de requêtes

Spécifiez le périmètre (Scope) par niveau.

Oui

Les jokers doivent respecter la hiérarchie du périmètre (Scope). Après avoir utilisé * à un niveau donné, tous les niveaux suivants doivent également utiliser * ou rester vides. Par exemple, app-001/user-001/*/* est valide, mais app-001/*/agent-001/* ne l'est pas.

Limites de la mémoire de fichier et de l'affichage des fichiers

Élément

Limite ou comportement

Périmètre (Scope)

Les quatre niveaux, appId, tenantId, agentId et runId, sont requis. Le joker * n'est pas pris en charge.

Chemin du fichier

Le chemin canonique doit commencer par / et peut atteindre 800 octets en UTF-8. Le chemin ne peut pas être le répertoire racine ni contenir de segments de chemin vides, ., .. ou des caractères NUL.

Contenu du fichier

Texte UTF-8 valide uniquement

Taille du fichier

Jusqu'à 100 Kio (102 400 octets) par fichier

Fichiers actuels dans un périmètre (Scope)

Jusqu'à 2 000 fichiers par défaut

Pagination de la liste des fichiers

limit a pour valeur par défaut 100 et peut atteindre 500.

Écritures concurrentes

expectedSha256 est facultatif. Si plusieurs rédacteurs modifient le fichier, transmettez le condensé issu de la dernière lecture.

Caviardage des versions historiques

Irréversible. Le caviardage efface uniquement les versions historiques sélectionnées et ne modifie pas le fichier actuel.

Affichages de fichiers

Lecture seule. Gérez les mémoires à l'aide d'interfaces structurées telles que le SDK ou la CLI.

Si le contenu du fichier, le chemin ou le nombre de fichiers dépasse la limite correspondante, le service renvoie respectivement PAYLOAD_TOO_LARGE, VALIDATION_ERROR ou QUOTA_EXCEEDED. Si le condensé d'une écriture concurrente ne correspond pas, le service renvoie SHA_MISMATCH. Lisez le dernier fichier avant de décider de réessayer.

Limites d'écriture de mémoire

Élément

Limite

Nombre de messages

Jusqu'à 20

Longueur totale du contenu des messages

Jusqu'à 32 000 octets en UTF-8

Longueur du text

Jusqu'à 32 000 octets en UTF-8

Longueur de messageId

Jusqu'à 256 caractères

Nombre de clés metadata

Jusqu'à 16

Longueur de la clé metadata

Jusqu'à 64 caractères

Longueur de la valeur metadata

Jusqu'à 1 024 caractères

Fournissez au moins l'un des éléments suivants : messages ou text. Le joker * n'est pas autorisé dans le périmètre (Scope) lors de l'ajout de mémoires.

Visibilité des écritures asynchrones

AddMemories.sync a pour valeur par défaut false, ce qui active les écritures asynchrones. Les écritures asynchrones deviennent visibles comme suit :

Les messages bruts sont écrits en premier et peuvent être interrogés immédiatement en tant que mémoires à court terme.
L'extraction de la mémoire à long terme s'exécute en arrière-plan.
Une fois l'extraction de la mémoire à long terme et l'actualisation de l'index terminées, les mémoires peuvent être récupérées en appelant SearchMemories.

Pour afficher immédiatement les résultats d'extraction après une écriture lors d'un test, définissez sync sur true. Un bref délai d'actualisation de l'index peut toujours se produire avant que les mémoires à long terme ne soient consultables après la fin d'une écriture synchrone. Appelez également GetMemoryTask et transmettez le requestId renvoyé par AddMemories pour interroger l'état de la tâche d'extraction asynchrone et les identifiants des unités de mémoire extraites.

Valeurs par défaut de recherche

Paramètre

Valeur par défaut

Description

topK

10

Nombre maximal de résultats à renvoyer. La valeur par défaut est 10 et le maximum est 50. Le filtrage par pertinence ou la déduplication sémantique peuvent entraîner un nombre de résultats inférieur à topK.

enableRerank

true

Indique si le reclassement est activé.

includeEvidence

false

Indique si les preuves sources à court terme doivent être incluses dans le champ evidence de chaque résultat.

minSimilarity

0

Seuil de pertinence dans la plage 0~1. Une valeur de 0 désactive le filtrage. Une valeur supérieure à 0 filtre les résultats dont les scores de pertinence sont inférieurs au seuil. Lorsque le reclassement est activé, le score correspond au score de pertinence du reclassement. Sinon, le score correspond à la similarité cosinus normalisée.

Lorsque vous recherchez des mémoires à long terme, appId et tenantId sont requis. Vous pouvez utiliser le joker * pour agentId et runId.

Interrogations de mémoires à court terme

ListMemoryStoreMessages interroge les messages de session bruts. Les quatre niveaux de périmètre (Scope), appId, tenantId, agentId et runId, sont requis. Les jokers ne sont pas pris en charge.

Utilisez cette API pour :

Afficher les messages de session bruts.
Rejouer une session spécifique.
Dépanner l'extraction de la mémoire à long terme.

Limites de la consolidation de mémoire (Dream)

La consolidation de mémoire (Dream) est une tâche asynchrone qui affine et fusionne davantage les mémoires stockées, et extrait des compétences et des profils. Les API associées sont CreateMemoryDreamTask, GetMemoryDreamTask, ListMemoryDreamTasks, ListMemoryDreamActions, ApplyMemoryDreamActions et CancelMemoryDreamTask.

Limites de CreateMemoryDreamTask

Élément

Limite

Nombre de scopes

Requis. Jusqu'à 20.

maxSessions

0~100

maxMessages

0~20000

maxMemories

0~5000

expandedScopeLimit

0~1000

Longueur des instructions

Jusqu'à 4 000 octets en UTF-8

actionIds pour ApplyMemoryDreamActions

Jusqu'à 100 par requête

Valeurs d'énumération

Champ

Valeurs

taskType

memory (par défaut) / skill / profile

applyMode

proposal (par défaut) / safe_auto. Pris en charge uniquement lorsque taskType=memory.

scopeOutputMode

preserve_scope (par défaut) / promote_scope

Clés confidenceThresholds

add / update / merge. Les valeurs vont de 0~1. DELETE ne prend pas en charge de seuil de confiance automatique.

État de la tâche (status de la tâche)

queued / running / planning / applying / completed / completed_with_failures / failed / cancelled

Type d'action (action)

ADD / UPDATE / DELETE / MERGE / NOOP / EMIT_SKILL / EMIT_PROFILE

État de l'action (status de l'action)

proposed / applied / skipped / failed

Lorsque applyMode=proposal, la tâche génère des actions dans l'état proposed. Appelez ApplyMemoryDreamActions pour appliquer explicitement les actions. Lorsque safe_auto est utilisé, le service applique automatiquement les actions sûres qui satisfont aux seuils de confiance. Les actions EMIT_SKILL et EMIT_PROFILE sont écrites directement par la tâche Dream et ne nécessitent pas d'application manuelle.

Tâches asynchrones et pagination des listes

API

Limite par défaut

Limite maximale

ListMemoryTasks

50

100

ListMemoryStoreScopes

100

ListMemoryDreamTasks

50

100

ListMemoryDreamActions

100

Les valeurs d'état des tâches d'extraction pour ListMemoryTasks.status ou task.status renvoyées par GetMemoryTask sont queued / running / completed / failed / needs_reconcile.

GetMemoryTask et ListMemoryTasks dépendent de l'index des tâches. Après la première écriture, le service nécessite un certain temps pour construire l'index des tâches. Pendant cette période, ces API peuvent renvoyer 409 CONFLICT avec le message ingest task index is still building, please retry shortly. Réessayez ultérieurement.

CLI, SDK et plugins

Pagination de la CLI

Les commandes de liste de la CLI liées à la mémoire renvoient une seule page de résultats et ne récupèrent pas automatiquement les pages suivantes. Pour récupérer la page suivante, utilisez le nextToken issu de la réponse.

Exemple :

tablestore-agent-cli memory list-units \
  --store agent_memory \
  --app-id app-001 \
  --next-token <token>

Création automatique d'instance Tablestore

Si ots_endpoint et ots_instance_name ne sont pas configurés, la CLI crée et réutilise automatiquement une instance Tablestore gérée dans la région Chine (Pékin) ou Chine (Hangzhou) lorsque vous exécutez la commande doctor ou effectuez une opération. La création de l'instance prend un certain temps et le résultat est écrit dans le fichier de configuration local.

Si vous configurez manuellement un point de terminaison et un nom d'instance ultérieurement, la CLI utilise l'instance explicitement configurée.

Versions du SDK et de la CLI

SDK ou outil

Version requise

SDK Python

tablestore >= 6.4.7 (6.4.5 et versions ultérieures prennent en charge les API de mémoire de base ; 6.4.7 et versions ultérieures prennent en charge les API de tâche et de consolidation de mémoire)

SDK Node.js

tablestore >= 5.6.5

Agent Storage SDK pour Python

tablestore-agent-storage >= 1.0.10

Agent Storage SDK pour TypeScript

@tablestore/agent-storage >= 0.0.11

Agent Storage SDK pour Go

github.com/aliyun/tablestore-agent-storage-sdk/go

CLI

@tablestore/tablestore-agent-cli >= 0.2.5

Remarques sur les plugins d'agent

Par défaut, les plugins Hermes et OpenClaw effectuent des recherches parmi les agents et les sessions du locataire actuel, en utilisant agentId=* et runId=*. Si votre activité professionnelle n'autorise pas le partage de mémoires entre agents ou sessions, utilisez le SDK pour contrôler le périmètre (Scope) de recherche ou modifiez la configuration du plugin.

Limites de mise à niveau progressive et de restauration

Les trois commutateurs suivants sont désactivés par défaut et fonctionnent de manière indépendante :

memory_unit_v2_write_enabled=false : le service ne génère ni n'accepte les champs d'écriture V2.
memory_unit_v2_projection_enabled=false : le service conserve le format d'octet hérité pour les projections de fichiers.
search_session_affinity_mode=off : le service conserve le comportement de recherche à voie unique hérité et les champs de réponse associés.

Procédez à un déploiement serveur en premier lieu. Commencez par mettre à niveau tous les réplicas vers une version capable de lire les colonnes V2 et de reconnaître contextScope ainsi que les nouveaux champs de réponse, tout en maintenant les commutateurs désactivés. Une fois tous les réplicas hérités supprimés, les clients peuvent commencer à envoyer contextScope. Ensuite, changez le mode en shadow puis en on. Les serveurs hérités rejettent strictement les champs inconnus. Si les clients envoient contextScope avant que tous les réplicas ne soient mis à niveau, le cluster en version mixte renvoie une erreur HTTP 400.

N'activez pas les écritures V2 ni les projections de fichiers V2 dans un cluster en version mixte. Après l'écriture d'une ligne V2, ne revenez pas directement à un analyseur ou un rédacteur hérité qui ne reconnaît pas les colonnes V2. Une écriture de ligne entière héritée peut écraser ou supprimer les nouveaux champs. Pour restaurer le comportement de l'application, revenez à une version compatible capable de lire les données V2 avec tous les nouveaux commutateurs désactivés, plutôt que de revenir à un binaire antérieur à V2.