Utiliser la mémoire

Les sessions de l'API Managed Agents sont éphémères par défaut. Lorsqu'une session se termine, tout ce que l'agent a appris disparaît. Les magasins de mémoire permettent à l'agent de transporter ses apprentissages entre les sessions : préférences utilisateur, conventions de projet, erreurs antérieures et contexte de domaine.

Aperçu

Un magasin de mémoire est une collection de documents texte à portée d'espace de travail optimisée pour Claude. Lorsqu'un ou plusieurs magasins de mémoire sont attachés à une session, l'agent vérifie automatiquement les magasins avant de commencer une tâche et écrit les apprentissages durables une fois terminé - aucune invite supplémentaire ou configuration n'est nécessaire de votre côté.

Chaque mémoire dans un magasin peut être accédée et modifiée directement via l'API ou la Console, permettant l'ajustement, l'importation et l'exportation de mémoires.

Chaque modification d'une mémoire crée une memory_version immuable pour soutenir l'audit et l'annulation des modifications de mémoire.

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=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...

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

L'amorcer avec du contenu (optionnel)

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

Attacher la mémoire à une session

Les magasins de mémoire sont attachés dans le tableau resources[] de la session.

Incluez optionnellement une prompt si vous souhaitez fournir des instructions spécifiques à la session à Claude sur la façon d'utiliser ce magasin de mémoire. Elle est fournie à Claude en plus du name et de la description du magasin de mémoire, et est limitée à 4 096 caractères.

Vous pouvez également configurer access. Par défaut, il est read_write, mais read_only est également supporté (montré explicitement dans l'exemple ci-dessous).

Un maximum de 8 magasins de mémoire sont supportés 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 de domaine), séparé des apprentissages en lecture-écriture propres à chaque session.
• Mappage à 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 dépasse une seule session, ou un que vous souhaitez archiver selon votre propre calendrier.

Outils de mémoire

Lorsque les magasins de mémoire sont attachés à une session, l'agent accède automatiquement aux outils de mémoire. Les interactions de l'agent avec les magasins de mémoire sont enregistrées en tant qu'événements agent.tool_use dans le flux d'événements.

Inspecter et corriger la mémoire

Les magasins de mémoire peuvent être gérés directement via l'API. Utilisez ceci pour construire des flux de travail d'examen, corriger les mauvaises mémoires, ou amorcer les magasins avant toute exécution de session.

Lister les mémoires

La liste ne retourne pas le contenu de la mémoire, juste les métadonnées de l'objet. Utilisez path_prefix pour les listes à portée de répertoire (incluez une barre oblique finale : /notes/ correspond à /notes/a.md mais pas à /notes_backup/old.md).

Lire une mémoire

La récupération d'une mémoire individuelle retourne le contenu complet du document.

Écrire un document

Utilisez memories.write pour faire un upsert d'un document par chemin. Si rien n'existe au chemin, il est créé ; si un document existe déjà là, son contenu est remplacé. Pour muter un document existant par mem_... ID (par exemple, pour renommer son chemin ou appliquer en toute sécurité une modification de contenu), utilisez memories.update à la place (voir Mettre à jour ci-dessous).

Créer uniquement si le chemin est libre

Passez precondition={"type": "not_exists"} à memories.write pour en faire une garde de création uniquement. Si un document existe déjà au chemin, l'écriture retourne 409 memory_precondition_failed au lieu de le remplacer. Utilisez ceci lors de l'amorçage d'un magasin et vous voulez éviter de détruire le contenu existant.

Pour modifier en toute sécurité un document existant (lire, modifier, réécrire sans détruire une modification concurrente), utilisez memories.update avec une précondition content_sha256 à la place. Voir Mettre à jour ci-dessous.

Mettre à jour

memories.update() modifie un document existant par son mem_... ID. Vous pouvez modifier content, path (un renommage), ou les deux en un seul appel.

Renommer sur un chemin occupé retourne 409 conflict. L'appelant doit supprimer ou renommer le bloqueur en premier, ou passer precondition={"type": "not_exists"} pour rendre le renommage un non-op si quelque chose existe déjà à la cible.

L'exemple ci-dessous renomme un document à un chemin d'archive :

Modifications de contenu sûres (concurrence optimiste)

Pour modifier le contenu d'un document sans détruire une écriture concurrente, passez une précondition content_sha256. La mise à jour s'applique uniquement si le hash stocké correspond toujours à celui que vous avez lu ; en cas de non-correspondance, elle retourne 409 memory_precondition_failed, auquel cas vous relisez le document et réessayez contre l'état frais.

Supprimer un document

Optionnellement, passez expected_content_sha256 pour une suppression conditionnelle.

Versions de mémoire

Chaque mutation d'une mémoire crée une version de mémoire immuable (memver_...). Les versions s'accumulent pour la durée de vie de la mémoire parent et forment la surface d'audit et de restauration en dessous. L'appel memories.retrieve en direct retourne toujours la tête actuelle ; les points de terminaison de version vous donnent l'historique complet.

Une nouvelle version est écrite à chaque mutation :

• Le premier memories.write à un chemin crée une version avec operation: "created".
• memories.update qui change content, path, ou les deux crée une version avec operation: "modified".
• memories.delete crée une version avec operation: "deleted".

Utilisez les points de terminaison de version pour auditer quel utilisateur ou agent a changé quoi et quand, pour inspecter ou restaurer un snapshot antérieur, et pour nettoyer le contenu sensible de l'historique avec redact.

Lister les versions

Lister les métadonnées de version paginées pour un magasin, les plus récentes en premier. Filtrer par memory_id, operation (created, modified, ou deleted), session_id, api_key_id, ou une plage de temps created_at_gte/created_at_lte. La réponse de liste n'inclut pas le corps content ; récupérez les versions individuelles avec retrieve lorsque vous avez besoin du contenu complet.

Récupérer une version

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

Rédiger une version

Rédiger 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, d'informations personnelles identifiables ou les demandes de suppression d'utilisateurs. Rédiger efface complètement content, content_sha256, content_size_bytes, et path ; tous les autres champs, y compris l'acteur et les horodatages, sont préservés.