Outil de mémoire

L'outil de mémoire permet à Claude de stocker et de récupérer des informations entre les conversations via un répertoire de fichiers de mémoire. Claude peut créer, lire, mettre à jour et supprimer des fichiers qui persistent entre les sessions, ce qui lui permet d'accumuler des connaissances au fil du temps sans tout conserver dans la fenêtre de contexte.

Il s'agit de la primitive clé pour la récupération de contexte juste-à-temps : plutôt que de charger toutes les informations pertinentes dès le départ, les agents stockent ce qu'ils apprennent en mémoire et le récupèrent à la demande. Cela permet de garder le contexte actif concentré sur ce qui est actuellement pertinent, un aspect essentiel pour les flux de travail de longue durée où tout charger en une seule fois saturerait la fenêtre de contexte. Consultez Effective context engineering pour une vue d'ensemble de ce modèle.

L'outil de mémoire fonctionne côté client : 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 exécutions d'agent
• Apprendre des interactions, décisions et retours passés
• Construire des bases de connaissances au fil du temps
• Permettre l'apprentissage inter-conversations, où Claude s'améliore sur des flux de travail récurrents



Fonctionnement

Lorsqu'il est activé, Claude vérifie automatiquement son répertoire de mémoire avant de commencer les tâches. Claude peut créer, lire, mettre à jour et supprimer des fichiers dans le répertoire /memories pour stocker ce qu'il apprend en travaillant, puis référencer ces souvenirs dans de futures conversations afin de traiter des tâches similaires plus efficacement ou de reprendre là où il s'était arrêté.

Comme il s'agit d'un outil côté client, Claude effectue des appels d'outil pour réaliser les opérations de mémoire, et votre application exécute ces opérations localement. Cela vous donne un contrôle total sur l'emplacement et le mode de stockage de la mémoire. Pour des raisons de sécurité, vous devez restreindre toutes les opérations de mémoire au répertoire /memories.



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

Lorsque vous demandez à Claude de vous aider sur une tâche, Claude vérifie d'abord automatiquement son répertoire de mémoire. Voici à quoi ressemble une interaction typique :

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..."

Pour la prise en charge des modèles, consultez la Référence des outils.



Premiers pas

Pour utiliser l'outil de mémoire :

1. Ajoutez l'outil de mémoire à votre requête
2. Implémentez des gestionnaires côté client pour les opérations de mémoire



Utilisation de base

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPlease help me debug this.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)



Commandes de l'outil

Votre implémentation côté client doit gérer ces commandes de l'outil de mémoire. Bien que ces spécifications décrivent les comportements recommandés que Claude connaît le mieux, vous pouvez modifier votre implémentation et renvoyer des chaînes de caractères selon les besoins de votre cas d'utilisation.



view

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

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // Optional: view specific lines
}



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}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

• Liste les fichiers jusqu'à 2 niveaux de profondeur
• Affiche des tailles lisibles par l'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

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 : indexée à 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



Gestion des erreurs

• Le fichier/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"



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"
}



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"
}



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/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.



rename

Renomme ou déplace un fichier/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 (ne pas écraser) : "Error: The destination {new_path} already exists"



Gestion des répertoires

Renomme le répertoire.



Conseils de prompting

Cette instruction est automatiquement incluse dans l'invite système lorsque l'outil de mémoire est activé :

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.

Si vous observez que Claude crée des fichiers de mémoire désordonnés, vous pouvez inclure cette instruction :

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 guider 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é

Voici des préoccupations de sécurité importantes lors de l'implémentation de votre stockage de mémoire :



Informations sensibles

Claude refusera généralement d'écrire des informations sensibles dans les fichiers de mémoire. Cependant, vous pouvez souhaiter implémenter une validation plus stricte qui supprime les informations potentiellement sensibles.



Taille du stockage de fichiers

Envisagez de suivre la taille des fichiers de mémoire et d'empêcher les fichiers de devenir trop volumineux. Envisagez d'ajouter un nombre maximal de caractères que la commande de lecture de mémoire peut renvoyer, et laissez Claude paginer le contenu.



Expiration de la mémoire

Envisagez de supprimer 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 vers leur forme canonique et vérifiez qu'ils restent dans le répertoire de mémoire
• Rejetez les chemins contenant des séquences comme ../, ..\\, 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é de chemin intégrés à votre langage (par exemple, pathlib.Path.resolve() et relative_to() de 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. Consultez les sections des commandes d'outil individuelles ci-dessus pour les messages d'erreur et comportements détaillés. Les erreurs courantes incluent : fichier introuvable, erreurs de permission, chemins invalides et correspondances de texte en double.



Intégration avec l'édition de contexte

L'outil de mémoire se combine avec 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 combiné avec la compaction, qui fournit un résumé côté serveur du contexte de conversation plus ancien. Alors que 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 lorsqu'elle approche de la limite de la fenêtre de contexte.

Pour les flux de travail agentiques de longue durée, envisagez d'utiliser les deux : la compaction maintient le contexte actif gérable sans comptabilité côté client, et la mémoire conserve les informations importantes au-delà des limites de compaction afin que rien de critique ne soit perdu dans le résumé.



Modèle de développement logiciel multi-sessions

Pour les projets logiciels de longue durée qui s'étendent sur plusieurs sessions d'agent, les fichiers de mémoire doivent être initialisés délibérément, et non simplement écrits de manière ad hoc au fur et à mesure de l'avancement du travail. Le modèle ci-dessous transforme la mémoire en un mécanisme de récupération structuré, afin que chaque nouvelle session puisse reprendre exactement là où la précédente s'était arrêtée.



Fonctionnement

1. Session d'initialisation : la première session configure les artefacts de mémoire avant que tout travail substantiel ne commence. Cela inclut un journal de progression (suivant ce qui a été fait et ce qui vient ensuite), une liste de contrôle des fonctionnalités (définissant 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 la lecture de ces artefacts de mémoire. Cela permet de récupérer l'état complet du projet en quelques secondes, sans avoir à 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 confirme qu'elle fonctionne, et non simplement après que le code a été écrit. Cela maintient la fiabilité du journal de progression et empêche la dérive du périmètre de s'accumuler d'une session à l'autre.



Étapes suivantes