Mémoire Claude Code : le guide du contexte persistant

Chaque session Claude Code commence de la même façon : aucun souvenir d'hier. Vous passez vingt minutes à expliquer le flux d'authentification de votre API lundi, et mardi vous l'expliquez à nouveau, parce que rien dans le fonctionnement du modèle ne le transporte de lui-même. Ce manque est le correctif le plus demandé que nous entendons de la part des équipes qui font tourner Claude Code au quotidien, et c'est aussi le plus mal compris, parce que « donner de la mémoire à Claude » n'est pas une seule fonctionnalité. Ce sont quatre mécanismes avec des métiers, des coûts et des modes d'échec différents.

Ce guide les démêle : ce que chaque couche résout réellement, ce qui appartient à laquelle, comment mettre en place une skill mémoire comme claude-mem, et les mathématiques de tokens qui expliquent pourquoi se souvenir est bon marché alors que redécouvrir les mêmes faits à chaque session ne l'est pas.

Le problème du jour de la marmotte

Un modèle de langage n'a aucun état entre les appels d'API. Chaque message que vous envoyez inclut toute la conversation jusque-là, et quand cette conversation se termine, tout ce que le modèle « savait » sur votre projet se termine aussi. Ouvrez une nouvelle session demain et vous repartez d'une page blanche, quels que soient les fichiers présents sur le disque.

Ce serait très bien si les sessions étaient courtes et autonomes. Elles ne le sont pas. Le vrai travail s'étale sur des jours : vous corrigez un bug lundi, le même schéma apparaît dans un fichier différent jeudi, et l'agent n'a aucun moyen de relier les deux à moins que quelque chose en dehors de la conversation n'ait porté cette connexion. Chaque session sans cela paie une taxe de redécouverte : relire les mêmes fichiers, réapprendre les mêmes conventions, répéter occasionnellement une erreur déjà corrigée.

La solution n'est pas une fenêtre de contexte plus grande. Les fenêtres de contexte sont déjà grandes, et le problème n'est pas la capacité, c'est la continuité. Ce que vous voulez, c'est un endroit en dehors de la conversation où les faits et les décisions survivent, plus un moyen pour Claude de recharger la bonne tranche de cet endroit quand ça compte. C'est la mémoire, et Claude Code vous donne quatre façons de la construire.

Les quatre couches de la mémoire Claude

La couche un est CLAUDE.md : des faits de projet statiques que vous écrivez une fois, qui se chargent en entier au début de chaque session. La couche deux est l'auto-mémoire, un répertoire de fichiers dans lesquels Claude écrit lui-même, accumulant des faits au fil du temps sans que vous les rédigiez à la main. La couche trois est les skills mémoire, qui capturent et compressent automatiquement le contexte de session et le réinjectent plus tard. La couche quatre est l'option low-tech : un fichier de notes en texte brut que l'agent lit et met à jour parce que vous le lui avez demandé.

Ce ne sont pas des options concurrentes. Elles résolvent des problèmes différents, et la plupart des configurations sérieuses en font tourner deux ou trois à la fois.

Couche 1 : CLAUDE.md, des faits statiques toujours chargés

CLAUDE.md est le mécanisme de mémoire le plus ancien et le plus simple de Claude Code. C'est un fichier markdown que Claude Code trouve en remontant depuis votre répertoire de travail, et il se charge en entier, à chaque session, avant que vous ne tapiez quoi que ce soit. Cela en fait le bon endroit pour les faits qui sont presque toujours vrais : comment lancer les tests, quel gestionnaire de paquets utilise le dépôt, quel dossier est legacy et interdit.

C'est le mauvais endroit pour tout ce qui change souvent ou ne s'applique qu'occasionnellement, parce que « se charge en entier, à chaque session » est aussi son coût. Un CLAUDE.md de 3 000 lignes représente environ 30 000 tokens taxés à chaque requête, que cette requête en ait besoin ou non. Nous couvrons l'arithmétique complète avec un exemple annoté réel dans notre guide des bonnes pratiques CLAUDE.md ; la version courte est que CLAUDE.md veut des faits stables, pas un journal qui grossit.

C'est aussi là que CLAUDE.md arrive en bout de course. Il est statique : vous l'écrivez, Claude le lit, et le mettre à jour est une corvée manuelle que vous devez penser à faire. Les trois couches suivantes existent pour gérer les faits qui s'accumulent d'eux-mêmes.

Couche 2 : l'auto-mémoire et les répertoires de mémoire

La couche du milieu est un répertoire de mémoire, souvent ~/.claude/memory/ ou un équivalent local au projet, où Claude écrit des notes structurées sur ce qu'il apprend et les relit au début des sessions futures. Contrairement à CLAUDE.md, personne ne rédige à la main la plupart de ces entrées. L'agent décide que quelque chose vaut la peine d'être retenu, une décision que vous avez prise, une préférence que vous avez exprimée, un fait qu'il a dû creuser pour trouver, et le classe avec assez de structure pour le retrouver plus tard.

C'est là que vit la skill Memory Management, et c'est la skill la mieux notée dans cette catégorie sur SkillProof : 9,2 sur 10. Nous l'avons fait tourner sur une semaine complète de vraies sessions, pas une seule démo, et elle a tenu sous un usage réel. Claude a fidèlement rappelé des décisions de projet et des préférences qu'il avait stockées, et la précision de rappel est restée élevée même à mesure que le magasin grossissait, la partie qui casse habituellement en premier dans les implémentations naïves.

Ce qui distingue cette couche de CLAUDE.md, c'est qu'elle est sélective à l'entrée comme à la sortie. Une skill mémoire bien construite indexe ce qu'elle a stocké et récupère la tranche pertinente pour la tâche en cours, de sorte que le magasin peut grossir jusqu'à des milliers d'entrées sans que chaque session ne paie pour toutes.

Couche 3 : les skills mémoire, claude-mem et la capture automatique

La troisième couche pousse l'idée plus loin. Au lieu que Claude décide en cours de conversation ce qui vaut la peine d'être sauvegardé, une skill dédiée capture la session entière automatiquement, la compresse, et réinjecte le contexte pertinent dans la suivante. Claude-mem est l'exemple le plus clair de ce schéma. Son pitch est « contexte persistant à travers les sessions pour chaque agent » : il observe ce que fait votre agent pendant une session, compresse cette activité avec une passe de résumé par IA, et fait ressortir la version compressée la prochaine fois que c'est pertinent, à travers Claude Code et, selon sa propre documentation, plusieurs autres runtimes d'agents.

Nous devons être francs sur où il en est dans nos tests. Claude-mem est apparu via notre crawler GitHub avec 85 685 étoiles, ce qui explique pourquoi il est dans la file d'attente pour un test complet plutôt que de porter déjà un verdict ; nous ne publions pas de note avant d'avoir installé une skill proprement et de l'avoir fait tourner sur du vrai travail, la même barre que Memory Management a déjà franchie. Ce que nous pouvons dire maintenant est architectural : la capture automatique supprime le moment où vous vous arrêteriez autrement pour décider, en cours de session, si quelque chose vaut la peine d'être retenu. La skill décide à votre place. Reste à savoir si elle tient sur une semaine complète sur une machine vierge, ce que la file de test existe pour répondre.

Couche 4 : les fichiers simples comme mémoire

La dernière couche ne demande aucune skill : un simple fichier markdown, généralement appelé quelque chose comme notes.md ou progress.md, que vous demandez à Claude de lire au début d'une session et de mettre à jour à la fin. Pas d'indexation, pas de capture automatique, pas de notation. Vous êtes le système de mémoire ; le fichier n'est que l'endroit où vous l'écrivez.

Cette couche est sous-estimée parce qu'elle semble trop simple pour compter. Elle ne l'est pas. Pour un projet solo avec un seul contributeur et une poignée de fils en cours, un fichier de notes que vous maintenez réellement bat un système de mémoire automatisé que vous ne regardez jamais. Le mode d'échec repose entièrement sur vous, cependant : personne n'élague, personne ne signale les contradictions, et il devient un mur de texte avec les mêmes angles morts que n'importe quel document non maintenu développe. Il fonctionne exactement aussi bien que votre discipline à le mettre à jour, pas mieux.

Ce qui va où : le tableau de décision

Type de mémoire	Idéal pour	Se charge	Maintenance
CLAUDE.md	Faits stables, toujours vrais (commandes de build, conventions, pièges)	En entier, à chaque session	Manuelle, édition à la main
Auto-mémoire / répertoire de mémoire	Décisions et préférences qui s'accumulent avec le temps	Sélectivement, à la récupération	Surtout automatique (géré par une skill)
Skills mémoire (claude-mem)	Contexte de session complet, capturé sans que vous décidiez ce qui compte	Compressé, injecté quand pertinent	Capture automatique, revue occasionnelle
Fichier de notes simple	Projets solo, fils en cours simples	Manuel, vous dites à Claude de le lire	Entièrement manuelle

Lisez ce tableau selon ce qui change, pas selon ce qui est pratique à mettre en place. Si un fait serait toujours vrai dans six mois, il appartient à CLAUDE.md. Si c'est une décision prise cette semaine qui pourrait compter à nouveau plus tard, elle appartient à la mémoire. Si vous ne pouvez pas prédire ce dont vous aurez besoin de vous souvenir et ne voulez pas décider sur le moment, c'est le cas pour la capture automatique. Si rien de tout cela ne s'applique, un fichier de notes bat encore rien du tout.

Configurer claude-mem, étape par étape

Le schéma général pour une skill mémoire à capture automatique ressemble à ceci, en utilisant claude-mem comme exemple concret :

1. Clonez la skill. git clone https://github.com/thedotmack/claude-mem dans un répertoire de travail, puis suivez le script d'installation du dépôt plutôt que de copier les fichiers à la main. Les skills mémoire ont souvent besoin d'enregistrer un hook, pas seulement de déposer un SKILL.md en place.

2. Redémarrez Claude Code. L'installation câble généralement un hook de début ou de fin de session pour que la capture se produise sans que vous ayez à invoquer quoi que ce soit. Un redémarrage est ce qui active ce hook.

3. Faites tourner une session normale. Ne la testez pas avec une tâche jouet. Faites du vrai travail ; l'intérêt est de voir ce qu'elle décide de retenir quand personne ne surveille pour le test.

4. Démarrez votre session suivante et vérifiez ce qui est revenu. Demandez à Claude ce dont il se souvient du travail d'hier avant de dire quoi que ce soit d'autre. Quelque chose de spécifique et correct veut dire que la capture fonctionne. Quelque chose de vague ou faux veut dire vérifier la config avant de lui faire confiance avec quelque chose d'important.

5. Fixez une cadence de revue. La capture automatique sans revue se transforme en accumulation automatique de bruit. Accordez-vous un créneau récurrent de dix minutes pour parcourir ce qui a été stocké (plus de détails sous hygiène de mémoire, ci-dessous).

Si vous préférez commencer par quelque chose déjà noté, Memory Management est la voie manuelle-mais-testée : installez le dossier de skill dans ~/.claude/skills/, et il crée son propre répertoire de mémoire à la première utilisation, sans installation de hook séparée nécessaire.

L'économie en tokens de la mémoire

Voici le calcul qui rend la mise en place utile. Disons qu'un fait de projet prend 500 mots à expliquer depuis zéro : la forme de votre flux d'authentification, pourquoi une certaine table a deux clés étrangères, ce que fait réellement le script de déploiement. Expliqué à nouveau dans le chat, ça fait environ 650 tokens d'entrée à chaque fois que vous le réexpliquez, en plus du temps que vous passez à le taper et du temps que Claude passe à raisonner dessus dans ce message.

Stocké en mémoire à la place, le même fait coûte ces 650 tokens une fois, pour l'écrire. La récupération ensuite coûte une fraction de cela : une couche de mémoire bien indexée tire un résumé compressé, souvent sous les 100 tokens, seulement quand la tâche en cours touche ce fait. Expliquez-le dans le chat cinq fois sur un mois et vous avez dépensé environ 3 250 tokens à réenseigner ce que la mémoire aurait coûté 650 tokens à apprendre et 500 au total à rappeler cinq fois : un écart grossier de cinq contre un qui s'élargit à mesure que le fait est nécessaire plus souvent.

Comparez cela à tout entasser dans CLAUDE.md à la place : un fait pertinent une session sur vingt se charge quand même les dix-neuf autres, sans sélectivité pour récupérer ce coût. Le préambule fixe que porte votre configuration à chaque tour (CLAUDE.md, schémas d'outils, injections de mémoire) rivalise directement avec votre vrai travail pour l'espace et l'attention. Nous avons mesuré cela plus en profondeur, avec de vrais comptages de tokens avant/après, dans notre guide du coût en tokens ; la mémoire est une ligne dans ce tableau plus large, souvent la correction la moins chère par rapport à ce qu'elle économise.

Hygiène de mémoire : le rituel de revue

Un système de mémoire qui ne fait qu'accumuler n'est pas une fonctionnalité, c'est une fuite lente. Les entrées périmées n'échouent pas bruyamment ; rien ne plante quand Claude se rappelle d'une décision que vous avez renversée il y a trois semaines. Il agit simplement, discrètement, sur une information périmée, et vous perdez du temps de débogage à comprendre pourquoi l'agent a tort avec confiance à propos de quelque chose que vous savez avoir corrigé.

Faites une passe mensuelle, dix minutes, la même discipline que le rituel de revue CLAUDE.md que nous recommandons ailleurs. Ouvrez le magasin de mémoire. Pour chaque entrée qui semble structurante, demandez si elle est toujours vraie, si une décision qu'elle décrit a été renversée depuis, et si elle est assez spécifique pour agir dessus. Supprimez tout ce qui échoue. Un magasin de mémoire dont vous êtes fier est plus petit un an après qu'il ne l'était après trois mois ; la croissance devrait être en précision, pas en volume.

Le déclencheur le plus fiable pour une revue n'est cependant pas le calendrier. C'est le moment où Claude fait quelque chose de mal à cause d'une mémoire périmée. Traitez ça comme un bug : corrigez l'entrée dans le même souffle que l'erreur, pas à votre prochaine passe planifiée.

Confidentialité : ce qui est capturé, où ça vit

Les skills mémoire lisent ce qui se passe dans vos sessions, donc la question honnête est ce qui est capturé et où ça finit. Pour la mémoire basée sur des fichiers, Memory Management, claude-mem, et l'approche des notes simples pareillement, la réponse est généralement la même : tout est écrit dans des fichiers texte sur votre propre disque, typiquement sous ~/.claude/ ou un dossier de mémoire local au projet, pas sur un serveur tiers. Rien ne quitte votre machine à moins que vous ne commitiez ces fichiers dans un dépôt partagé ou qu'une skill ne documente explicitement une fonctionnalité de synchronisation distante.

C'est une bonne nouvelle pour le contrôle et une mauvaise nouvelle pour supposer que c'est automatiquement sûr. Un fichier de mémoire est un enregistrement en texte clair de ce sur quoi vous avez travaillé, et il peut inclure des identifiants mentionnés en passant, des noms de clients, ou des détails d'architecture que vous ne voudriez pas dans un dépôt public. Lisez ce qui se trouve réellement dans un répertoire de mémoire avant de le commiter avec votre code, et avant d'installer une skill mémoire quelconque, vérifiez sa source pour ce que « capture tout ce que fait votre agent » signifie vraiment, y compris si la sortie de commande contenant des secrets est aussi balayée. La capture automatique mérite le même examen que n'importe quel outil qui lit votre terminal.

FAQ

Claude Code a-t-il une mémoire persistante intégrée ?

Partiellement. CLAUDE.md offre une mémoire statique, toujours chargée, prête à l'emploi, et c'est réellement intégré, sans installation nécessaire. Tout ce qui va au-delà des faits statiques, une mémoire qui s'accumule, s'indexe, et se récupère sélectivement, vient actuellement d'une skill plutôt que d'une fonctionnalité native.

Quelle est la différence entre CLAUDE.md et une skill mémoire ?

CLAUDE.md se charge en entier, à chaque session, et vous le maintenez à la main. Une skill mémoire écrit et lit un magasin qui grossit de façon sélective, ne tirant que ce qui est pertinent pour la tâche en cours, et une grande partie de l'écriture se fait sans que vous le fassiez manuellement. Utilisez CLAUDE.md pour les faits qui ne changent jamais ; utilisez une skill mémoire pour les faits qui s'accumulent.

Est-il sûr d'installer claude-mem dès maintenant ?

Nous ne pouvons pas encore lui donner de verdict. Il est dans notre file de test, non noté, malgré son important suivi sur GitHub. Installez-le comme vous installeriez n'importe quoi de non noté : sur un projet où vous pouvez vous permettre d'expérimenter d'abord, et lisez la source avant de lui confier des sessions sensibles.

Combien coûte en tokens le fait de faire tourner une skill mémoire ?

Moins que l'alternative dans presque tous les cas. Le stockage lui-même est presque gratuit puisqu'il vit sur disque, pas dans le contexte. La récupération au démarrage de session coûte typiquement bien moins que réexpliquer le même fait dans le chat, et l'écart s'élargit à mesure que ce fait devrait sinon être réexpliqué plus de fois.

Devrais-je utiliser plus d'une couche de mémoire à la fois ?

Oui, et la plupart des configurations qui fonctionnent le font : CLAUDE.md pour les faits qui ne changent jamais, plus soit une skill mémoire soit un fichier de notes discipliné pour les faits qui s'accumulent. Traitez-les comme complémentaires plutôt que de choisir un favori. Le but est de faire correspondre chaque type de fait à la couche construite pour lui, pas de se fixer sur un seul mécanisme pour tout.