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.

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
• Activer l'apprentissage entre conversations où Claude s'améliore sur les flux de travail récurrents

Comment ça marche

Lorsqu'elle est activée, 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 les conversations futures pour gérer des tâches similaires plus efficacement ou reprendre là où il s'était arrêté.

Puisqu'il s'agit d'un outil côté client, Claude effectue des appels d'outil pour effectuer 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": "Directory: /memories\n- customer_service_guidelines.xml\n- 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": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}

6. Claude utilise la mémoire pour aider :

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

Modèles supportés

L'outil de mémoire est disponible sur :

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Commencer

Pour utiliser l'outil de mémoire :

1. Incluez l'en-tête bêta context-management-2025-06-27 dans vos requêtes API
2. Ajoutez l'outil de mémoire à votre requête
3. Implémentez des gestionnaires côté client pour les opérations de mémoire

Utilisation de base

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

Commandes d'outil

Votre implémentation côté client doit gérer ces commandes d'outil de mémoire :

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
}

create

Créer ou remplacer un fichier :

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

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

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

delete

Supprimer un fichier ou un répertoire :

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

rename

Renommer ou déplacer un fichier/répertoire :

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

Conseils de formulation

Nous incluons automatiquement cette instruction dans l'invite système lorsque l'outil de mémoire est inclus :

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é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, « Écrivez uniquement les informations pertinentes à <topic> dans votre système de mémoire. »

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 pouvez vouloir 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 motifs 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 à votre langage (par exemple, pathlib.Path.resolve() et relative_to() de Python)

Gestion des erreurs

L'outil de mémoire utilise les mêmes modèles de gestion des erreurs que l'outil d'éditeur de texte. Les erreurs courantes incluent fichier non trouvé, erreurs de permission et chemins invalides.

Utilisation avec l'édition de contexte

L'outil de mémoire peut être combiné avec l'édition de contexte, qui efface automatiquement les anciens résultats d'outil lorsque le contexte de la conversation dépasse un seuil configuré. Cette combinaison permet les flux de travail d'agent longue durée qui dépasseraient autrement les limites de contexte.

Comment ils fonctionnent ensemble

Lorsque l'édition de contexte est activée et que votre conversation approche du seuil d'effacement, Claude reçoit automatiquement une notification d'avertissement. Cela incite Claude à préserver toute information importante des résultats d'outil dans les fichiers de mémoire avant que ces résultats ne soient effacés de la fenêtre de contexte.

Après que les résultats d'outil soient effacés, Claude peut récupérer les informations stockées à partir des fichiers de mémoire chaque fois que nécessaire, traitant efficacement la mémoire comme une extension de son contexte de travail. Cela permet à Claude de :

• Continuer les flux de travail complexes et multi-étapes sans perdre d'informations critiques
• Référencer les travaux et décisions passés même après que les résultats d'outil soient supprimés
• Maintenir un contexte cohérent entre les conversations qui dépasseraient les limites de contexte typiques
• Construire une base de connaissances au fil du temps tout en gardant la fenêtre de contexte active gérable

Exemple de flux de travail

Considérez un projet de refactorisation de code avec de nombreuses opérations de fichiers :

1. Claude effectue de nombreuses modifications de fichiers, générant de nombreux résultats d'outil
2. À mesure que le contexte grandit et approche votre seuil, Claude reçoit un avertissement
3. Claude résume les modifications apportées jusqu'à présent dans un fichier de mémoire (par exemple, /memories/refactoring_progress.xml)
4. L'édition de contexte efface automatiquement les résultats d'outil plus anciens
5. Claude continue à travailler, référençant le fichier de mémoire lorsqu'il a besoin de rappeler quelles modifications ont déjà été complétées
6. Le flux de travail peut continuer indéfiniment, avec Claude gérant à la fois le contexte actif et la mémoire persistante

Configuration

Pour utiliser les deux fonctionnalités ensemble :

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Your other tools
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

Vous pouvez également exclure les appels d'outil de mémoire d'être effacés pour vous assurer que Claude a toujours accès aux opérations de mémoire récentes :

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}