Memoire et persistance dans Claude Code : le guide complet (CLAUDE.md, MCP Memory, sessions)

Le plus gros probleme quand tu bosses avec Claude Code au quotidien, c’est que chaque conversation repart de zero. Claude ne se souvient pas de ce que tu lui as dit hier. Il ne sait pas que tu preferes les tabs aux spaces, que ton projet utilise Vitest et pas Jest, ou que le fichier utils/auth.ts est un nid a bugs qu’il ne faut pas toucher.

Sauf si tu configures la persistance correctement.

Claude Code offre quatre mecanismes de persistance complementaires, et la plupart des devs n’en utilisent qu’un seul (ou aucun). Ce guide couvre les quatre, explique quand utiliser lequel, et te donne un arbre de decision pour ne plus te poser la question.

Les 4 mecanismes de persistance

1. CLAUDE.md : les instructions permanentes

C’est le mecanisme le plus basique et le plus puissant. Le fichier CLAUDE.md a la racine de ton projet est lu par Claude Code a chaque demarrage de conversation. Tout ce qui est dedans est considere comme une instruction permanente.

Ce qu’il faut y mettre :

Les conventions du projet (stack, style, patterns)
Les regles que tu ne veux jamais repeter (“toujours utiliser des composants serveur”, “jamais de any en TypeScript”)
Les commandes custom et leur usage
Le contexte business minimal du projet

Ce qu’il ne faut PAS y mettre :

Des infos qui changent souvent (taches en cours, bugs du moment)
Des instructions trop longues (Claude a un budget de tokens pour le contexte)
Des donnees sensibles (le fichier est dans le repo)

2. Fichiers memoire : le cerveau persistant

Au-dela de CLAUDE.md, tu peux configurer un systeme de memoire base sur des fichiers. Claude Code peut lire et ecrire dans un dossier dedie (.claude/memory/ ou equivalent) pour stocker des informations qui evoluent dans le temps.

Cas d’usage :

Profil utilisateur (qui tu es, tes preferences, ton niveau)
Feedbacks accumules (“ne fais plus X”, “continue a faire Y”)
Contexte projet (decisions architecturales, contacts, deadlines)
References externes (liens Notion, dashboards, repos)

Avantage : Les memoires survivent entre les conversations et s’enrichissent au fil du temps.

3. MCP Memory : le knowledge graph

MCP Memory est un serveur MCP qui stocke les informations sous forme de graphe de connaissances. Contrairement aux fichiers plats, il permet des relations entre entites et des requetes structurees.

Quand l’utiliser :

Quand tu as beaucoup d’entites liees (personnes, projets, decisions)
Quand tu veux pouvoir interroger la memoire par relation (“qui a decide X ?”, “quels projets sont lies a Y ?”)
Quand tu travailles en equipe et que la memoire doit etre partagee

Quand s’en passer :

Pour un solo builder avec des besoins simples, les fichiers memoire suffisent
Si tu ne veux pas gerer un serveur MCP supplementaire

4. Session storage : le contexte de conversation

Pendant une conversation, Claude Code maintient un contexte qui inclut tout ce qui s’est passe : tes messages, ses reponses, les resultats d’outils. Ce contexte est automatique mais ephemere : il disparait quand la conversation se termine.

Comment l’optimiser :

Utilise les taches (TodoWrite) pour garder le fil dans les conversations longues
Utilise le plan mode pour les taches complexes (le plan persiste dans la conversation)
Sois conscient que le contexte se compresse quand il approche la limite

L’arbre de decision

Pour savoir quel mecanisme utiliser, pose-toi ces questions :

Est-ce que cette info doit survivre entre les conversations ?

Non -> Session storage (automatique)
Oui -> Continue

Est-ce que cette info change rarement ?

Oui -> CLAUDE.md
Non -> Continue

Est-ce que cette info a des relations complexes avec d’autres infos ?

Oui -> MCP Memory
Non -> Fichiers memoire

Les erreurs les plus courantes

1. Tout mettre dans CLAUDE.md

CLAUDE.md est lu a chaque conversation. Si tu y mets 500 lignes d’instructions, tu consommes des tokens inutilement et tu dilues les instructions importantes. Garde CLAUDE.md pour les regles critiques et invariantes.

2. Ne jamais nettoyer la memoire

Les fichiers memoire et MCP Memory accumulent des informations. Si tu ne nettoies jamais, tu te retrouves avec des infos obsoletes qui induisent Claude en erreur. Fais un menage mensuel.

3. Ignorer la hierarchie des CLAUDE.md

Claude Code lit les CLAUDE.md a plusieurs niveaux : global (~/.claude/CLAUDE.md), projet (racine), et sous-dossiers. Utilise cette hierarchie : les regles globales dans le global, les regles projet dans le projet, les regles specifiques dans les sous-dossiers.

4. Stocker des secrets dans la memoire

Les fichiers memoire sont en clair sur le disque. Ne stocke jamais de tokens, mots de passe, ou cles API dans la memoire. Utilise des variables d’environnement.

Ma config recommandee

Pour un builder solo :

CLAUDE.md global : qui tu es, tes preferences universelles, les regles de formatage
CLAUDE.md projet : stack, conventions, commandes custom, contexte business
Fichiers memoire : profil detaille, feedbacks, contacts, references externes
MCP Memory : optionnel, a ajouter si tu geres beaucoup d’entites interconnectees
Session : laisser Claude gerer, utiliser les taches pour les conversations longues

Ce guide est base sur l’utilisation quotidienne des 4 mecanismes de persistance dans Claude Code sur des projets de production.