Outil de mémoire

L'outil de mémoire permet à Claude de stocker et récupérer des informations à travers les conversations grâce à un répertoire de fichiers de mémoire. Claude peut créer, lire, mettre à jour et supprimer des fichiers qui persistent entre les sessions, lui permettant de construire des connaissances au fil du temps sans tout garder 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 grâce à votre propre infrastructure.

Cas d'usage

• Maintenir le contexte de projet à travers plusieurs exécutions d'agent
• Apprendre des interactions passées, des décisions et des retours
• Construire des bases de connaissances au fil du temps
• Permettre l'apprentissage inter-conversationnel où Claude s'améliore sur les flux de travail récurrents

Comment ça fonctionne

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 fait des appels d'outils 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 devriez restreindre toutes les opérations de mémoire au répertoire /memories.

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

Quand 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 :

"Aidez-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 précédent."

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 :

"Basé sur 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.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

Usage 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": "Je travaille sur un web scraper Python qui continue de planter avec une erreur de timeout. Voici la fonction problématique :\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\nVeuillez m'\''aider à déboguer ceci."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

Commandes d'outils

Votre implémentation côté client doit gérer ces commandes d'outils 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 : voir des lignes spécifiques
}

create

Créer ou écraser un fichier :

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Notes de réunion :\n- Discuté de la chronologie du projet\n- Prochaines étapes définies\n"
}

str_replace

Remplacer du texte dans un fichier :

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Couleur préférée : bleu",
  "new_str": "Couleur préférée : vert"
}

insert

Insérer du texte à une ligne spécifique :

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Réviser la documentation de l'outil de mémoire\n"
}

delete

Supprimer un fichier ou 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 prompt

Nous incluons automatiquement cette instruction dans le prompt système quand l'outil de mémoire est inclus :

IMPORTANT : TOUJOURS VOIR VOTRE RÉPERTOIRE DE MÉMOIRE AVANT DE FAIRE QUOI QUE CE SOIT D'AUTRE.
PROTOCOLE DE MÉMOIRE :
1. Utilisez la commande `view` de votre outil `memory` pour vérifier les progrès antérieurs.
2. ... (travailler sur la tâche) ...
     - Au fur et à mesure que vous progressez, enregistrez le statut / progrès / pensées etc dans votre mémoire.
SUPPOSER UNE INTERRUPTION : Votre fenêtre de contexte pourrait être réinitialisée à tout moment, donc vous risquez de perdre tout progrès qui n'est pas enregistré dans votre répertoire de mémoire.

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

Note : lors de l'édition de votre dossier de mémoire, essayez toujours de garder son contenu à jour, cohérent et organisé. Vous pouvez renommer ou supprimer des fichiers qui ne sont plus pertinents. Ne créez pas de nouveaux fichiers sauf si nécessaire.

Vous pouvez aussi guider ce que Claude écrit en mémoire, par exemple, "Écrivez seulement des informations pertinentes à <sujet> 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 pourriez vouloir implémenter une validation plus stricte qui supprime les informations potentiellement sensibles.

Taille de stockage des fichiers

Considérez le suivi des tailles des fichiers de mémoire et empêchez les fichiers de devenir trop volumineux. Considérez l'ajout d'un nombre maximum de caractères que la commande de lecture de mémoire peut retourner, et laissez Claude paginer à travers le contenu.

Expiration de la mémoire

Considérez effacer périodiquement les fichiers de mémoire qui n'ont pas été accédés pendant une période prolongée.

Protection contre la traversée de chemin

Considérez ces mesures de protection :

• Validez que tous les chemins commencent par /memories
• Résolvez les chemins à 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 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 de 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 d'erreurs que l'outil d'éditeur de texte. Les erreurs communes 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'outils quand le contexte de conversation dépasse un seuil configuré. Cette combinaison permet des flux de travail agentiques de longue durée qui dépasseraient autrement les limites de contexte.

Comment ils fonctionnent ensemble

Quand 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'outils dans des fichiers de mémoire avant que ces résultats soient effacés de la fenêtre de contexte.

Après que les résultats d'outils sont effacés, Claude peut récupérer l'information stockée des fichiers de mémoire quand nécessaire, traitant effectivement la mémoire comme une extension de son contexte de travail. Cela permet à Claude de :

• Continuer des flux de travail complexes, multi-étapes sans perdre d'information critique
• Référencer le travail et les décisions passés même après que les résultats d'outils sont supprimés
• Maintenir un contexte cohérent à travers des 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 fait de nombreuses modifications aux fichiers, générant beaucoup de résultats d'outils
2. Alors que le contexte grandit et approche de votre seuil, Claude reçoit un avertissement
3. Claude résume les changements faits jusqu'à présent dans un fichier de mémoire (par exemple, /memories/refactoring_progress.xml)
4. L'édition de contexte efface automatiquement les anciens résultats d'outils
5. Claude continue de travailler, référençant le fichier de mémoire quand il a besoin de se rappeler quels changements ont déjà été complétés
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"
        },
        # Vos autres outils
    ],
    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 aussi exclure les appels d'outils de mémoire d'être effacés pour assurer que Claude ait toujours accès aux opérations de mémoire récentes :

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