MEMORY.md : le guide complet de la mémoire persistante de Claude Code

Quatrième volet de la série Claude Code. Après CLAUDE.md, SKILL.md et les Hooks, on attaque le sujet qui change tout : la mémoire que Claude Code écrit pour lui-même.

Ce que vous allez apprendre — et pourquoi ça change tout

Quand vous lancez Claude Code, il lit votre CLAUDE.md. C’est votre mémoire manuelle — les instructions que vous avez écrites pour lui. J’ai consacré un article entier à ce mécanisme. Mais il existe un deuxième fichier, que vous n’avez probablement pas écrit, qui vit dans ~/.claude/projects/<votre-projet>/memory/MEMORY.md. Ce fichier, c’est Claude qui l’a créé. C’est Claude qui le maintient. Et c’est Claude qui le relit au démarrage de chaque session.

Ce n’est pas un détail d’implémentation. C’est le mécanisme qui transforme un assistant amnésique en un collaborateur qui apprend.

La documentation officielle d’Anthropic traite le sujet en quelques paragraphes. On y apprend que l’auto-memory est « activée par défaut » et que Claude « sauvegarde des notes pour lui-même ». C’est factuellement exact. C’est aussi spectaculairement insuffisant.

En réalité, la mémoire de Claude Code est un système à trois couches — mémoire manuelle, mémoire automatique, mémoire d’agent — avec une hiérarchie de priorité, une limite codée en dur à 200 lignes, un mécanisme de fichiers satellites à la demande, et des interactions subtiles avec la compaction, les hooks et les subagents. Comprendre ce système, c’est comprendre la différence entre un agent qui répète les mêmes erreurs et un agent qui progresse.

Cet article couvre : le fonctionnement interne de l’auto-memory (comment Claude décide ce qu’il retient, où il l’écrit, et quand il le relit), la distinction avec la mémoire conversationnelle de Claude.ai (un piège dans lequel tombent la plupart des articles anglophones), la hiérarchie de résolution des conflits entre les couches, un framework en six couches pour comprendre l’intégralité du contexte de Claude Code, les stratégies avancées (refactoring, drift, coût en tokens), et un case study session par session sur un projet réel.

Si vous avez déjà lu mon guide sur CLAUDE.md et celui sur les Skills, vous connaissez l’approche : on part de la doc officielle, on la dépasse, et on construit quelque chose d’actionnable. Et si vous cherchez un retour d’usage global sur les outils IA que j’utilise au quotidien — dont Claude Code —, c’est dans ma stack IA 2026 que ça se passe.

L’ère de l’amnésie est finie

Le paradoxe du contexte infini

Pendant des mois, utiliser Claude Code ressemblait à travailler avec un développeur brillant mais amnésique. Chaque matin, on recommençait. On réexpliquait la stack, les conventions, les pièges spécifiques au projet. Les 200 000 tokens de contexte ne changeaient rien au problème fondamental : la fenêtre de contexte, c’est de la mémoire de travail. Pas de la mémoire à long terme.

L’analogie la plus juste : vous pouvez tenir un livre entier dans vos mains, mais si vous posez le livre et que quelqu’un vous en donne un autre, le premier n’existe plus. 200k tokens, c’est la taille du livre. La mémoire persistante, c’est votre bibliothèque.

Un modèle capable de raisonner sur un roman entier en une seule passe, mais incapable de retenir que pnpm est obligatoire sur votre monorepo d’une session à l’autre — c’est exactement le paradoxe que vivait chaque utilisateur de Claude Code avant l’auto-memory. La fenêtre de contexte est vaste. Elle est aussi éphémère.

Le natif mange le communautaire

La communauté n’a pas attendu. Des projets comme claude-mem ont tenté de combler le vide — un plugin qui capture les actions de Claude pendant les sessions, les comprime via le SDK agent, et les réinjecte au démarrage suivant. Ingénieux. Mais du bricolage. Le genre de solution que vous maintenez jusqu’à ce que l’éditeur propose la vraie réponse.

La vraie réponse est arrivée début 2026. Anthropic a déployé l’auto-memory comme fonctionnalité native de Claude Code — un écosystème dont Anthropic a fait le fer de lance de sa stratégie. Activée par défaut. Pas un plugin, pas un hack, pas un flag expérimental — même si le code source portait encore la mention « research preview » dans les premières itérations. Claude prend des notes tout seul pendant qu’il travaille, et les recharge automatiquement au démarrage de chaque session.

La guerre entre le natif et le communautaire est terminée — et le natif a gagné. Pas parce que les solutions tierces étaient mauvaises, mais parce que l’intégration profonde dans le CLI change fondamentalement la donne. Un plugin qui injecte du contexte au démarrage, c’est un pansement. Un système qui observe, filtre et écrit pendant que l’agent travaille, intégré au même processus, c’est un organe. Et dans un monde où le vibe coding promet de tout simplifier, la mémoire persistante est ce qui sépare le bricolage de l’ingénierie.

Le Specification Driven Development

L’impact sur les projets longs est immédiat. On passe du prompt engineering — l’art de formuler la bonne question — au context engineering : l’art de construire l’environnement dans lequel l’agent opère. La mémoire n’est plus un problème à résoudre ; c’est un levier à optimiser. Et pour les développeurs qui se demandent si l’IA va les remplacer, la réponse est dans la nuance : elle remplace ceux qui ne font que taper du code, elle amplifie ceux qui savent piloter un agent.

C’est ce que j’appelle le Specification Driven Development (SDD) : un modèle de développement où la spécification n’est plus un document mort qu’on rédige et qu’on oublie, mais un organisme vivant qui s’enrichit à chaque session. CLAUDE.md pose les règles. MEMORY.md accumule l’expérience. Les hooks automatisent les réflexes. Et le tout forme un agent qui progresse. C’est exactement ce qu’Anthropic décrit dans ses best practices et, plus récemment, dans son guide sur le context engineering efficace — le passage du prompt ponctuel à l’environnement persistant.

Dans un workflow classique, le développeur écrit un cahier des charges, le transmet à l’équipe, et prie pour que l’implémentation corresponde. Avec un agent doté de mémoire, la spécification est le pilotage. Chaque session enrichit le contexte. Chaque correction affine le comportement. Le fossé entre « ce qu’on a demandé » et « ce qui a été livré » se réduit mécaniquement, session après session.

C’est aussi un renversement dans la valeur perçue du travail de configuration. Passer une heure à structurer un CLAUDE.md et à auditer un MEMORY.md, ça ne ferme aucun ticket Jira. Mais c’est le travail qui multiplie l’efficacité de toutes les heures suivantes. Dans un monde où l’IA est une commodité, le vrai avantage compétitif n’est plus l’accès au modèle — c’est la qualité du contexte que vous lui donnez. Les développeurs qui l’ont compris creusent l’écart. Les autres réexpliquent leurs conventions chaque matin.

Les deux mémoires : anatomie et contrôle

Avant d’aller plus loin, il faut démêler une confusion que je vois partout — y compris dans les articles anglophones bien référencés. Quand on parle de « mémoire de Claude », on parle en réalité de deux systèmes totalement distincts qui n’ont presque rien en commun.

Claude.ai Memory — le grand public

Si vous utilisez Claude via l’interface web ou mobile (claude.ai), vous avez accès à une mémoire conversationnelle dans les Settings. C’est le système userMemories. Claude extrait automatiquement des informations de vos conversations — votre métier, vos préférences, votre stack technique — et les stocke pour personnaliser les échanges futurs.

C’est pratique pour le grand public. Mais pour un développeur, les limites sont vite atteintes : extraction opaque (vous ne contrôlez pas ce qui est retenu ni comment c’est formulé), pas de versioning, pas d’édition granulaire, pas de lien avec un projet spécifique. Vous pouvez supprimer des entrées individuelles, mais vous ne pouvez ni les reformuler, ni les prioriser, ni les exporter. C’est une mémoire de chatbot — conçue pour que Claude se souvienne que vous codez en Python et que vous préférez les réponses concises, pas pour piloter un projet de 50 000 lignes.

D’après les release notes d’Anthropic, cette mémoire a d’abord été déployée pour les plans Max, puis progressivement étendue aux plans Pro. Si vous êtes sur un plan gratuit, vous n’y avez probablement pas accès au moment où vous lisez ces lignes.

Ce n’est pas le sujet de cet article. On le mentionne ici pour qu’il n’y ait aucune ambiguïté, puis on passe à autre chose. Tout ce qui suit concerne exclusivement Claude Code et son fichier MEMORY.md.

MEMORY.md dans Claude Code — le cœur du sujet

MEMORY.md est un fichier Markdown généré et maintenu par Claude Code lui-même, stocké localement dans ~/.claude/projects/<hash-du-projet>/memory/MEMORY.md. Il est injecté dans le system prompt au démarrage de chaque session. Claude le lit, s’en sert comme contexte, et le met à jour quand il découvre quelque chose qui mérite d’être retenu.

L’emplacement est dérivé du dépôt Git. Tous les worktrees et sous-répertoires d’un même dépôt partagent un même répertoire de mémoire. En dehors d’un dépôt Git, c’est le répertoire de travail qui sert de clé.

Voici les commandes essentielles :

# Vérifier si l'auto-memory est active sur votre projet
ls ~/.claude/projects/

# Ouvrir le gestionnaire de mémoire en session
/memory

# Activer/désactiver via les settings projet
# Dans .claude/settings.json :
{ "autoMemoryEnabled": true }

# Désactiver via variable d'environnement
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

# Compter les lignes de votre MEMORY.md
wc -l ~/.claude/projects/<hash>/memory/MEMORY.md
Langage du code : PHP (php)

La commande /memory dans une session active est le point d’entrée principal. Elle affiche la liste de tous les fichiers d’instructions chargés (CLAUDE.md, rules, mémoire), permet de basculer l’auto-memory on/off, et donne un lien direct pour ouvrir le dossier mémoire dans votre éditeur.

Le point crucial : c’est du Markdown brut. Pas une API, pas une base de données, pas un dashboard. Un fichier texte dans votre filesystem. grep pour chercher, wc -l pour compter, git diff pour tracer les changements si vous le versionnez, votre éditeur favori pour corriger. C’est volontairement low-tech — dans l’esprit de la philosophie Unix qui veut que chaque outil fasse une chose et la fasse bien. Et c’est exactement ce qui le rend puissant.

Comparaison factuelle — Q1 2026

Ce tableau n’est pas un jugement de valeur. Ce sont des faits datés, vérifiables. Deux approches pour deux publics différents. Mais si vous développez, la transparence d’un fichier Markdown que vous pouvez cat, grep et diff change fondamentalement la donne par rapport à un système dont vous ne pouvez que constater les effets.

Et AGENTS.md dans tout ça ?

Depuis mi-2025, le standard AGENTS.md émerge sous l’égide de la Agentic AI Foundation (Linux Foundation), soutenu par OpenAI, Google, Cursor, Sourcegraph et d’autres. Un seul fichier, lisible par Claude Code, Cursor, Copilot, Gemini CLI, Windsurf — l’idée est de découpler les instructions de l’outil.

J’ai détaillé la distinction CLAUDE.md vs AGENTS.md dans l’article précédent de cette série. En résumé : CLAUDE.md reste plus puissant pour les fonctionnalités spécifiques à Claude Code (hooks, rules, auto-memory, subagents). AGENTS.md est le choix pragmatique si votre équipe utilise plusieurs agents. Les deux fichiers coexistent dans le même dépôt sans conflit.

Mais AGENTS.md n’a pas d’équivalent à MEMORY.md. Aucun standard inter-plateforme ne gère la mémoire automatique. C’est un avantage compétitif net de l’écosystème Claude Code — et probablement la raison pour laquelle la communauté continue de construire des solutions de mémoire spécifiques plutôt que de converger vers un standard unique. On retrouve le même schéma que pour le web lui-même, où chaque plateforme bricole ses propres solutions pour rendre le contenu lisible par les agents, faute de standard universel.

La trinité des systèmes

La mémoire de Claude Code ne repose pas sur un seul mécanisme. C’est un système à trois couches, chacune avec sa logique, sa persistance et sa priorité.

Système 1 — Manual Memory : CLAUDE.md

C’est la constitution du projet. Vous l’écrivez, vous la maintenez, vous la versionnez avec Git. CLAUDE.md est chargé intégralement au démarrage de chaque session. J’ai consacré un article de 7 000 mots à ce système, avec la mécanique d’injection (spoiler : ce n’est pas dans le system prompt), la hiérarchie des six niveaux, et les patterns d’architecture. Je ne reviens pas dessus ici.

Le seul point à retenir pour la suite : CLAUDE.md a la priorité la plus haute dans la résolution des conflits avec l’auto-memory. C’est la couche de commandement. Les règles immuables, les conventions, les interdictions.

Système 2 — Auto Memory : MEMORY.md

C’est le journal de bord autonome. Claude y écrit ce qu’il apprend en travaillant : commandes de build, insights de débogage, notes d’architecture, préférences de style, habitudes de workflow.

La limite des 200 lignes. C’est un hard limit codé en dur dans le bundle CLI. Giuseppe Gurgone, développeur et blogueur technique, l’a trouvé verbatim dans le code source minifié : var U_ = "MEMORY.md", pZ = 200. Au-delà de 200 lignes, Claude n’injecte que les 200 premières et affiche un avertissement :

WARNING: MEMORY.md is N lines (limit: 200). Only the first 200 lines
were loaded. Move detailed content into separate topic files and keep
MEMORY.md as a concise index.
Langage du code : CSS (css)

Le système pousse vers un pattern « index + fichiers thématiques ». MEMORY.md reste un index concis. Les détails vont dans des fichiers satellites — debugging.md, patterns.md, architecture.md — dans le même répertoire. Ces fichiers ne sont pas chargés au démarrage. Claude les consulte à la demande, via ses outils de lecture de fichiers, quand il estime avoir besoin de l’information. C’est du just-in-time context — le même pattern que celui documenté par Anthropic pour le Memory Tool de l’API.

Concrètement, l’arborescence de la mémoire d’un projet mature ressemble à ça :

~/.claude/projects/<hash>/memory/
├── MEMORY.md           ← Index, 200 lignes max, chargé au démarrage
├── debugging.md        ← Solutions aux problèmes récurrents
├── patterns.md         ← Conventions de code observées
├── architecture.md     ← Cartographie des modules et dépendances
└── deployment.md       ← Procédures et conditions de succès
Langage du code : Markdown (markdown)

Claude maintient MEMORY.md comme table des matières et y référence les fichiers satellites. Quand il a besoin d’une information détaillée — par exemple, la solution à un bug CORS qu’il a déjà résolu trois semaines plus tôt — il ouvre le fichier satellite correspondant, lit la section pertinente, et poursuit. L’information est disponible sans polluer le budget de tokens de démarrage.

Ce mécanisme de chargement à la demande est encore derrière un feature flag sur certaines versions (tengu_coral_fern dans le code source). Si vos fichiers satellites ne semblent pas consultés, vérifiez que vous êtes sur une version récente de Claude Code.

En termes de tokens, un MEMORY.md rempli à sa capacité maximale consomme environ 1 500 tokens — soit environ 1,5% de la fenêtre de contexte. Un coût négligeable pour un gain considérable. Si la mécanique des tokens et de la troncature vous intéresse, j’ai consacré un article entier à la façon dont les IA gèrent — et dégradent — le contexte qu’on leur fournit.

Claude ne sauvegarde pas quelque chose à chaque session. Il évalue si l’information sera utile dans une future conversation. C’est la différence entre un fait isolé et un pattern systémique. Seuls les patterns méritent la mémoire. Plus sur ce mécanisme dans la section « Cycle de réflexion » ci-dessous.

Vous pouvez aussi forcer une mémorisation explicite :

> remember that we use pnpm, not npm
> save to memory that the API tests require a local Redis instance
> note that the staging environment uses port 3001
Langage du code : JavaScript (javascript)

Claude écrit immédiatement dans le fichier mémoire approprié. Pour écrire dans CLAUDE.md plutôt que dans la mémoire automatique, demandez-le explicitement : add this to CLAUDE.md.

Système 3 — Agent Memory

Depuis début 2026, les subagents de Claude Code disposent de leur propre mémoire persistante. C’est la troisième couche, et elle résout un problème fondamental : l’isolation des contextes.

Quand vous créez un subagent — via /agents ou en ajoutant un fichier .md dans .claude/agents/ — vous pouvez lui attribuer un scope mémoire dans le frontmatter YAML :

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
memory: user
---
You are a code reviewer. As you review code, update your
agent memory with patterns, conventions, and recurring
issues you discover.
Langage du code : YAML (yaml)

Trois scopes existent :

• project : stocké dans .claude/agent-memory/<nom>/. Committable dans Git, partageable avec l’équipe. C’est le scope le plus intéressant pour l’institutionnalisation des connaissances.
• local : stocké dans ~/.claude/agent-memory-local/<nom>/. Local à votre machine. Pour les préférences personnelles d’un agent.
• user : stocké dans ~/.claude/agent-memory/<nom>/. Global, disponible dans tous vos projets. Pour un agent qui vous suit partout.

Chaque subagent accumule sa propre base de connaissances sans polluer la mémoire du thread principal. Un reviewer apprend les patterns de code récurrents. Un debugger retient les solutions aux problèmes déjà rencontrés. Un architecte cartographie les dépendances.

Le point clé : seule la mémoire d’agent en scope project est partageable (via Git). La mémoire du thread principal (MEMORY.md) reste locale à la machine. C’est la limitation actuelle la plus significative du système — et probablement la prochaine à tomber.

Le conflit de mémoire : qui gagne ?

Quand CLAUDE.md dit « utilise toujours des tabs » et qu’un apprentissage récent dans MEMORY.md note « le projet utilise des spaces », qui a raison ?

La hiérarchie est claire :

CLAUDE.md projet > CLAUDE.md utilisateur > Auto-memory (MEMORY.md)

L’auto-memory complète sans jamais écraser. Si un conflit existe entre deux CLAUDE.md (projet et utilisateur), le plus spécifique l’emporte. Les managed policies d’organisation (Enterprise policy), quand elles existent, ne peuvent pas être exclues — elles s’appliquent quoi qu’il arrive, même si votre CLAUDE.md tente de les contredire.

En pratique, les conflits viennent rarement d’une contradiction frontale. Ils viennent d’instructions ambiguës dans CLAUDE.md qui laissent une marge d’interprétation que la mémoire automatique remplit à sa façon. Un cas vicieux : CLAUDE.md dit « utilise des named imports ». Claude le respecte. Mais après plusieurs sessions où vous importez manuellement un module spécifique en default import (parce que la lib l’impose), MEMORY.md note « pour la lib X, utiliser le default import ». Ce n’est pas un conflit — c’est une nuance contextuelle. Et c’est exactement le type de subtilité que la mémoire capture bien, à condition que CLAUDE.md soit suffisamment clair sur ce qui est une règle absolue versus une préférence.

La solution : être explicite dans CLAUDE.md, et auditer régulièrement MEMORY.md.

Le cycle de réflexion : ce que Claude choisit de retenir

Comment Claude décide-t-il qu’une information mérite d’être mémorisée ? Ce n’est pas un enregistrement brut de tout ce qui se passe dans la session. C’est un processus de filtrage basé sur la valeur future estimée.

Claude observe les corrections que vous apportez. S’il propose du code avec npm et que vous corrigez en pnpm trois fois de suite, ce n’est plus un incident — c’est un pattern. Le pattern est candidat à la mémorisation. Une correction unique sur un cas edge ne l’est pas.

Le même mécanisme s’applique aux insights de débogage. Si Claude passe 15 minutes à diagnostiquer un problème de CORS lié à une configuration spécifique de votre reverse proxy, la solution et le contexte méritent d’être retenus. Si vous corrigez une coquille dans un nom de variable, non.

La documentation officielle le formule ainsi : Claude « décide ce qui vaut la peine d’être retenu en fonction de si l’information serait utile dans une future conversation ». C’est un système probabiliste, pas déterministe. Il arrive que Claude mémorise des choses inutiles ou rate des patterns importants. D’où l’intérêt de la commande explicite remember that... pour forcer les entrées critiques, et de l’audit régulier pour nettoyer les entrées parasites.

Le Memory Hook : automatiser la mise à jour

Si vous avez lu l’article sur les Hooks, vous savez qu’on peut scripter des actions déclenchées par les événements de Claude Code. L’idée du Memory Hook est simple : forcer une mise à jour mémoire après un événement significatif.

Exemple concret : après un déploiement réussi, un hook PostToolUse détecte la commande de déploiement et déclenche un résumé des conditions de succès. La prochaine fois qu’un déploiement est demandé, Claude part avec le contexte complet du dernier succès.

Voici un exemple fonctionnel. Le hook se configure dans votre .claude/settings.json :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/memory-on-deploy.sh"
          }
        ]
      }
    ]
  }
}
Langage du code : JSON / JSON avec commentaires (json)

Et le script .claude/hooks/memory-on-deploy.sh :

#!/usr/bin/env bash
# Memory Hook : capture le contexte d'un déploiement réussi
# Déclenché par PostToolUse sur les commandes Bash

set -euo pipefail

# Lire le payload JSON de Claude Code sur stdin
INPUT=$(cat)

# Extraire la commande exécutée et son exit code
TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
EXIT_CODE=$(echo "$INPUT" | jq -r '.tool_result.exit_code // empty')

# Ne réagir que sur les commandes de déploiement réussies
if [[ "$TOOL_INPUT" == *"deploy"* ]] && [[ "$EXIT_CODE" == "0" ]]; then

  MEMORY_DIR="$HOME/.claude/projects/$(pwd | md5sum | cut -d' ' -f1)/memory"
  DEPLOY_LOG="$MEMORY_DIR/deployments.md"
  TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

  mkdir -p "$MEMORY_DIR"

  # Ajouter l'entrée au fichier satellite (pas au MEMORY.md principal)
  cat >> "$DEPLOY_LOG" << EOF

## Deploy $TIMESTAMP
- Command: $TOOL_INPUT
- Branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
- Commit: $(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
- Status: SUCCESS
EOF

  echo "memory-on-deploy: logged to $DEPLOY_LOG" >&2
fi

# Toujours sortir en succès pour ne pas bloquer Claude
exit 0
Langage du code : Shell Session (shell)

Quelques points importants sur ce script. Le hook écrit dans un fichier satellite (deployments.md), pas dans MEMORY.md directement — on ne veut pas polluer l’index principal avec des logs de déploiement. Claude consultera ce fichier à la demande quand il aura besoin du contexte. Le jq est nécessaire pour parser le payload JSON que Claude Code envoie sur stdin. Et le exit 0 final est critique : un hook qui échoue bloque l’agent.

Un autre hook utile : InstructionsLoaded, ajouté dans les dernières releases. Il se déclenche quand les fichiers CLAUDE.md ou .claude/rules/*.md sont chargés en contexte. L’événement inclut désormais agent_id et agent_type pour les subagents. C’est l’outil de diagnostic par excellence : loguer exactement quelles instructions sont actives, quand elles se chargent, et pourquoi — indispensable pour déboguer un comportement inattendu lié à un conflit entre couches de mémoire.

Intégration IDE : la mémoire visible

Dans VS Code avec l’extension Claude Code, la mémoire n’est pas cachée dans un terminal. Les sessions apparaissent dans la barre d’activité via une icône dédiée, les plans sont rendus en Markdown avec possibilité d’ajouter des commentaires inline, et la compaction est affichée comme une carte repliable avec le résumé à l’intérieur.

Côté terminal pur, /memory reste le point d’entrée. Mais vous avez aussi /compact qui déclenche manuellement la compaction (Claude relit CLAUDE.md depuis le disque, résume la conversation, et reprend — la mémoire auto survit intégralement), et /cost pour surveiller la consommation de tokens en temps réel.

La pyramide des 6 couches du contexte

Voici le framework qui synthétise tout ce qu’on a vu dans cette série — les quatre articles. Six couches, de la plus permanente à la plus éphémère, qui constituent l’intégralité du contexte dont dispose Claude Code à un instant donné.

Couche 1 — Identité

Le fichier ~/.claude/CLAUDE.md. Vos préférences globales : langue de réponse, style de code, conventions universelles. S’applique à tous les projets, tout le temps. C’est votre empreinte.

Ce fichier ne devrait pas dépasser 100 lignes. C’est le socle commun — les choses qui sont vraies quel que soit le projet. Si une règle est spécifique à un dépôt, elle n’a rien à faire ici.

Couche 2 — Projet

Le CLAUDE.md racine du dépôt plus les fichiers dans .claude/rules/. Framework, commandes de build, architecture, interdictions. Versionné avec Git, partagé avec l’équipe. C’est le règlement intérieur.

Les rules modulaires — des fichiers .md dans .claude/rules/ qui se chargent conditionnellement via des globs — sont la solution quand CLAUDE.md grossit trop. Un fichier typescript.md se charge quand Claude travaille sur un .ts. Un fichier testing.md se charge dans le contexte des fichiers de test. Le chargement est paresseux : seules les règles pertinentes au fichier en cours sont injectées.

Couche 3 — Expérience

MEMORY.md et ses fichiers satellites. L’auto-memory. Persistance cross-sessions, local à la machine. C’est la mémoire institutionnelle — sauf qu’elle est individuelle pour le moment.

Détail important : les fichiers satellites (debugging.md, patterns.md) ne sont pas chargés au démarrage. Seul MEMORY.md (200 premières lignes) est injecté dans le system prompt. Les satellites sont consultés à la demande. C’est du just-in-time context.

Couche 4 — Éphémère

L’historique de la session en cours. Messages, résultats d’outils, décisions prises dans la conversation active. Élagué dynamiquement par la compaction quand le contexte approche ses limites.

Après un /compact, Claude relit CLAUDE.md depuis le disque et le réinjecte dans la session. Mais les instructions données uniquement à l’oral dans la conversation sont perdues — sauf si elles ont été captées par l’auto-memory. C’est pourquoi toute règle importante doit finir dans CLAUDE.md ou MEMORY.md — pas dans un message de chat. Si une instruction disparaît après compaction, c’est le signe qu’elle n’a jamais été écrite dans un fichier persistant.

C’est aussi la couche la plus coûteuse en tokens. Sur un projet complexe avec beaucoup d’allers-retours et de résultats d’outils volumineux (diffs, outputs de build, stacktraces), l’historique de session peut consommer la quasi-totalité de la fenêtre de contexte. La mémoire persistante (couches 1-3) est précisément ce qui permet de réduire cette pression : moins de réexplication → moins de tokens éphémères → plus de place pour le travail réel.

Un point souvent négligé : la compaction et la mémoire coexistent mais ne font pas la même chose. La compaction résume la conversation côté serveur pour rester dans la fenêtre de contexte. La mémoire persiste des informations structurées côté client pour les retrouver entre sessions. Pour les workflows longs, Anthropic recommande d’utiliser les deux : la compaction garde le contexte actif gérable, la mémoire garantit que rien de critique n’est perdu dans le résumé.

Couche 5 — Outils & Hooks

L’état des serveurs MCP connectés et des triggers actifs. Les skills chargées, les hooks PreToolUse et PostToolUse. C’est l’outillage disponible à l’instant T.

Couche 6 — Sécurité & Scope

Les managed policies d’organisation, les permission modes des subagents, les restrictions d’outils. C’est le périmètre dans lequel tout le reste opère. Non excluable, non contournable.

Vue d’ensemble

L’ensemble des couches 1 à 3 plus les couches système consomme typiquement moins de 5 000 tokens au démarrage. Sur une fenêtre de 200 000 tokens, c’est 2,5%. Le ratio signal/coût est excellent.

Ce framework n’est pas qu’un schéma théorique. C’est une grille de diagnostic. Quand Claude se comporte bizarrement, posez-vous la question : quelle couche est en cause ? Un conflit entre couche 2 et 3 ? Une instruction manquante en couche 1 ? Un hook défaillant en couche 5 ? La réponse oriente immédiatement l’action corrective.

Stratégies avancées et limites

Mémoire vs MCP : quand externaliser

MEMORY.md est parfait pour les connaissances légères et les patterns de travail. Mais il y a des cas où un fichier Markdown de 200 lignes ne suffit plus :

• Quand le volume de données dépasse ce que le format index + satellites peut absorber — un projet avec des centaines de modules, des dizaines de services, des dépendances complexes entre composants.
• Quand plusieurs développeurs doivent partager une base de connaissances commune en temps réel, au-delà de ce que le scope project des subagents permet.
• Quand vous avez besoin de recherche sémantique plutôt que de chargement séquentiel — « quels fichiers sont liés à la fonctionnalité de paiement ? » plutôt que de parcourir un index linéaire.

Dans ces cas, un serveur MCP avec une base vectorielle (ou même un simple SQLite avec embeddings) prend le relais. La mémoire locale reste pour les réflexes du quotidien ; le MCP sert de mémoire étendue interrogeable à la demande. C’est d’ailleurs le pattern recommandé par Anthropic dans leur documentation sur le Memory Tool — ils parlent de « just-in-time context retrieval » comme primitive fondamentale pour les agents long-running. Attention toutefois au semantic collapse si votre base vectorielle grossit significativement — un phénomène où la pertinence des résultats se dégrade à grande échelle. Si le sujet du retrieval vous intéresse plus largement, j’ai consacré un guide complet au RAG qui couvre le pipeline de bout en bout.

Le critère de décision est simple : si l’information tient en une ligne et s’applique à toutes les sessions → MEMORY.md. Si elle nécessite du contexte, de la recherche ou du filtrage → MCP.

Le Memory Drift : la dérive silencieuse

C’est le piège que personne ne mentionne dans les tutoriels enthousiastes. Après des dizaines de sessions, MEMORY.md accumule des observations qui ne sont plus pertinentes, voire des « mauvais plis » — des patterns que Claude a inférés à tort et qui polluent ses futures décisions.

Exemple 1 : Claude note que vous utilisez console.log pour déboguer. Après quelques sessions, il commence à saupoudrer des console.log dans le code de production. Ce n’était pas une convention, c’était un contexte ponctuel. Mais la mémoire ne fait pas la différence.

Exemple 2 : Claude observe que vous importez souvent lodash dans un module spécifique. Il généralise et commence à l’importer partout, y compris dans des fichiers où il n’a rien à faire. L’observation était correcte localement, la généralisation est fausse.

Le drift est d’autant plus insidieux qu’il est progressif. Vous ne le remarquez pas à la session 5. À la session 15, vous vous demandez pourquoi Claude a pris cette habitude. À la session 25, vous avez oublié que ce n’était pas voulu.

La solution : l’audit régulier. Ouvrez votre MEMORY.md toutes les deux semaines. Supprimez les observations obsolètes. Reformulez les patterns vagues. Un bon réflexe : quand vous détectez un comportement non désiré, cherchez d’abord dans MEMORY.md avant de corriger à l’oral. Si l’entrée fautive est là, supprimez-la. Sinon, ajoutez une négation explicite. Les règles négatives sont aussi puissantes que les règles positives dans ce système.

Curation et refactoring

Quand MEMORY.md approche des 200 lignes, c’est le moment de refactorer. Le système encourage déjà cette pratique en déportant les détails dans des fichiers thématiques. Mais la vraie curation va plus loin.

Regroupez les entrées redondantes. Trois observations sur « le projet utilise PostgreSQL » deviennent une seule ligne. Remontez les patterns les plus critiques en haut du fichier — Claude Code lit le fichier séquentiellement et accorde plus de poids aux premières lignes (c’est le même phénomène de « fading memory » que j’ai documenté pour CLAUDE.md). Supprimez les observations contextuelles qui ne se généralisent pas.

Voici un avant/après de curation pour illustrer la différence :

Avant (extrait, 18 lignes pour 4 concepts) :

- The project uses PostgreSQL as the database
- PostgreSQL version is 16
- Database is PostgreSQL, accessed via Prisma
- When writing tests, put them in tests/unit/ for unit tests
- Integration tests go in tests/integration/
- Tests should always be in the right folder
- The team uses pnpm for package management
- Never use npm, always pnpm
- pnpm is the package manager for this project
- Saw that console.log was used for debugging the auth flow
- Fixed a Redis timeout by increasing the TTL to 3600
- The staging URL is https://staging.example.com
- Linting errors appeared when using double quotes in PHP
- Use single quotes in PHP, double quotes in Twig templates
- The CI pipeline runs on GitHub Actions
- Build is triggered by push to main
- PR reviews require 2 approvals
- The deploy script is in scripts/deploy.sh
Langage du code : JavaScript (javascript)

Après (8 lignes pour les mêmes concepts + plus) :

# Build & Tooling
- Package manager: pnpm only, never npm or yarn
- Build/test: make build, make test-unit, make test-integration
- CI: GitHub Actions, triggered on push to main, 2 PR approvals required
- Deploy: scripts/deploy.sh

# Code Conventions
- PHP: single quotes. Twig templates: double quotes
- Tests: /tests/unit/ and /tests/integration/, never at root /tests/
- DB: PostgreSQL 16 via Prisma, always use QueryBuilder
Langage du code : PHP (php)

De 18 lignes à 8. Même information, plus quelques ajouts. Le gain en densité signal/bruit est considérable — et il se traduit directement en meilleure adhérence.

La dette de mémoire : un coût caché qui mérite d’être nommé

Soyons honnêtes : cet audit bimensuel que je recommande, c’est du travail. Du travail qui ne livre aucune fonctionnalité, ne ferme aucun ticket, et n’apparaît dans aucun sprint review. C’est une nouvelle forme de dette technique — la dette de mémoire. Comme la dette de documentation ou la dette de tests, elle s’accumule silencieusement et se paie plus tard sous forme de dérive comportementale de l’agent.

Le parallèle avec le code est frappant. Personne ne conteste qu’il faut refactorer du code régulièrement. Mais personne ne planifie non plus de « sprint de refactoring mémoire ». Le résultat : des MEMORY.md de 200 lignes pleins de bruit qui dégradent les réponses de Claude sans que personne ne comprenne pourquoi.

La vraie question est : pourrait-on automatiser cette curation ? En théorie, rien n’empêche de créer un subagent dédié — un memory-curator avec un scope mémoire project — dont le seul rôle serait d’analyser périodiquement le MEMORY.md du thread principal, d’identifier les doublons, de détecter les observations obsolètes, et de proposer une version nettoyée. Un linter de mémoire, en quelque sorte.

---
name: memory-curator
description: Audits and curates MEMORY.md files
tools: Read, Write, Edit, Glob, Grep
model: haiku
memory: project
---
You are a memory curator. When invoked, analyze the project's
MEMORY.md for: duplicates, stale observations, contradictions
with CLAUDE.md, entries beyond 200 lines. Propose a curated
version. Never delete without confirmation.

Aujourd’hui, ce subagent ne peut pas écrire dans le MEMORY.md du thread principal (isolation des contextes oblige). Mais la direction est claire : la mémoire partagée entre agents est la prochaine frontière d’Anthropic, et quand elle arrivera, l’auto-curation deviendra un workflow standard. En attendant, le subagent peut au moins analyser et proposer — la validation humaine reste dans la boucle.

L’aspect financier : le vrai coût en tokens

Chaque token de mémoire injecté au démarrage est un token facturé à chaque message. Sur un projet long avec des dizaines d’échanges par jour, un MEMORY.md obèse coûte.

Calcul : 1 500 tokens de mémoire × 100 messages/jour × 30 jours = 4,5 millions de tokens d’input supplémentaires par mois. Au tarif Sonnet (~3$/MTok en input), c’est ~13,50$ mensuels. Pas ruineux. Mais ajoutez les CLAUDE.md (projet + utilisateur), les rules modulaires, les descriptions de serveurs MCP — on atteint facilement 5 000-10 000 tokens de contexte persistant. Et sur Opus, le multiplicateur change la donne.

D’où la règle : chaque ligne doit justifier sa présence par son impact sur la qualité des réponses. Un MEMORY.md de 200 lignes rempli de banalités coûte autant qu’un MEMORY.md de 50 lignes parfaitement ciblé — mais le second produit de meilleurs résultats. Le coût optimal est celui où chaque token de mémoire économise plus de tokens de correction en aval.

Étude de cas : 10 sessions de Memory Training

Voici ce qui se passe concrètement quand on laisse la mémoire faire son travail sur un vrai projet. L’exemple vient du développement de Motorsport-Passion, un projet PHP/MySQL avec des années d’historique et ses propres conventions.

Session 1 — Le point zéro. Claude Code ne sait rien. Il propose npm install sur un projet PHP. Il génère des fichiers avec des conventions PSR-12 alors que le projet a son propre style. Il cherche les tests dans tests/ alors qu’ils sont dans un répertoire dédié avec une structure spécifique. Chaque interaction commence par « Non, pas comme ça ». Le MEMORY.md est vide. Temps passé en corrections : environ 50% de la session.

Sessions 2-3 — Les premières corrections. On martèle les fondamentaux. « Le build, c’est make build, pas npm run build. » « Les tests d’intégration sont dans /tests/integration/, les unitaires dans /tests/unit/. » « Les migrations suivent le format YYYYMMDD_description.sql. » Claude commence à noter. Le MEMORY.md affiche ses premières lignes :

- Project uses make for build commands, not npm
- Integration tests in /tests/integration/, unit tests in /tests/unit/
- Migration files follow YYYYMMDD_description.sql format
- Never use default exports
Langage du code : JavaScript (javascript)

Rudimentaire. 15 lignes. Mais les erreurs les plus grossières disparaissent déjà à la session suivante.

Sessions 4-5 — L’émergence des patterns. Les bases sont acquises. Claude ne se trompe plus sur les commandes de build. Il commence à capturer des choses plus fines : le style des messages de commit (conventionnel, en anglais), la structure des fichiers de configuration, le fait que les variables d’environnement de développement vivent dans .env.local et pas .env. Plus intéressant : il note des patterns architecturaux que j’ai pas explicitement enseignés. « Les requêtes SQL passent par le QueryBuilder, jamais de requêtes brutes. » Il a inféré ça en lisant le code existant. La mémoire dépasse le mode réactif pour devenir proactive. 60 lignes. Temps de correction : ~20% de la session.

Sessions 6-7 — Le premier refactoring. Le fichier montre ses limites. Trois entrées différentes mentionnent PostgreSQL sous des angles différents. Deux observations sur le style de code se contredisent partiellement — l’une note les single quotes, l’autre les double quotes, alors que la règle est single quotes pour PHP et double pour les templates Twig. C’est le moment du premier nettoyage. J’ouvre MEMORY.md, je consolide les doublons, je supprime les observations trop contextuelles (« le bug #347 était lié à un timeout Redis » — utile une fois, jamais deux), je reformule les patterns vagues en instructions claires. Descente de 60 à 45 lignes. La qualité des réponses de Claude s’améliore visiblement après ce nettoyage — preuve que la concision et la clarté comptent autant que le volume.

Sessions 8-9 — L’autonomie. Le changement qualitatif. Claude propose des solutions qui non seulement respectent les conventions, mais anticipent les contraintes du projet. Il sait que le système de templates a un cache qu’il faut invalider après modification. Il sait que les routes API suivent un pattern REST strict avec des middleware de validation. Il suggère des structures de code cohérentes avec l’existant sans qu’on le guide. Exemple concret : je lui demande d’ajouter une fonctionnalité de notification. Il crée le fichier dans le bon répertoire, utilise le bon namespace, injecte les bonnes dépendances, et ajoute le test dans le bon dossier avec le bon naming. Six semaines plus tôt, chacun de ces choix aurait nécessité une correction. Les corrections portent sur des décisions d’architecture, plus sur des conventions.

Session 10 — Le bilan. MEMORY.md fait 80 lignes. Propres, structurées par thèmes. Le temps de mise en contexte au démarrage est passé de 10-15 minutes de réexplication à zéro. Gain estimé : 30-40% de réduction du temps passé en corrections et réexplications. Ce n’est pas scientifique, c’est un ressenti de praticien. Mais c’est suffisamment significatif pour que la mémoire soit devenue le premier système que je configure sur tout nouveau projet.

La leçon : la mémoire ne se « configure » pas une fois pour toutes. Elle se cultive. On plante les bases, on laisse pousser, on taille régulièrement, et on récolte un agent qui s’améliore continuellement.

Dépannage

« Claude ignore ce qu’il a dans sa mémoire »

Vérifiez d’abord que l’auto-memory est activée : /memory en session. Si le toggle est off, rien n’est chargé. Ensuite, comptez les lignes : wc -l sur votre MEMORY.md. Au-delà de 200, seul le début est injecté. Vérifiez que l’information critique n’est pas reléguée en ligne 180.

« MEMORY.md grossit trop vite »

Claude note parfois des observations trop granulaires. Deux options : (1) curez régulièrement en supprimant les observations ponctuelles, (2) déplacez les détails dans des fichiers thématiques et gardez MEMORY.md comme index. Claude fera le lien.

« La mémoire contient des erreurs »

C’est normal — c’est du Memory Drift. Ouvrez le fichier, corrigez ou supprimez. C’est du Markdown, pas une base de données protégée. Un grep -n "pattern" MEMORY.md identifie vite les entrées problématiques.

« L’auto-memory ne se déclenche pas »

Vérifiez la variable d’environnement CLAUDE_CODE_DISABLE_AUTO_MEMORY. Si elle est à 1, la mémoire est désactivée. Vérifiez aussi que le répertoire ~/.claude/projects/ existe et est accessible en écriture. Si vous travaillez dans un conteneur ou un environnement sandboxé, le chemin peut être monté en read-only.

« Mon subagent ne retient rien entre les sessions »

Le champ memory doit être explicite dans le frontmatter du subagent. Sans lui, pas de mémoire persistante. Et vérifiez le scope : local et user sont machine-specific, project est dans le dépôt.

« Conflit entre CLAUDE.md et MEMORY.md »

Identifiez l’instruction conflictuelle dans chaque fichier. La règle est : CLAUDE.md gagne toujours. Si le comportement observé contredit CLAUDE.md, l’entrée de MEMORY.md crée de l’ambiguïté — supprimez-la. Si c’est une nuance légitime (cas spécial d’une règle générale), reformulez les deux pour lever l’ambiguïté.

Checklist

Avant de commencer

• [ ] L’auto-memory est activée (/memory → toggle ON)
• [ ] Le répertoire ~/.claude/projects/<votre-projet>/memory/ existe
• [ ] Votre CLAUDE.md est en place et à jour (les deux systèmes sont complémentaires)

En cours de projet

• [ ] Vérifier wc -l MEMORY.md régulièrement (objectif : < 150 lignes pour garder de la marge)
• [ ] Forcer la mémorisation des décisions critiques avec remember that...
• [ ] Après un déploiement ou une résolution de bug majeur, demander à Claude de mettre à jour sa mémoire

Audit bimensuel

• [ ] Ouvrir MEMORY.md dans un éditeur
• [ ] Supprimer les observations obsolètes ou trop contextuelles
• [ ] Consolider les doublons
• [ ] Remonter les patterns critiques en haut du fichier
• [ ] Vérifier l’absence de drift (observations devenues fausses)
• [ ] Si > 200 lignes : refactorer en index + fichiers satellites

Signaux d’alerte

• [ ] Claude répète une erreur que vous avez corrigée → l’auto-memory n’a pas capté ou l’entrée a été éjectée au-delà de la ligne 200
• [ ] Claude adopte un comportement non désiré de façon systématique → drift, chercher dans MEMORY.md
• [ ] Les réponses sont de moins en moins pertinentes au fil des sessions → probable obésité du fichier, curer

Le mot de la fin

MEMORY.md est le mécanisme qui fait passer Claude Code du statut d’outil à celui de collaborateur. Un outil, on le configure. Un collaborateur, on le forme. Et la formation passe par la mémoire — manuelle (CLAUDE.md), automatique (MEMORY.md), et bientôt collective (Agent Memory en scope project).

La direction est claire. Aujourd’hui, la mémoire de Claude Code est locale par machine. Un développeur qui change de poste repart de zéro. Une équipe ne peut pas mutualiser les apprentissages du thread principal. C’est la limitation actuelle la plus criante — et les briques pour la lever sont déjà en place. Les configs projet et l’auto-memory sont partagées entre les worktrees d’un même dépôt Git. L’API propose un Memory Tool côté serveur avec les mêmes principes. Quand ces deux mondes fusionneront, l’agent ne sera plus individuel. Il sera institutionnel.

L’éthique suit. Un fichier qui retient tout ce que vous faites, décidez et préférez dans votre travail, ça pose des questions — d’autant plus que les LLM eux-mêmes sont des surfaces d’attaque et que le contenu de votre MEMORY.md pourrait être exfiltré via une injection de prompt bien placée. MEMORY.md est local — c’est un choix de design qu’il faut saluer. Pas de cloud par défaut, pas de partage involontaire. Mais la question se reposera avec la mémoire partagée. Où s’arrête la mémoire utile, où commence la surveillance ? Un agent qui retient que vous refactorez trois fois avant de merger et que vous testez rarement les cas edge — ce sont des observations factuelles. Agrégées, elles dessinent un profil. La réponse sera dans la transparence : un fichier Markdown éditable, où chaque entrée est visible et supprimable, sera toujours préférable à une boîte noire.

Cet article s’inscrit dans une série sur les mécanismes fondamentaux de Claude Code : CLAUDE.md pour les instructions persistantes, SKILL.md pour les workflows réutilisables, les Hooks pour l’automatisation, et maintenant MEMORY.md pour l’apprentissage continu. Les quatre ensemble forment le socle du context engineering — l’art de construire l’environnement dans lequel un agent produit systématiquement de bonnes réponses.

Mais l’écosystème Claude Code ne s’arrête pas là. L’arrivée des plugins et des marketplaces — y compris le répertoire officiel d’Anthropic — ouvre un nouveau chapitre : des extensions installables, distribuables et combinables, qui embarquent leurs propres skills, hooks, serveurs MCP et agents. Le modèle de distribution change. On passe de « je configure mon agent » à « j’installe les briques qui correspondent à mon workflow ». Côté plateforme, Cowork étend le paradigme aux non-développeurs avec des tâches récurrentes planifiées, des connecteurs enterprise et des agents département par département. Et la Claude Platform Marketplace laisse entrevoir un écosystème où les skills, plugins et connecteurs circulent entre équipes et organisations.

Ces sujets mériteront leurs propres articles quand l’écosystème sera suffisamment mûr. En attendant, ouvrez votre MEMORY.md. Lisez-le. Curez-le. Et regardez votre agent progresser.

Ressources

• Documentation officielle — Memory (Claude Code)
• Documentation officielle — Subagents & Agent Memory
• Memory Tool (API Claude)
• Plugin Marketplaces (Claude Code)
• Plugin Directory officiel Anthropic (GitHub)
• Giuseppe Gurgone — Claude Code’s Experimental Memory System
• Mon article — CLAUDE.md : le guide complet
• Mon article — SKILL.md : le guide complet
• Mon article — Les Hooks Claude Code
• Mon article — RAG : le guide complet