Outil de mémoire

L'outil de mémoire permet à Claude de stocker et 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 de construire des connaissances au fil du temps sans garder tout dans la fenêtre de contexte.

C'est la primitive clé pour la récupération de contexte juste-à-temps : plutôt que de charger toutes les informations pertinentes à l'avance, les agents stockent ce qu'ils apprennent en mémoire et le récupèrent à la demande. Cela maintient le contexte actif concentré sur ce qui est actuellement pertinent, ce qui est critique pour les flux de travail de longue durée où charger tout à la fois dépasserait la fenêtre de contexte. Voir Effective context engineering pour le modèle plus large.

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'usage

• Maintenir le contexte du projet entre 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 entre conversations où Claude s'améliore dans les flux de travail récurrents

Comment ça marche

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 mémoires dans les conversations futures pour gérer des tâches similaires plus efficacement ou reprendre là où il s'était arrêté.

Puisque c'est un outil côté client, Claude effectue des appels d'outil pour exécuter les opérations de mémoire, et votre application exécute ces opérations localement. Cela vous donne un contrôle complet sur où et comment la mémoire est stockée. Pour la sécurité, vous devez restreindre toutes les opérations de mémoire au répertoire /memories.

Exemple : Comment fonctionnent les appels d'outil de mémoire

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

1. Demande de l'utilisateur :

"Aide-moi à répondre à ce ticket de service client."

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

"Je vais vous aider à répondre au ticket de service client. Laissez-moi vérifier ma mémoire pour tout contexte antérieur."

Claude appelle l'outil de mémoire :

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

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

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Voici les fichiers et répertoires jusqu'à 2 niveaux de profondeur dans /memories, excluant les éléments cachés et 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 retourne le contenu du fichier :

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "Voici le contenu de /memories/customer_service_guidelines.xml avec les numéros de ligne :\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Toujours adresser les clients par leur prénom\n     4\t- Utiliser un langage empathique\n..."
}

6. Claude utilise la mémoire pour aider :

"Basé sur vos directives de service client, je peux vous aider à rédiger une réponse. Veuillez partager les détails du ticket..."

Pour le support du modèle, voir la Référence des outils.

Commencer

Pour utiliser l'outil de mémoire :

1. Ajouter l'outil de mémoire à votre demande
2. Implémenter des gestionnaires côté client pour les opérations de mémoire

Utilisation basique

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    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 d'outil

Votre implémentation côté client doit gérer ces commandes d'outil de mémoire. Bien que ces spécifications décrivent les comportements recommandés avec lesquels Claude est le plus familier, vous pouvez modifier votre implémentation et retourner des chaînes selon vos besoins.

view

Affiche le contenu du répertoire ou le contenu du fichier avec des plages de lignes optionnelles :

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // Optionnel : afficher des lignes spécifiques
}

Valeurs de retour

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

Voici les fichiers et répertoires jusqu'à 2 niveaux de profondeur dans {path}, excluant les éléments cachés et node_modules :
{size}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

• Liste les fichiers jusqu'à 2 niveaux de profondeur
• Affiche les tailles lisibles par l'homme (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 : Retourner le contenu du fichier avec un en-tête et des numéros de ligne :

Voici le contenu de {path} avec les numéros de ligne :
{line_numbers}{tab}{content}

Formatage des numéros de ligne :

• Largeur : 6 caractères, alignés à droite avec remplissage d'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 avec plus de 999 999 lignes doivent retourner une erreur : "File {path} exceeds maximum line limit of 999,999 lines."

Exemple de sortie :

Voici le contenu de /memories/notes.txt avec les numéros de ligne :
     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éer 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

Remplacer 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 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 non trouvé : "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• Texte dupliqué : Quand old_str apparaît plusieurs fois, retourner : "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, retourner une erreur "fichier n'existe pas".

insert

Insérer 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, retourner une erreur "fichier n'existe pas".

delete

Supprimer 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

Renommer ou déplacer 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à : Retourner une erreur (ne pas écraser) : "Error: The destination {new_path} already exists"

Gestion des répertoires

Renomme le répertoire.

Conseils de prompt

Cette instruction est automatiquement incluse dans le prompt système quand 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 Claude créant des fichiers de mémoire désorganisé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 les préoccupations de sécurité importantes lors de l'implémentation de votre magasin de mémoire :

Informations sensibles

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

Taille de stockage des fichiers

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

Expiration de la mémoire

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

Protection contre la traversée de répertoires

Envisagez ces protections :

• Valider que tous les chemins commencent par /memories
• Résoudre les chemins à leur forme canonique et vérifier qu'ils restent dans le répertoire de mémoire
• Rejeter les chemins contenant des séquences comme ../, ..\\, ou d'autres modèles de traversée
• Surveiller les séquences de traversée codées en URL (%2e%2e%2f)
• Utiliser les utilitaires de sécurité des chemins intégrés de 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 à l'outil d'éditeur de texte. Voir les sections de commande d'outil individuelles ci-dessus pour les messages d'erreur détaillés et les comportements. Les erreurs courantes incluent fichier non trouvé, erreurs de permission, chemins invalides et correspondances de texte dupliquées.

Intégration de 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, voir Context editing.

Utilisation avec Compaction

L'outil de mémoire peut également être associé à compaction, qui fournit une résumé côté serveur du contexte de conversation plus ancien. Tandis que l'édition de contexte efface les résultats d'outil spécifiques côté client, la compaction résume automatiquement la conversation entière côté serveur quand elle approche de la limite de la fenêtre de contexte.

Pour les flux de travail d'agent 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 persiste les informations importantes entre les limites de compaction afin que rien de critique ne soit perdu dans le résumé.

Modèle de développement logiciel multi-session

Pour les projets logiciels de longue durée qui s'étendent sur plusieurs sessions d'agent, les fichiers de mémoire doivent être amorcés délibérément, pas seulement écrits de manière ad hoc au fur et à mesure que le travail progresse. 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 dernière s'était arrêtée.

Comment ça marche

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 (suivi de ce qui a été fait et de ce qui vient ensuite), une liste de contrôle des fonctionnalités (définissant la portée du travail) et une référence à tout script de démarrage ou d'initialisation dont le projet a besoin.

2. Sessions ultérieures : Chaque nouvelle session s'ouvre en lisant ces artefacts de mémoire. Cela récupère l'état complet du projet en quelques secondes, sans avoir besoin de réexplorer la base de code ou de retracer les décisions antérieures.

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

Principe clé

Travailler sur une fonctionnalité à la fois. Marquer une fonctionnalité comme complète uniquement après que la vérification de bout en bout confirme qu'elle fonctionne, pas seulement après que le code a été écrit. Cela maintient le journal de progression fiable et empêche la dérive de portée de se composer entre les sessions.

Prochaines étapes