Utilisation de la mémoire d'agent

Chaque session Managed Agents démarre par défaut avec un contexte vierge. Lorsqu'une session se termine, tout l'état que l'agent a accumulé disparaît. Les « memory stores » (magasins de mémoire) permettent à l'agent de transporter des informations d'une session à l'autre : préférences utilisateur, conventions de projet, erreurs passées et contexte de domaine.



Vue d'ensemble

Un magasin de mémoire est une collection de documents texte limitée à un espace de travail et optimisée pour Claude. Lorsque vous attachez un magasin à une session, il est monté en tant que répertoire à l'intérieur du bac à sable de la session. L'agent le lit et y écrit avec les mêmes outils de fichiers qu'il utilise pour le reste du système de fichiers, et une note décrivant chaque montage est automatiquement ajoutée à l'invite système, indiquant à l'agent où chercher. L'ensemble d'outils de l'agent est requis pour ces interactions ; assurez-vous de l'activer lors de la création de l'agent.

Chaque mémoire dans un magasin est adressée par un chemin et peut être lue et modifiée directement via l'API ou la Console, ce qui permet l'ajustement, l'importation et l'exportation.

Chaque modification apportée à une mémoire crée une version de mémoire immuable, vous offrant une piste d'audit et une récupération à un instant donné pour tout ce que l'agent écrit.



Créer un magasin de mémoire

Donnez au magasin un name et une description. La description est transmise à l'agent, lui indiquant ce que contient le magasin.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

L'id du magasin de mémoire (memstore_...) est ce que vous transmettez lors de l'attachement du magasin à une session.



Préremplir avec du contenu (facultatif)

Préchargez un magasin avec du matériel de référence avant toute exécution d'agent :

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null



Attacher un magasin de mémoire à une session

Les magasins de mémoire sont attachés dans le tableau resources[] de la session lors de sa création. Contrairement aux ressources de fichiers et de dépôts, les magasins de mémoire ne peuvent être attachés qu'au moment de la création de la session ; l'ajout ou la suppression d'un magasin dans une session en cours d'exécution n'est pas pris en charge.

Incluez éventuellement des instructions pour fournir des directives spécifiques à la session sur la manière dont l'agent doit utiliser ce magasin. Elles sont présentées à l'agent aux côtés du name et de la description du magasin, et sont limitées à 4 096 caractères.

Vous pouvez également configurer access. La valeur par défaut est read_write (indiquée explicitement dans l'exemple suivant), mais read_only est également pris en charge.

ant beta:sessions create <<YAML
agent: $agent_id
environment_id: $environment_id
resources:
  - type: memory_store
    memory_store_id: $store_id
    access: read_write
    instructions: User preferences and project context. Check before starting any task.
YAML

Un maximum de 8 magasins de mémoire est pris en charge par session. Attachez plusieurs magasins lorsque différentes parties de la mémoire ont des propriétaires ou des règles d'accès différents. Raisons courantes :

• Matériel de référence partagé : un magasin en lecture seule attaché à de nombreuses sessions (normes, conventions, connaissances du domaine), maintenu séparé du magasin en lecture-écriture propre à chaque session.
• Correspondance avec la structure de votre produit : un magasin par utilisateur final, par équipe ou par projet, tout en partageant une seule configuration d'agent.
• Cycles de vie différents : un magasin qui survit à toute session individuelle, ou un magasin que vous souhaitez archiver selon son propre calendrier.



Comment l'agent accède à la mémoire

Chaque magasin attaché est monté à l'intérieur du bac à sable de la session en tant que répertoire sous /mnt/memory/. Le nom du répertoire est le nom d'affichage du magasin converti en un « slug » compatible avec le système de fichiers (mis en minuscules ; les séquences de caractères non alphanumériques deviennent un seul tiret), de sorte qu'un magasin nommé « Demo Memory » est monté à /mnt/memory/demo-memory/. Le chemin exact est renvoyé dans le champ mount_path de la ressource de magasin de mémoire de la session ; lisez-le à partir de là plutôt que de le construire vous-même. L'agent lit et écrit dans le magasin avec l'ensemble d'outils de l'agent standard. Les écritures sous le chemin de montage sont persistées dans le magasin et restent synchronisées entre les sessions qui le partagent ; les écritures vers tout autre chemin sous /mnt/memory/ atterrissent dans un espace temporaire local au conteneur et sont perdues à la fin de la session. Une brève description de chaque montage (nom d'affichage, chemin de montage, mode d'accès, description du magasin et éventuelles instructions) est automatiquement ajoutée à l'invite système.

access est appliqué au niveau du système de fichiers : un montage read_only rejette les écritures, tandis que les écritures sur un montage read_write produisent des versions de mémoire attribuées à la session.

Les lectures et écritures de l'agent apparaissent dans le flux d'événements comme des événements agent.tool_use et agent.tool_result ordinaires pour l'outil qui a touché le montage.



Afficher et modifier les mémoires

Les magasins de mémoire peuvent être gérés directement via l'API. Utilisez cette fonctionnalité pour créer des flux de travail de révision, corriger des mémoires erronées ou préremplir des magasins avant toute exécution de session.



Lister les mémoires

Listez les mémoires d'un magasin, éventuellement filtrées par path_prefix pour parcourir un chemin comme un répertoire :

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/" --order-by path --depth 2

Consultez la référence Lister les mémoires pour les paramètres complets et le schéma de réponse.



Lire une mémoire

La récupération d'une mémoire individuelle renvoie le contenu complet.

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Consultez la référence Récupérer une mémoire pour les paramètres complets et le schéma de réponse.



Créer une mémoire

memories.create crée une mémoire à un path donné. La création n'écrase pas ; pour modifier une mémoire existante, utilisez memories.update.

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

Consultez la référence Créer une mémoire pour les paramètres complets et le schéma de réponse.



Mettre à jour une mémoire

memories.update modifie une mémoire existante par son ID. Vous pouvez changer content, path (un renommage), ou les deux. L'exemple renomme une mémoire vers un chemin d'archive :

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

Consultez la référence Mettre à jour une mémoire pour les paramètres complets et le schéma de réponse.



Modifications de contenu sécurisées (concurrence optimiste)

Pour éviter d'écraser une écriture concurrente, transmettez une précondition content_sha256. La mise à jour ne s'applique que si le hachage du contenu stocké correspond toujours à celui que vous avez lu ; en cas de non-correspondance, relisez la mémoire et réessayez avec l'état actualisé.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null



Supprimer une mémoire

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

Consultez la référence Supprimer une mémoire pour les paramètres complets et le schéma de réponse.



Auditer les modifications de mémoire

Chaque mutation d'une mémoire crée une version de mémoire immuable (memver_...). Utilisez les points de terminaison de version pour auditer qui a modifié quoi et quand, pour inspecter ou restaurer un instantané antérieur, et pour effacer du contenu sensible de l'historique avec la rédaction.

Les versions appartiennent au magasin (et non à la mémoire individuelle) et survivent même après la suppression de la mémoire elle-même, de sorte que la piste d'audit reste complète. Les versions sont conservées pendant 30 jours ; toutefois, les versions récentes sont toujours conservées quel que soit leur âge, de sorte que les mémoires qui changent rarement peuvent conserver un historique au-delà de 30 jours. L'appel memories.retrieve en direct renvoie toujours la dernière version ; les points de terminaison de version vous donnent l'historique conservé.

Il n'existe pas de point de terminaison de restauration dédié ; pour revenir en arrière, récupérez la version souhaitée et réécrivez son content avec memories.update (ou memories.create si la mémoire parente a été supprimée, car les versions survivent à leur parent).

Les versions de mémoire passées peuvent être supprimées après 30 jours. Pour conserver l'historique de mémoire plus longtemps, exportez les versions via l'API.



Lister les versions

Listez l'historique des versions d'un magasin, les plus récentes en premier. L'exemple filtre sur l'historique d'une seule mémoire :

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

Consultez la référence Lister les versions de mémoire pour les paramètres complets et le schéma de réponse.



Récupérer une version

La récupération d'une version individuelle renvoie les mêmes champs que la réponse de liste, plus le corps content complet.

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consultez la référence Récupérer une version de mémoire pour les paramètres complets et le schéma de réponse.



Rédiger une version

La rédaction efface le contenu d'une version historique tout en préservant la piste d'audit (qui a fait quoi, quand). Utilisez-la pour les flux de travail de conformité tels que la suppression de secrets divulgués, de données personnelles (PII) ou les demandes de suppression d'utilisateur.

Une version qui est la tête actuelle d'une mémoire active ne peut pas être rédigée. Écrivez d'abord une nouvelle version (ou supprimez la mémoire), puis rédigez l'ancienne.

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consultez la référence Rédiger une version de mémoire pour les paramètres complets et le schéma de réponse.



Gérer les magasins de mémoire

En plus de create, les magasins de mémoire prennent en charge retrieve, update, list, archive et delete.



Lister les magasins

Listez les magasins de l'espace de travail. Les magasins archivés sont exclus par défaut ; transmettez include_archived: true pour les inclure.

ant beta:memory-stores list --include-archived

Consultez la référence Lister les magasins de mémoire pour les paramètres complets et le schéma de réponse.



Archiver un magasin

L'archivage rend un magasin en lecture seule et empêche son attachement à de nouvelles sessions. L'archivage est à sens unique ; il n'existe pas de désarchivage.

ant beta:memory-stores archive --memory-store-id "$store_id"

Consultez la référence Archiver un magasin de mémoire pour les paramètres complets et le schéma de réponse.

Pour supprimer définitivement un magasin ainsi que toutes ses mémoires et versions, utilisez memory_stores.delete.



Bonnes pratiques pour la gestion de la mémoire

Lorsqu'un magasin atteint sa limite de 2 000 mémoires, les écritures vers de nouvelles mémoires échouent : à la fois les appels directs memories.create et les écritures de fichiers de l'agent vers des chemins non mappés. Les mémoires existantes restent lisibles et modifiables. Les pratiques suivantes vous aident à rester bien en dessous de la limite et à récupérer en douceur si vous l'atteignez.

• Utilisez des magasins ciblés. Plutôt qu'un seul grand magasin à usage général, utilisez des magasins plus petits et spécialisés — un par utilisateur, un pour les connaissances de domaine partagées et un pour le contexte spécifique au projet. Chaque magasin a sa propre limite de 2 000 mémoires, donc garder les magasins bien délimités réduit le risque qu'un seul d'entre eux se remplisse.

• Condensez ou élaguez avant que le magasin ne se remplisse. Supprimez les mémoires obsolètes ou redondantes avec memories.delete. Vous pouvez également exécuter une session de rêve, qui consolide le contenu fragmenté dans un nouveau magasin de sortie distinct plutôt que de modifier l'original. Basculez vos sessions vers ce magasin de sortie, puis archivez ou supprimez l'original.

• Attachez un nouveau magasin lorsque cela a du sens. Si un magasin a dépassé son périmètre utile, attachez-en un nouveau pour le nouveau contenu et attachez l'original avec un accès read_only. L'agent peut lire dans les deux tout en n'écrivant que dans le nouveau.

• Limitez l'accès en écriture lorsque c'est approprié. Les sessions qui ne font que lire du matériel de référence partagé n'ont pas besoin de read_write. Limiter l'accès en écriture aux sessions qui ajoutent réellement de nouvelles mémoires facilite le suivi de l'origine de la croissance.