Utiliser la mémoire des agents

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

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 dans la « sandbox » (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. Le jeu d'outils de l'agent est requis pour ces interactions ; veillez à l'activer lors de la création de l'agent. Sur les sandboxes auto-hébergées, ce répertoire n'est pas un montage en direct. À la place, le worker d'environnement du SDK télécharge chaque magasin attaché dans votre sandbox avant l'exécution des outils de l'agent et maintient cette copie synchronisée avec le magasin.

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

Chaque modification d'une mémoire crée une version de mémoire immuable, vous offrant une piste d'audit et une restauration à 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 pour lui indiquer 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 lorsque vous attachez le magasin à une session.

L'alimenter avec du contenu (facultatif)

Préchargez un magasin avec des documents 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 la création de la session. Contrairement aux ressources de fichiers, les magasins de mémoire ne peuvent être attachés qu'au moment de la création de la session ; l'ajout ou le retrait d'un magasin dans une session en cours n'est pas pris en charge. Vous attachez les magasins de mémoire de la même manière pour les sessions sur le cloud et sur les environnements auto-hébergés ; les environnements auto-hébergés n'acceptent que les ressources memory_store.

Vous pouvez éventuellement inclure des instructions pour fournir des consignes propres à 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 :

• Documents de référence partagés : un magasin en lecture seule attaché à de nombreuses sessions (normes, conventions, connaissances métier), 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 configuration d'agent unique.
• 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é dans la sandbox de la session en tant que répertoire sous /mnt/memory/. Le nom du répertoire est le nom d'affichage du magasin, assaini en un slug compatible avec le système de fichiers (en minuscules ; les suites 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 le jeu 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/ échouent, car la sandbox monte ce répertoire parent en lecture seule. Une courte 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 sous forme d'événements agent.tool_use et agent.tool_result ordinaires pour l'outil qui a touché le montage.

Consulter et modifier les mémoires

Les magasins de mémoire peuvent être gérés directement via l'API. Utilisez cette possibilité pour créer des flux de révision, corriger de mauvaises mémoires ou alimenter des magasins avant toute exécution de session.

Lister les mémoires

Listez les mémoires d'un magasin. Les résultats sont renvoyés dans un ordre stable défini par le serveur.

• path_prefix limite la liste à un seul répertoire. Il doit se terminer par / et correspond à des segments de chemin entiers, de sorte que path_prefix=/notes/ renvoie /notes/todo.md mais pas /notes-archive/todo.md.
• depth contrôle la profondeur de la liste sous path_prefix : omettez-le (ou passez 0) pour lister tout le sous-arbre, ou passez 1 pour ne lister que les enfants immédiats. Les autres valeurs renvoient une erreur 400.

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

Consultez la référence Lister les mémoires pour l'ensemble des paramètres 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 l'ensemble des paramètres 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 l'ensemble des paramètres et le schéma de réponse.

Mettre à jour une mémoire

memories.update modifie une mémoire existante par son ID. Vous pouvez modifier 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 l'ensemble des paramètres et le schéma de réponse.

Modifications de contenu sûres (concurrence optimiste)

Pour éviter d'écraser une écriture concurrente, passez 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 sur 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 l'ensemble des paramètres 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 grâce au caviardage (redact).

Les versions appartiennent au magasin (et non à la mémoire individuelle) et ne sont pas supprimées lorsque la mémoire elle-même est supprimée, de sorte que la piste d'audit couvre également les mémoires supprimées, sous réserve de la rétention décrite ci-dessous. Les versions sont conservées pendant 30 jours après leur écriture ; toutefois, les versions récentes d'une mémoire active 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, à condition que la version souhaitée soit encore conservée).

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

Lister les versions

Listez l'historique des versions d'un magasin, de la plus récente à la plus ancienne. 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)
# `list --format json` émet un objet JSON par élément.
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

Consultez la référence Lister les versions de mémoire pour l'ensemble des paramètres 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 l'ensemble des paramètres et le schéma de réponse.

Caviarder une version

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

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

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

Consultez la référence Caviarder une version de mémoire pour l'ensemble des paramètres 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 ; passez 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 l'ensemble des paramètres et le schéma de réponse.

Archiver un magasin

L'archivage rend un magasin en lecture seule et empêche qu'il soit attaché à de nouvelles sessions. L'archivage est irréversible ; 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 l'ensemble des paramètres 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 de gestion de la mémoire

Lorsqu'un magasin atteint sa limite de 10 000 mémoires, les écritures de nouvelles mémoires échouent : aussi bien les appels directs à memories.create que 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 proprement si vous l'atteignez.

• Utilisez des magasins ciblés. Plutôt qu'un seul grand magasin généraliste, utilisez des magasins plus petits conçus pour un usage précis : un par utilisateur, un pour les connaissances métier partagées et un pour le contexte propre au projet. Chaque magasin a sa propre limite de 10 000 mémoires, donc garder des magasins bien délimités réduit le risque que l'un d'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 lancer 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 l'accès read_only. L'agent peut lire 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 des documents de référence partagés n'ont pas besoin de read_write. Restreindre l'accès en écriture aux sessions qui ajoutent réellement de nouvelles mémoires facilite le suivi de l'origine de la croissance.