Outil de mémoire

L'outil de mémoire permet à Claude de stocker et de récupérer des informations d'une conversation à l'autre dans un répertoire de fichiers de mémoire. Claude peut créer, lire, mettre à jour et supprimer des fichiers qui persistent entre les sessions, accumulant ainsi des connaissances au fil du temps sans tout conserver dans la « context window » (fenêtre de contexte).

La mémoire prend en charge la récupération de contexte juste-à-temps. Plutôt que de charger toutes les informations pertinentes dès le départ, un agent consigne ce qu'il apprend dans des fichiers de mémoire et les relit à la demande. Cela permet de garder le contexte actif concentré sur la tâche en cours, ce qui est important pour les sessions de longue durée qui, autrement, satureraient la fenêtre de contexte. Consultez Effective context engineering pour découvrir le modèle plus général.

L'outil de mémoire fonctionne côté client : Claude demande des opérations de fichiers, et votre application les exécute. Vous contrôlez où et comment les données sont stockées via votre propre infrastructure.

Cas d'utilisation

• Maintenir le contexte d'un projet sur plusieurs sessions d'agent
• Appliquer les enseignements tirés des interactions, décisions et retours passés à de nouvelles tâches
• Constituer une base de connaissances au fil du temps

Fonctionnement

Lorsque l'outil de mémoire est activé, Claude vérifie automatiquement son répertoire de mémoire avant de commencer une tâche. Au fur et à mesure de son travail, Claude stocke ce qu'il apprend dans des fichiers sous /memories et les relit lors de conversations ultérieures pour poursuivre un travail antérieur.

Comme l'outil de mémoire fonctionne côté client, Claude ne fait que demander des opérations de mémoire. Votre application exécute chaque requête sur un stockage que vous contrôlez et renvoie le résultat dans un bloc tool_result (voir Gérer les appels d'outils). Le chemin /memories est un préfixe que votre gestionnaire fait correspondre à un stockage réel, tel qu'un répertoire par utilisateur ou des clés dans une base de données. La mémoire réside entièrement dans votre application. Une conversation ultérieure reprend à partir de la même mémoire lorsqu'elle envoie la même entrée tools et que votre gestionnaire sert le même magasin de données. Pour des raisons de sécurité, limitez toutes les opérations de mémoire au répertoire /memories (voir Protection contre la traversée de chemin).

Exemple : fonctionnement des appels de l'outil de mémoire

Une interaction typique ressemble à ceci :

1. Requête de l'utilisateur :

"Help me respond to this customer service ticket."

2. Claude vérifie le répertoire de mémoire :

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Claude appelle l'outil de mémoire :

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. Votre application renvoie le contenu du répertoire :

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}

4. Claude lit les fichiers pertinents :

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. Votre application renvoie le contenu du fichier :

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude utilise la mémoire pour vous aider :

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

L'outil de mémoire est disponible sur tous les modèles Claude 4 et ultérieurs. Pour la liste complète des outils fournis par Anthropic, consultez la Référence des outils.

Premiers pas

L'utilisation de l'outil de mémoire se fait en deux étapes :

1. Ajoutez l'outil de mémoire à votre requête. L'entrée tools {"type": "memory_20250818", "name": "memory"} constitue l'intégralité de la configuration : le name doit être memory, et vous ne définissez pas de schéma d'entrée pour un outil fourni par Anthropic.
2. Implémentez un gestionnaire côté client pour chaque commande de mémoire. Votre gestionnaire doit rejeter les chemins situés en dehors de /memories ; lisez donc Protection contre la traversée de chemin avant de l'écrire.

Utilisation de base

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Help me respond to this customer service ticket.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

Implémenter le gestionnaire de mémoire

La réponse de Claude à une requête comme la précédente se termine par un bloc tool_use qui demande une opération de mémoire, par exemple view /memories. Votre application exécute l'opération et renvoie le résultat dans un bloc tool_result. Elle renvoie ensuite la conversation pour que Claude puisse continuer. Il s'agit de la « tool-use loop » (boucle d'utilisation d'outils) standard, décrite dans Gérer les appels d'outils.

Quatre SDK fournissent des utilitaires pour l'outil de mémoire, qui gèrent l'interface de l'outil et la boucle. Pour adosser la mémoire à votre propre stockage (fichiers sur disque, base de données, stockage cloud ou fichiers chiffrés), procédez selon votre SDK :

• Python et C# : créez une sous-classe de BetaAbstractMemoryTool.
• TypeScript : utilisez betaMemoryTool.
• Java : implémentez BetaMemoryToolHandler.

Python et TypeScript fournissent également une implémentation prête à l'emploi basée sur le système de fichiers local, BetaLocalFilesystemMemoryTool. Les utilitaires et les exécuteurs d'outils se trouvent dans l'espace de noms bêta de chaque SDK, même si l'outil de mémoire lui-même ne nécessite pas d'en-tête bêta. Les SDK Go et Ruby ne disposent d'aucun utilitaire de mémoire : ces exemples exécutent donc eux-mêmes la boucle d'utilisation d'outils. PHP, lui, encapsule la closure de votre gestionnaire dans son BetaRunnableTool générique. Ces trois exemples utilisent un stockage en mémoire, que vous remplacez par votre propre stockage.

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Les stockages en mémoire des exemples Go, PHP et Ruby rendent ces exemples autonomes. Chacun aiguille le traitement selon le champ command de l'input du bloc tool_use et renvoie les chaînes décrites dans Commandes de l'outil. Un gestionnaire de production nécessite en outre la validation des chemins, que ces stockages de démonstration omettent. Pour les exemples complets fournis par les SDK, consultez :

• Python : examples/memory/basic.py
• TypeScript : examples/tools-helpers-memory.ts
• C# : MemoryToolExample
• Java : BetaMemoryToolExample.java

Commandes de l'outil

Votre implémentation côté client doit gérer les commandes suivantes. Ces spécifications décrivent les comportements et les chaînes de retour recommandés : Claude lit le texte contenu dans votre résultat d'outil, quel qu'il soit ; vous pouvez donc renvoyer des chaînes différentes si votre application en a besoin.

view

Affiche le contenu d'un répertoire ou d'un fichier avec des plages de lignes facultatives :

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_range est facultatif et s'applique aux affichages de fichiers texte : [start_line, end_line] renvoie ces lignes, et [start_line, -1] renvoie tout depuis start_line jusqu'à la fin du fichier.

Valeurs de retour

Pour les répertoires : renvoyez une liste qui affiche les fichiers et répertoires avec leurs tailles :

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}

• Liste les fichiers jusqu'à 2 niveaux de profondeur
• Affiche des tailles lisibles par un humain (par exemple, 5.5K, 1.2M)
• Exclut les éléments cachés (fichiers commençant par .) et node_modules
• Utilise un caractère de tabulation entre la taille et le chemin

Le premier view de /memories sur un magasin vide n'est pas une erreur. Les outils de mémoire pour système de fichiers local des SDK (BetaLocalFilesystemMemoryTool) créent la racine de la mémoire avant le premier appel de Claude et renvoient l'en-tête de la liste suivi d'une seule ligne taille-et-chemin pour le répertoire vide lui-même.

Pour les fichiers : renvoyez le contenu du fichier avec un en-tête et des numéros de ligne :

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

Formatage des numéros de ligne :

• Largeur : 6 caractères, alignés à droite avec remplissage par des espaces
• Séparateur : caractère de tabulation entre le numéro de ligne et le contenu
• Indexation : à partir de 1 (la première ligne est la ligne 1)
• Limite de lignes : les fichiers de plus de 999 999 lignes doivent renvoyer une erreur : "File {path} exceeds maximum line limit of 999,999 lines."

Exemple de sortie :

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

La description de l'outil de Claude indique également que view affiche les fichiers image (.jpg, .jpeg et .png) et tronque l'affichage texte des fichiers de plus de 16 000 caractères. Attendez-vous à des appels view sur des chemins d'images et à des affichages par plage ultérieurs pour les fichiers longs.

Gestion des erreurs

• Le fichier ou le répertoire n'existe pas : "The path {path} does not exist. Please provide a valid path."

create

Crée un nouveau fichier :

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

Valeurs de retour

• Succès : "File created successfully at: {path}"

Gestion des erreurs

• Le fichier existe déjà : "Error: File {path} already exists"

La description de l'outil de Claude indique que create « crée ou écrase » un fichier ; attendez-vous donc à des appels create sur des chemins qui existent déjà. Renvoyer l'erreur constitue le comportement de référence, et écraser le fichier à la place est un choix d'implémentation valide.

str_replace

Remplace du texte dans un fichier :

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

new_str est facultatif pour str_replace : lorsqu'il est omis, old_str est supprimé sans remplacement.

Valeurs de retour

• Succès : "The memory file has been edited." suivi d'un extrait de code du fichier modifié avec les numéros de ligne

Gestion des erreurs

• Le fichier n'existe pas : "Error: The path {path} does not exist. Please provide a valid path."
• Texte introuvable : "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• Texte en double : lorsque old_str apparaît plusieurs fois, renvoyez : "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"

Gestion des répertoires

Si le chemin est un répertoire, renvoyez une erreur « le fichier n'existe pas ».

insert

Insère du texte à une ligne spécifique :

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

insert_text est inséré après la ligne insert_line, et 0 insère au début du fichier.

Valeurs de retour

• Succès : "The file {path} has been edited."

Gestion des erreurs

• Le fichier n'existe pas : "Error: The path {path} does not exist"
• Numéro de ligne invalide : "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"

Gestion des répertoires

Si le chemin est un répertoire, renvoyez une erreur « le fichier n'existe pas ».

delete

Supprime un fichier ou un répertoire :

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

Valeurs de retour

• Succès : "Successfully deleted {path}"

Gestion des erreurs

• Le fichier ou le répertoire n'existe pas : "Error: The path {path} does not exist"

Gestion des répertoires

Supprime le répertoire et tout son contenu de manière récursive. La description de l'outil indique à Claude qu'il ne peut pas supprimer le répertoire /memories lui-même ; rejetez donc un delete dont le chemin est la racine de la mémoire.

rename

Renomme ou déplace un fichier ou un répertoire :

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

Valeurs de retour

• Succès : "Successfully renamed {old_path} to {new_path}"

Gestion des erreurs

• La source n'existe pas : "Error: The path {old_path} does not exist"
• La destination existe déjà : renvoyez une erreur (n'écrasez pas) : "Error: The destination {new_path} already exists"

Gestion des répertoires

Renomme le répertoire. La description de l'outil indique à Claude qu'il ne peut pas renommer le répertoire /memories lui-même ; rejetez donc un rename dont le old_path est la racine de la mémoire.

Conseils de prompting

Lorsque l'outil de mémoire est présent dans les tools de votre requête, l'API ajoute automatiquement cette instruction à l'invite système. Vous n'avez pas besoin de l'envoyer vous-même :

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

La description de l'outil de Claude lui indique déjà de garder le répertoire de mémoire organisé ; vous n'avez donc pas besoin de répéter cette instruction. Si Claude crée malgré tout des fichiers de mémoire désordonnés, vous pouvez la renforcer dans votre prompt :

Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.

Vous pouvez également orienter ce que Claude écrit en mémoire. Par exemple : « Only write down information relevant to <topic> in your memory system. »

Considérations de sécurité

Votre application exécute chaque opération de fichier demandée par Claude ; ces mesures de protection relèvent donc de votre responsabilité :

Informations sensibles

Claude refuse généralement d'écrire des informations sensibles dans les fichiers de mémoire. Pour des garanties plus solides, ajoutez une validation qui supprime les données sensibles avant que votre gestionnaire n'écrive le fichier.

Taille du stockage des fichiers

Surveillez la taille des fichiers de mémoire et plafonnez la taille maximale qu'un fichier peut atteindre. Envisagez de plafonner le nombre de caractères renvoyés par la commande view, et laissez Claude parcourir le reste avec view_range.

Expiration de la mémoire

Supprimez périodiquement les fichiers de mémoire qui n'ont pas été consultés depuis longtemps.

Protection contre la traversée de chemin

Envisagez ces mesures de protection :

• Validez que tous les chemins commencent par /memories
• Résolvez les chemins sous leur forme canonique et vérifiez qu'ils restent dans le répertoire de mémoire
• Rejetez les chemins contenant des séquences telles que ../, ..\\ ou d'autres motifs de traversée
• Surveillez les séquences de traversée encodées en URL (%2e%2e%2f)
• Utilisez les utilitaires de sécurité des chemins intégrés à votre langage (par exemple, pathlib.Path.resolve() et relative_to() en Python)

Gestion des erreurs

L'outil de mémoire utilise des modèles de gestion des erreurs similaires à ceux de l'outil d'édition de texte. Les messages d'erreur de chaque commande sont répertoriés dans la section Commandes de l'outil. Pour renvoyer une erreur à Claude, définissez is_error sur true dans le résultat de l'outil et placez le message dans content :

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}

Intégration avec l'édition de contexte

L'outil de mémoire s'associe à l'édition de contexte pour gérer les conversations de longue durée. Pour plus de détails, consultez Édition de contexte.

Utilisation avec la compaction

L'outil de mémoire peut également être associé à la compaction, qui résume côté serveur le contexte plus ancien de la conversation. L'édition de contexte efface des résultats d'outils spécifiques côté client. La compaction résume automatiquement l'ensemble de la conversation côté serveur lorsque celle-ci approche de la limite de la fenêtre de contexte.

Pour les agents de longue durée, envisagez d'utiliser les deux : la compaction maintient un contexte actif réduit sans tenue de registre côté client, et la mémoire préserve les informations qui doivent survivre au résumé.

Modèle de développement logiciel multisession

Pour les projets logiciels qui s'étendent sur plusieurs sessions d'agent, configurez les fichiers de mémoire de manière délibérée plutôt que de les écrire au fil de l'eau à mesure que le travail avance. Le modèle suivant transforme la mémoire en mécanisme de reprise : chaque nouvelle session reprend à partir de l'état enregistré par la précédente.

Fonctionnement du modèle

1. Session d'initialisation : la première session configure les fichiers de mémoire avant le début de tout travail substantiel. Cela comprend un journal de progression (qui suit ce qui a été fait et ce qui vient ensuite), une liste de contrôle des fonctionnalités (qui définit le périmètre du travail) et une référence à tout script de démarrage ou d'initialisation dont le projet a besoin.

2. Sessions suivantes : chaque nouvelle session commence par lire ces fichiers de mémoire. Cela restaure l'état du projet sans réexplorer la base de code ni retracer les décisions antérieures.

3. Mise à jour de fin de session : avant qu'une session ne se termine, elle met à jour le journal de progression avec ce qui a été accompli et ce qui reste à faire. Cela garantit que la session suivante dispose d'un point de départ précis.

Principe clé

Travaillez sur une seule fonctionnalité à la fois. Ne marquez une fonctionnalité comme terminée qu'après qu'une vérification de bout en bout a confirmé qu'elle fonctionne, et non lorsque le code est écrit. Cela permet de garder le journal de progression exact d'une session à l'autre.

Étapes suivantes