Utiliser la mémoire des agents

Utiliser la mémoire

Agent Memory est une fonctionnalité en Research Preview. Demandez l'accès pour l'essayer.

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 conserver ses apprentissages entre les sessions : préférences utilisateur, conventions de projet, erreurs antérieures et contexte de domaine.

Toutes les demandes de l'API Managed Agents nécessitent l'en-tête bêta managed-agents-2026-04-01. Un en-tête bêta supplémentaire est nécessaire pour les fonctionnalités en research preview. Le SDK définit automatiquement ces en-têtes bêta.

Aperçu

Un magasin de mémoire est une collection de documents texte optimisée pour Claude et délimitée par l'espace de travail. 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, ce qui permet d'ajuster, d'importer et d'exporter les mémoires.

Chaque modification d'une mémoire crée une version de mémoire immuable pour prendre en charge 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 = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(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 :

Les mémoires individuelles dans le magasin sont limitées à 100 Ko (~25 K tokens). Structurez la mémoire comme de nombreux petits fichiers ciblés, pas quelques gros.

Attacher un magasin de mémoire à une session

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

Incluez éventuellement 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, c'est read_write, mais read_only est également pris en charge (montré explicitement dans l'exemple ci-dessous).

Un maximum de 8 magasins de mémoire sont 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 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 des 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.

Outil	Description
`memory_list`	Lister les mémoires dans un magasin, éventuellement filtrées par préfixe de chemin.
`memory_search`	Recherche en texte intégral dans le contenu de la mémoire.
`memory_read`	Lire le contenu d'une mémoire.
`memory_write`	Créer ou remplacer une mémoire à un chemin.
`memory_edit`	Modifier une mémoire existante.
`memory_delete`	Supprimer une mémoire.

Afficher et modifier les mémoires

Les magasins de mémoire peuvent être gérés directement via l'API. Utilisez ceci pour créer 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 délimitées par 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.

Créer une mémoire

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

Écritures sécurisées (concurrence optimiste)

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

Pour modifier en toute sécurité une mémoire existante (lire, modifier, réécrire sans écraser une modification concurrente), utilisez plutôt memories.update avec une précondition content_sha256. Voir Mettre à jour une mémoire ci-dessous.

Mettre à jour une mémoire

memories.update() modifie une mémoire existante par son ID mem_.... 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 une mémoire vers un chemin d'archive :

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

Pour modifier le contenu d'une mémoire sans écraser une écriture concurrente, passez une précondition content_sha256. La mise à jour ne s'applique que 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 la mémoire et réessayez par rapport à l'état frais.

Supprimer une mémoire

Passez éventuellement expected_content_sha256 pour une suppression conditionnelle.

Auditer les modifications de mémoire

Chaque mutation d'une mémoire crée une version de mémoire immuable (memver_...). Les versions s'accumulent pendant la durée de vie de la mémoire parente 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 vers 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

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 conformité tels que la suppression de secrets divulgués, d'informations personnelles identifiables ou les demandes de suppression d'utilisateurs. La rédaction 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.

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

mem = client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)