Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
L'outil de mémoire permet à Claude de stocker et récupérer des informations entre les conversations dans un répertoire de fichiers de mémoire. Claude peut créer, lire, mettre à jour et supprimer des fichiers qui persistent entre les sessions, accumulant des connaissances au fil du temps sans tout conserver dans la fenêtre de contexte.
La mémoire prend en charge la récupération de contexte juste-à-temps. Plutôt que de charger toutes les informations pertinentes dès le départ, un agent enregistre ce qu'il apprend dans des fichiers de mémoire et les relit à la demande. Cela maintient le contexte actif concentré sur la tâche en cours, ce qui est important pour les sessions de longue durée qui, autrement, submergeraient la fenêtre de contexte. Consultez Effective context engineering pour le modèle plus général.
L'outil de mémoire fonctionne côté client : Claude demande des opérations de fichiers, et votre application les exécute. Vous contrôlez où et comment les données sont stockées via votre propre infrastructure.
Lorsque l'outil de mémoire est activé, Claude vérifie automatiquement son répertoire de mémoire avant de commencer une tâche. Au fur et à mesure de son travail, Claude stocke ce qu'il apprend dans des fichiers sous /memories et les relit lors de conversations ultérieures pour poursuivre le travail antérieur.
Comme l'outil de mémoire est côté client, Claude ne fait que demander des opérations de mémoire. Votre application exécute chaque requête sur un stockage que vous contrôlez et renvoie le résultat dans un bloc tool_result (voir Gérer les appels d'outils). Le chemin /memories est un préfixe que votre gestionnaire fait correspondre à un stockage réel, tel qu'un répertoire par utilisateur ou des clés dans une base de données. La mémoire réside entièrement dans votre application. Une conversation ultérieure reprend à partir de la même mémoire lorsqu'elle envoie la même entrée tools et que votre gestionnaire sert le même magasin. Pour des raisons de sécurité, restreignez toutes les opérations de mémoire au répertoire /memories (voir Protection contre la traversée de chemin).
Une interaction typique ressemble à ceci :
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 aider :
"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."L'outil de mémoire est disponible sur tous les modèles Claude 4 et ultérieurs. Pour la liste complète des outils fournis par Anthropic, consultez la Référence des outils.
L'outil de mémoire est disponible en disponibilité générale sur l'API Messages : aucun en-tête bêta n'est requis. Son utilisation se fait en deux étapes :
tools {"type": "memory_20250818", "name": "memory"} constitue l'intégralité de la configuration : le name doit être memory, et vous ne définissez pas de schéma d'entrée pour un outil fourni par Anthropic./memories, donc lisez Protection contre la traversée de chemin avant de l'écrire.client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-5",
max_tokens=2048,
messages=[
{
"role": "user",
"content": "Help me respond to this customer service ticket.",
}
],
tools=[{"type": "memory_20250818", "name": "memory"}],
)
print(message)La réponse de Claude à une requête comme la précédente se termine par un bloc tool_use qui demande une opération de mémoire, telle que view /memories. Votre application exécute l'opération et renvoie le résultat dans un bloc tool_result, puis renvoie la conversation pour que Claude puisse continuer : la boucle d'utilisation d'outils standard.
Quatre SDK fournissent des assistants pour l'outil de mémoire qui gèrent l'interface de l'outil et la boucle. Créez une sous-classe de BetaAbstractMemoryTool (Python et C#), utilisez betaMemoryTool (TypeScript), ou implémentez BetaMemoryToolHandler (Java) pour adosser la mémoire à votre propre stockage, tel que des fichiers sur disque, une base de données, un stockage cloud ou des fichiers chiffrés. Python et TypeScript fournissent également une implémentation prête à l'emploi pour le système de fichiers local, BetaLocalFilesystemMemoryTool. Les surfaces d'assistants et d'exécuteurs d'outils se trouvent dans l'espace de noms bêta de chaque SDK, même si l'outil de mémoire lui-même est en disponibilité générale. Les SDK Go et Ruby n'ont pas d'assistant de mémoire, donc ces exemples exécutent eux-mêmes la boucle d'utilisation d'outils, et PHP enveloppe votre closure de gestionnaire dans son BetaRunnableTool générique. Tous les trois utilisent un magasin en mémoire que vous remplacez par votre propre stockage.
import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool
client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
runner = client.beta.messages.tool_runner(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Remember that customer Acme Corp prefers email follow-ups.",
}
],
tools=[memory],
)
final_message = runner.until_done()
print(final_message.content)Les magasins en mémoire dans les exemples Go, PHP et Ruby les rendent autonomes : chacun effectue une répartition selon le champ command dans l'input du bloc tool_use et renvoie les chaînes décrites sous Commandes de l'outil. Un gestionnaire de production a également besoin de la validation de chemin que ces magasins de démonstration omettent. Pour les exemples complets des SDK eux-mêmes, consultez :
Votre implémentation côté client doit gérer les commandes suivantes. Ces spécifications décrivent les comportements recommandés et les chaînes de retour : Claude lit le texte que contient votre résultat d'outil, quel qu'il soit, vous pouvez donc renvoyer des chaînes différentes si votre application en a besoin.
Affiche le contenu d'un répertoire ou le contenu d'un fichier avec des plages de lignes optionnelles :
{
"command": "view",
"path": "/memories/notes.txt",
"view_range": [1, 10]
}view_range est optionnel et s'applique aux vues de fichiers texte : [start_line, end_line] renvoie ces lignes, et [start_line, -1] renvoie tout depuis start_line jusqu'à la fin du fichier.
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}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}5.5K, 1.2M).) et node_modulesLe premier view de /memories sur un magasin vide n'est pas une erreur. Les outils de mémoire pour système de fichiers local des SDK (BetaLocalFilesystemMemoryTool) créent la racine de mémoire avant le premier appel de Claude et renvoient l'en-tête de la liste suivi d'une seule ligne taille-et-chemin pour le répertoire vide lui-même.
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 :
"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 hundredLa description de l'outil pour Claude indique également que view affiche les fichiers image (.jpg, .jpeg et .png) et tronque la vue texte des fichiers de plus de 16 000 caractères. Attendez-vous à des appels view sur des chemins d'images et à des vues avec plage de suivi pour les fichiers longs.
"The path {path} does not exist. Please provide a valid path."Crée un nouveau fichier :
{
"command": "create",
"path": "/memories/notes.txt",
"file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}"File created successfully at: {path}""Error: File {path} already exists"La description de l'outil pour Claude indique que create « crée ou écrase » un fichier, attendez-vous donc à des appels create sur des chemins qui existent déjà. Renvoyer l'erreur est le comportement de référence, et écraser à la place est un choix d'implémentation valide.
Remplace du texte dans un fichier :
{
"command": "str_replace",
"path": "/memories/preferences.txt",
"old_str": "Favorite color: blue",
"new_str": "Favorite color: green"
}new_str est optionnel pour str_replace : lorsqu'il est omis, old_str est supprimé sans remplacement.
"The memory file has been edited." suivi d'un extrait de code du fichier modifié avec les numéros de ligne"Error: The path {path} does not exist. Please provide a valid path.""No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."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"Si le chemin est un répertoire, renvoyez une erreur « le fichier n'existe pas ».
Insère du texte à une ligne spécifique :
{
"command": "insert",
"path": "/memories/todo.txt",
"insert_line": 2,
"insert_text": "- Review memory tool documentation\n"
}insert_text est inséré après la ligne insert_line, et 0 insère au début du fichier.
"The file {path} has been edited.""Error: The path {path} does not exist""Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"Si le chemin est un répertoire, renvoyez une erreur « le fichier n'existe pas ».
Supprime un fichier ou un répertoire :
{
"command": "delete",
"path": "/memories/old_file.txt"
}"Successfully deleted {path}""Error: The path {path} does not exist"Supprime le répertoire et tout son contenu de manière récursive. La description de l'outil indique à Claude qu'il ne peut pas supprimer le répertoire /memories lui-même, rejetez donc un delete dont le chemin est la racine de mémoire.
Renomme ou déplace un fichier ou un répertoire :
{
"command": "rename",
"old_path": "/memories/draft.txt",
"new_path": "/memories/final.txt"
}"Successfully renamed {old_path} to {new_path}""Error: The path {old_path} does not exist""Error: The destination {new_path} already exists"Renomme le répertoire. La description de l'outil indique à Claude qu'il ne peut pas renommer le répertoire /memories lui-même, rejetez donc un rename dont le old_path est la racine de mémoire.
Lorsque l'outil de mémoire est présent dans les tools de votre requête, l'API ajoute automatiquement cette instruction à l'invite système. Vous n'avez pas besoin de l'envoyer vous-même :
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.La description de l'outil pour Claude lui indique déjà de garder le répertoire de mémoire organisé, vous n'avez donc pas besoin de répéter cette instruction. Si Claude crée malgré tout des fichiers de mémoire encombrés, vous pouvez le renforcer dans votre prompt :
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 : « N'écrivez dans votre système de mémoire que les informations pertinentes pour <topic>. »
Votre application exécute chaque opération de fichier que Claude demande, ces protections sont donc de votre responsabilité :
Claude refuse généralement d'écrire des informations sensibles dans les fichiers de mémoire. Pour des garanties plus solides, ajoutez une validation qui supprime les données sensibles avant que votre gestionnaire n'écrive le fichier.
Suivez la taille des fichiers de mémoire et plafonnez la taille maximale qu'un fichier peut atteindre. Envisagez de plafonner le nombre de caractères que la commande view renvoie, et laissez Claude parcourir le reste avec view_range.
Supprimez périodiquement les fichiers de mémoire qui n'ont pas été consultés depuis longtemps.
Envisagez ces protections :
/memories../, ..\\, ou d'autres motifs de traversée%2e%2e%2f)pathlib.Path.resolve() et relative_to() de Python)L'outil de mémoire utilise des modèles de gestion des erreurs similaires à ceux de l'outil d'édition de texte. Les messages d'erreur de chaque commande sont listés sous Commandes de l'outil. Pour renvoyer une erreur à Claude, définissez is_error à true sur le résultat de l'outil et placez le message dans content :
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Error: The path /memories/notes.txt does not exist",
"is_error": true
}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.
L'outil de mémoire peut également être combiné avec la compaction, qui résume le contexte de conversation plus ancien côté serveur. 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 lorsque la conversation approche de la limite de la fenêtre de contexte.
Pour les agents de longue durée, envisagez d'utiliser les deux : la compaction maintient le contexte actif réduit sans comptabilité côté client, et la mémoire préserve les informations qui doivent survivre à la synthèse.
Pour les projets logiciels qui s'étendent sur plusieurs sessions d'agent, configurez les fichiers de mémoire de manière délibérée au lieu de les écrire au fil de l'eau à mesure que le travail progresse. Le modèle suivant transforme la mémoire en mécanisme de récupération : chaque nouvelle session reprend à partir de l'état que la précédente a enregistré.
Session d'initialisation : La première session configure les fichiers 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.
Sessions suivantes : Chaque nouvelle session commence par la lecture de ces fichiers de mémoire. Cela restaure l'état du projet sans réexplorer la base de code ni retracer les décisions antérieures.
Mise à jour de fin de session : Avant la fin d'une session, celle-ci met à jour le journal de progression avec ce qui a été accompli et ce qui reste. Cela garantit que la session suivante dispose d'un point de départ précis.
Travaillez sur une 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 lorsque le code est écrit. Cela maintient le journal de progression précis de session en session.
Exécutez des commandes shell dans une session bash persistante.
Gérez automatiquement le contexte de conversation à mesure qu'il grandit avec l'édition de contexte.
Compaction de contexte côté serveur pour gérer les longues conversations qui approchent des limites de la fenêtre de contexte.
Répertoire des outils fournis par Anthropic et référence pour les propriétés optionnelles de définition d'outils.
Was this page helpful?