Aller au contenu principal

Mémoire et édition du contexte

Avancé

Un agent à exécution longue a deux ennemis : il oublie ce qu'il a appris à l'instant où la conversation se termine, et sa fenêtre de contexte se remplit de sorties d'outils périmées jusqu'à déborder. Anthropic livre une primitive pour chacun — l'outil memory (persistance) et l'édition du contexte (élagage) — et ils sont conçus pour être utilisés ensemble.

What you'll learn
  • Ce qu'est l'outil memory — un stockage de fichiers côté client à /memories que vous implémentez, pas Anthropic
  • Les six commandes auxquelles votre gestionnaire doit répondre : view, create, str_replace, insert, delete, rename
  • Pourquoi la validation contre la traversée de chemins est non négociable quand vous le câblez
  • Comment l'édition du contexte efface automatiquement les anciens résultats d'outils une fois que le contexte franchit un seuil de tokens
  • Comment combiner les deux sous un même en-tête bêta, et les pièges liés au cache et à l'ordre

Deux problèmes, deux outils​

Gardez les deux idées séparées dans votre tête :

  • Outil memory = persistance entre les sessions. Claude lit et écrit des fichiers ; vous les stockez.
  • Édition du contexte = élagage au sein d'une session. L'API supprime les résultats d'outils périmés du prompt avant qu'il n'atteigne Claude.

Cette page va de pair avec Mise en cache des prompts et l'économie des tokens pour le volet coût, et avec l'ingénierie du contexte et les harnais d'agents à exécution longue pour le pourquoi.

Vocabulaire de la mémoire et du contexte
Appuyez sur Entrée ou Espace pour retourner la carte. Utilisez les flèches gauche et droite pour naviguer entre les cartes.Terme affiché.
1 / 5

L'outil memory est un outil que vous implémentez​

C'est ce qui fait trébucher les gens : activer l'outil memory ne vous donne pas un stockage hébergé par Anthropic. C'est un outil côté client. Claude émet des appels d'outils comme view ou create ; votre application les exécute contre le backend de votre choix — fichiers locaux, base de données, blobs chiffrés, stockage cloud — et renvoie le résultat. Vous décidez où vivent les octets (c'est aussi pourquoi c'est éligible au Zero-Data-Retention).

Quand l'outil est activé, Anthropic injecte une instruction système indiquant à Claude de vérifier son répertoire de mémoire avant toute autre chose, et d'enregistrer sa progression au fil du travail afin que rien ne soit perdu si le contexte est réinitialisé.

Étape 1 — activer l'outil​

Ajoutez l'outil à votre requête. La chaîne de type est la version datée memory_20250818.

import anthropic

client = anthropic.Anthropic()

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

print(message)

Les SDK officiels livrent des helpers de mémoire pour que vous n'ayez pas à coder à la main l'interface de l'outil — dérivez BetaAbstractMemoryTool (Python, C#), utilisez betaMemoryTool (TypeScript), ou implémentez BetaMemoryToolHandler (Java). Ils vous offrent un point d'accroche propre où brancher votre stockage.

Étape 2 — répondre aux six commandes​

Votre gestionnaire doit les implémenter. Les chaînes que Claude attend en retour sont spécifiques — respectez-les pour que le modèle interprète correctement les résultats.

Guided walkthrough1 of 6
  1. Lister un répertoire (fichiers jusqu'à 2 niveaux de profondeur, avec des tailles lisibles par l'humain) ou renvoyer le contenu d'un fichier avec des numéros de ligne indexés à partir de 1. view_range optionnel pour lire une tranche.

Un vrai view du répertoire renvoie quelque chose comme ceci — notez l'en-tête littéral et les tailles séparées par des tabulations, que le modèle est entraîné à analyser :

Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:
4.0K	/memories
1.5K	/memories/customer_service_guidelines.xml
2.0K	/memories/refund_policies.xml

Étape 3 — verrouiller les chemins (ne sautez pas cette étape)​

L'outil memory permet à un modèle d'émettre des chaînes de chemin arbitraires. Une conversation empoisonnée ou une charge utile d'injection de prompt peut tenter de s'échapper de /memories et de lire ou d'écraser des fichiers ailleurs sur votre machine. Traitez chaque chemin entrant comme hostile.

Watch out
  • Rejetez tout chemin qui ne se résout pas à l'intérieur de /memories.
  • Canonicalisez avant de vérifier — en Python, Path(p).resolve() puis vérifiez que .relative_to(memories_root) ne lève pas d'exception.
  • Bloquez ../, ..\, et la traversée encodée en URL comme %2e%2e%2f.
  • Plafonnez la taille des fichiers et la longueur de lecture pour qu'un agent emballé ne puisse pas épuiser le disque ou faire exploser le prompt suivant.

Ce validateur, c'est tout l'enjeu — verrouillez-le et testez-le avant que quoi que ce soit d'autre ne soit livré :

Garde contre la traversée de chemins (Python)

from pathlib import Path

MEMORY_ROOT = Path("/srv/agent/memories").resolve()

def safe_path(requested: str) -> Path:
  # Map the model's /memories/... onto your real root, then prove containment.
  rel = requested.removeprefix("/memories").lstrip("/")
  candidate = (MEMORY_ROOT / rel).resolve()
  candidate.relative_to(MEMORY_ROOT)  # raises ValueError if it escaped
  return candidate

L'édition du contexte empêche la fenêtre de déborder​

La mémoire résout l'oubli. Le problème inverse — une fenêtre de contexte bourrée de vieux blocs tool_result provenant de 40 recherches web en arrière — est ce que résout l'édition du contexte. Une fois que le prompt franchit un seuil de tokens, l'API efface les résultats d'outils les plus anciens (en les remplaçant par un court espace réservé pour que Claude sache qu'ils ont été supprimés) avant que le prompt ne soit envoyé au modèle. Votre client conserve l'historique complet et non édité ; seul ce qui atteint le modèle est rogné.

Cela s'appuie sur un en-tête bêta :

anthropic-beta: context-management-2025-06-27

Vous le configurez avec un tableau context_management.edits. La stratégie principale est clear_tool_uses_20250919 :

message = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    betas=["context-management-2025-06-27"],
    messages=[...],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},  # start clearing past 30k
                "keep": {"type": "tool_uses", "value": 3},            # always keep the last 3
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["memory"],                          # never clear memory calls
                "clear_tool_inputs": False,                           # keep the call args, drop results
            }
        ]
    },
)

Ce que signifient les réglages :

ParamètreValeur par défautCe qu'il contrôle
trigger100 000 tokens d'entréeQuand l'effacement se déclenche
keep3 utilisations d'outilsCombien de paires récentes utilisation/résultat d'outil sont toujours préservées
clear_at_leastaucuneMinimum de tokens libérés par activation — utilisez-le pour qu'une invalidation de cache en vaille réellement la peine
exclude_toolsaucunOutils jamais effacés (p. ex. memory, web_search)
clear_tool_inputsfalseS'il faut aussi supprimer les arguments d'appel de l'outil, pas seulement le résultat

La réponse vous indique ce qu'elle a fait, sous context_management.applied_edits — p. ex. cleared_tool_uses et cleared_input_tokens — pour que vous puissiez journaliser combien a été récupéré.

Il existe une stratégie sœur, clear_thinking_20251015, qui élague les anciens blocs de réflexion étendue. Si vous utilisez les deux, listez clear_thinking_20251015 en premier dans le tableau edits.

Pro tip
  • Effacer les résultats d'outils invalide tout préfixe de cache de prompt au point d'effacement — associez-le à clear_at_least pour ne payer cette invalidation que lorsque vous libérez un volume significatif.
  • exclude_tools: ["memory"] est le réflexe habituel : vous voulez que les propres notes de l'agent persistent, et non qu'elles soient balayées avec les résultats de recherche périmés.
  • L'édition du contexte (rognage côté client) et la compaction (résumé côté serveur) sont des fonctionnalités différentes — pour les exécutions très longues, vous pouvez superposer les deux.

Pourquoi les associer — les chiffres​

Utilisées ensemble, les deux fonctionnalités permettent à un agent de fonctionner bien au-delà d'une seule fenêtre de contexte : l'édition du contexte garde la fenêtre active légère, et tout ce qui compte est écrit en mémoire avant d'être effacé. Anthropic rapporte que combiner la mémoire avec l'édition du contexte a donné une amélioration de 39 % sur une évaluation de recherche agentique, et que l'édition du contexte à elle seule a réduit l'utilisation de tokens de 84 % dans un test de recherche web sur 100 tours.

Un modèle qui fonctionne : le journal de projet multi-session​

L'usage le plus propre de la mémoire consiste à l'amorcer délibérément plutôt qu'à écrire des fichiers de manière ad hoc :

Guided walkthrough1 of 4
  1. Avant tout travail réel, écrivez un journal de progression, une liste de contrôle des fonctionnalités, et une note pointant vers tout script de démarrage dont le projet a besoin.

Testez votre compréhension​

Check yourself

0/3
  1. Où sont réellement stockées les données de l'outil memory ?
  2. Que supprime la stratégie clear_tool_uses_20250919 de l'édition du contexte ?
  3. Pourquoi devez-vous valider chaque chemin que reçoit l'outil memory ?

Sources et lectures complémentaires​