La mémoire de Claude Code

Problème : Chaque nouvelle session démarre à zéro. Tu retapes le même contexte. Framework, conventions, focus actuel, organisation des fichiers. L'agent n'a aucun souvenir d'hier.

Victoire rapide : Crée le fichier mémoire en 30 secondes :

cd your-project
claude
/init

Claude lit ton dépôt et génère un CLAUDE.md de démarrage à côté. Ce fichier devient le contexte permanent du projet, chargé en tête de chaque future session.

Ce qu'est vraiment CLAUDE.md

Le fichier mémoire s'appelle CLAUDE.md. Il vit sur le disque, donc il survit à tout. L'historique du chat meurt quand la session se termine. Ce fichier, non. Claude le lit au démarrage et le traite comme faisant autorité.

Voilà le point important. Le texte dans CLAUDE.md obtient un slot haute priorité dans la fenêtre de contexte. Claude le suit plus strictement que les messages du chat et plus strictement que les fichiers qu'il récupère en cours de session. Traite-le comme de la config, pas comme de la doc.

Cet écart de priorité façonne comment tu structures tout le reste. La hiérarchie de priorité l'explique en détail.

Structure le fichier pour la rétention

Divise le fichier en deux moitiés. Ce qui ne change jamais en haut. Ce qui bouge en bas.

# Project Context
 
- Framework: Next.js 14 with App Router
- Database: Supabase with Row Level Security
- Testing: Vitest for unit tests
 
## Key Directories
 
- `src/app/` - Route handlers and pages
- `src/lib/` - Shared utilities
- `src/components/` - React components
 
## Standards
 
- TypeScript strict mode required
- All API routes need error handling
- Run `npm test` before committing
 
## Current Focus
 
- Building user authentication flow
- Priority: Login and password reset

Le bloc Current Focus est ton brouillon. Écrase-le tous les quelques jours. Laisse le reste tranquille.

Mémoire hiérarchique dans l'arborescence

Les fichiers CLAUDE.md s'emboîtent. Claude remonte l'arborescence de répertoires et charge chacun qu'il trouve :

~/projects/CLAUDE.md          <- Universal defaults
~/projects/my-app/CLAUDE.md   <- Project-specific
~/projects/my-app/api/CLAUDE.md <- Component-specific

Monorepo ? Des sous-dossiers différents avec des stacks différentes ? C'est là que ça prouve sa valeur. Garde les fichiers de niveau supérieur courts. Chaque couche se charge à chaque lancement.

@import : mémoire composable

Un fichier peut en importer d'autres. La syntaxe est @chemin/vers/import. Ta configuration mémoire cesse d'être un seul fichier et commence à ressembler à un petit graphe.

See @README for project overview and @package.json for available npm commands.
 
# Additional Instructions
 
- git workflow @docs/git-instructions.md

Les chemins relatifs et absolus fonctionnent tous les deux. Les chemins relatifs se résolvent par rapport au fichier qui importe, pas à ton répertoire de travail. Tu peux pointer vers n'importe quoi sur ta machine :

# Pull in shared team standards
 
- @docs/coding-standards.md
- @docs/api-conventions.md
 
# Reference external files with absolute paths
 
- @~/.claude/my-preferences.md

Approbation à la première utilisation. La première fois qu'un projet importe un fichier extérieur à lui-même, Claude Code affiche une boîte de dialogue d'approbation listant les chemins exacts. Approuve pour charger. Decline pour ignorer. Le choix est mémorisé par projet. Un refus est permanent jusqu'à ce que tu l'annules, et la boîte de dialogue ne réapparaîtra pas.

Sécurité dans les blocs de code. Les imports dans les blocs de code délimités ou les spans de code inline sont ignorés. Écrire @chemin/vers/fichier dans un exemple est sans risque.

Imports récursifs. Les fichiers importés peuvent importer leurs propres fichiers. La profondeur maximum est de 5 niveaux. Utilise ça pour empiler des jeux d'instructions sans tout mettre dans un seul endroit.

Conseil pour les git worktrees. CLAUDE.local.md ne vit que dans un worktree à la fois. Si tu sautes entre les worktrees, mets tes instructions personnelles dans ton répertoire home et importe-les :

# Individual Preferences
 
- @~/.claude/my-project-instructions.md

CLAUDE.local.md : mémoire privée

Certains contextes t'appartiennent, pas à l'équipe. URLs de sandbox locales. Fixtures de test. Une habitude de nommage de branches. Mets-les dans CLAUDE.local.md. Claude Code ajoute ce fichier à .gitignore automatiquement, donc il ne fuite jamais dans le dépôt.

# CLAUDE.local.md
 
## My Local Setup
 
- Dev server: http://localhost:3001
- Test database: local-dev-db
- Preferred branch naming: feature/[initials]-[description]

Il se charge à côté de CLAUDE.md avec la même haute priorité. Tes notes personnelles restent personnelles. Le fichier partagé reste propre.

/memory : inspecter et éditer en direct

Lance /memory dans une session pour voir chaque fichier mémoire actuellement chargé et en ouvrir n'importe lequel dans ton éditeur. Ça couvre trois usages :

• Vérifier quels fichiers CLAUDE.md, règles et imports sont actifs
• Éditer la mémoire sans quitter la session
• Déboguer quand une instruction semble être ignorée

Règles modulaires : mémoire ciblée par chemin

Tu veux plus de contrôle ? Le répertoire .claude/rules/ te permet de découper les instructions en de nombreux petits fichiers, chacun ciblant un pattern de chemin :

.claude/rules/
├── api-guidelines.md     # paths: src/api/**/*
├── react-patterns.md     # paths: src/components/**/*
└── testing-rules.md      # paths: **/*.test.*

Crucial : Les fichiers de règles ont la même haute priorité que CLAUDE.md. Ce qui change, c'est la portée. Le ciblage par chemin décide quand cette priorité s'active.

Ça corrige le problème du "CLAUDE.md monolithique". Entasse tout dans un seul fichier et chaque instruction se bat pour l'attention, y compris celles qui n'ont rien à voir avec ce sur quoi tu travailles maintenant. Avec les règles, tes instructions API n'entrent en compétition que quand Claude édite vraiment du code API.

Règles au niveau utilisateur. Les règles personnelles qui couvrent tous les projets vivent dans ~/.claude/rules/. Elles se chargent avant les règles de projet, donc les règles de projet gagnent en cas d'égalité.

Expansion d'accolades. Les patterns de chemin acceptent l'expansion d'accolades pour plusieurs extensions ou dossiers : src/**/*.{ts,tsx} ou {src,lib}/**/*.ts.

Symlinks. Le dossier .claude/rules/ suit les symlinks, ce qui te permet de réutiliser des jeux de règles entre projets. Les symlinks circulaires sont détectés et ignorés.

Le guide du répertoire de règles couvre la syntaxe complète des patterns de chemin, l'ordre de priorité, et les notes de migration.

Les cinq emplacements mémoire

Claude Code a cinq slots mémoire distincts. Chacun a un rôle :

Les chemins de politique gérée varient selon l'OS :

• macOS : /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux : /etc/claude-code/CLAUDE.md
• Windows : C:\Program Files\ClaudeCode\CLAUDE.md

Les slots supérieurs se chargent en premier et définissent le plancher. Les fichiers plus spécifiques s'empilent par-dessus.

Découverte dans les sous-arbres : chargement paresseux

Claude remonte l'arborescence au lancement. Il remarque aussi les fichiers CLAUDE.md qui se trouvent dans des dossiers en dessous de celui où tu as démarré.

La différence clé : ces fichiers de sous-arborescence ne se chargent pas au lancement. Ils se chargent au moment où Claude lit un fichier dans ce sous-dossier. Le démarrage reste léger, et les règles localisées apparaissent quand même au bon moment.

Donc si packages/auth/CLAUDE.md contient des instructions spécifiques à l'auth, elles restent dormantes jusqu'à ce que Claude ouvre un fichier sous packages/auth/.

Mets ton fichier mémoire sous git

Mets CLAUDE.md sous contrôle de version et il devient une mémoire versionnable :

# Before experimenting with instructions
git add CLAUDE.md && git commit -m "working context state"
 
# Try new instructions, then restore if needed
git checkout CLAUDE.md

Rollback instantané quand une modification se passe mal.

Auto Memory : les propres notes de Claude

Tu écris CLAUDE.md. Claude tient aussi son propre carnet. Ce fichier vit dans ~/.claude/projects/<project>/memory/ et se remplit d'observations de débogage, de patterns de build, et de notes d'architecture. Les 200 premières lignes du fichier principal MEMORY.md se chargent au démarrage à côté de tes fichiers CLAUDE.md. Le guide complet de l'auto memory couvre l'organisation du stockage et la configuration.

Session Memory : résumé en continu

Claude Code tient maintenant un résumé en continu de la session actuelle qui se met à jour à chaque message. Le fichier de résumé vit dans ~/.claude/projects/[project]/[session]/session_memory et suit :

• Titre de la session. Description auto-générée de ton travail
• Statut actuel. Éléments terminés, points de discussion, questions ouvertes
• Résultats clés. Résultats importants et apprentissages
• Journal de travail. Historique chronologique des actions effectuées

Ce flux permet la compaction instantanée. Lance /compact et Claude injecte le résumé dans un contexte frais immédiatement. Pas d'attente de deux minutes.

Demande à Claude "où est stockée ta session memory ?" et il te donnera le chemin exact pour la session actuelle.

Contexte frais à la demande

Les longues sessions s'alourdissent de bruit. Réinitialise avec /clear :

/clear

Ça efface le buffer de conversation et garde CLAUDE.md en place. Le bruit part. Ta mémoire reste.

Pour une réinitialisation complète, quitte et relance :

exit
claude

Contextes isolés par tâche

Tu veux une mémoire totalement séparée pour une branche ? Fork un dossier :

mkdir feature-auth && cd feature-auth
cp ../CLAUDE.md CLAUDE.md
echo "## Focus: Authentication only" >> CLAUDE.md
claude

Chaque dossier porte son propre CLAUDE.md. Les contextes restent cloisonnés. Parfait pour les branches de fonctionnalités et le travail exploratoire.

Quand ça tourne mal

Le contexte semble périmé. L'historique de conversation a accumulé du bruit.

• Solution : Lance /clear. Le chat part, CLAUDE.md reste.

Les projets se mélangent. Les instructions d'un dépôt apparaissent dans un autre.

• Solution : Chaque projet a besoin de son propre CLAUDE.md à la racine du projet.

Les instructions sont ignorées. Le fichier est devenu trop long ou a perdu sa structure.

• Solution : Garde CLAUDE.md sous 400 lignes. Pousse les détails spécifiques à un domaine dans des règles ciblées par chemin, pour qu'ils n'aient une haute priorité que quand le chemin correspond.

Prochaines étapes

• Traite CLAUDE.md comme un système d'exploitation pour des patterns d'orchestration plus lourds
• Lis le guide auto memory pour les propres notes de projet de Claude
• Étudie la gestion du contexte pour garder les tokens légers
• Regarde les modes de planification pour un travail structuré
• Connecte l'intégration git pour des points de contrôle mémoire
• Vois comment la mémoire s'intègre dans le context engineering pour les systèmes d'agents en production

Souviens-toi : CLAUDE.md n'est pas de la documentation de projet. C'est le système d'exploitation de ton agent. Structure-le bien, et chaque session reprend exactement là où la dernière s'est arrêtée.