Claude oublie tout à chaque session — j'ai passé 2h à lui apprendre à se souvenir

Pour la cinquième fois cette semaine, j'ai expliqué à Claude que je ne voulais pas de résumé en fin de message. Pour la cinquième fois, il l'a noté. Pour la cinquième fois, la session suivante, il avait oublié.

Ce n'est pas un bug. C'est le fonctionnement normal. Claude Code démarre chaque session avec une ardoise vierge. Les préférences, les corrections, les décisions prises ensemble la veille -- tout ça disparaît avec /clear ou la fin de la session. Après quelques semaines d'utilisation intensive sur ShareBox, j'avais l'impression de former un stagiaire amnésique.

Phase 1 : tout mettre dans CLAUDE.md

Ma première réaction a été de tout écrire dans le CLAUDE.md du projet. Conventions de code, stack technique, règles de déploiement -- mais aussi mes préférences personnelles. "Réponses concises." "Pas de résumé." "Dev senior, pas besoin d'expliquer les bases." "Toujours recharger php-fpm après un edit PHP." Le fichier a grossi.

En deux semaines, le CLAUDE.md de ShareBox faisait 200 lignes. Un mélange de contraintes projet (ffmpeg n'a pas de GPU, le remux est désactivé) et de préférences personnelles (style de réponse, niveau technique). Certaines infos étaient temporaires -- une décision d'architecture en cours, un bug à investiguer cette semaine. D'autres étaient permanentes. Tout cohabitait dans le même fichier, sans hiérarchie.

Le problème : Claude charge le CLAUDE.md entier à chaque session. Plus il grossit, plus le signal se noie. Et les infos temporaires restent là, même quand elles ne sont plus pertinentes. Un CLAUDE.md de 300 lignes finit par être aussi utile qu'un fichier README que personne ne lit.

La découverte : la mémoire auto

C'est en lisant la doc de Claude Code que j'ai découvert le système de mémoire persistante. Des fichiers Markdown dans un répertoire dédié -- ~/.claude/projects/<projet>/memory/ pour la mémoire projet, ~/.claude/memory/ pour la mémoire globale. Claude les lit au démarrage via un fichier index MEMORY.md, et peut les mettre à jour en cours de session.

La distinction avec le CLAUDE.md est devenue claire à ce moment-là. Le CLAUDE.md décrit le projet : stack, conventions, déploiement, gotchas techniques. C'est versionné avec le code, c'est stable. La mémoire décrit la relation de travail : qui je suis, comment je veux qu'on travaille ensemble, quelles décisions sont en cours.

Première chose que j'ai faite : extraire du CLAUDE.md tout ce qui me concernait moi plutôt que le projet. Mon profil technique, mes préférences de style, les corrections que j'avais dû faire plusieurs fois. Le CLAUDE.md a retrouvé une taille raisonnable, et ces informations ont eu un endroit dédié.

Les 4 tiroirs

Chaque fichier mémoire a un type. Ce n'est pas un label arbitraire -- ça définit quand et comment Claude va l'utiliser.

Le type user dit à Claude avec qui il travaille. Mon fichier user_profile.md contient trois lignes : dev senior PHP/JS, projet perso, préfère le code simple. Ça suffit pour que Claude ajuste son niveau d'explication sans que j'aie à me présenter à chaque session.

Le type feedback capture les corrections de trajectoire. "Ne pas ajouter de Co-Authored-By dans les commits." "Réponses concises et directes, pas de résumé." Ce sont des choses que j'ai dû corriger une ou deux fois, et que je ne veux plus jamais avoir à ré-expliquer. C'est le type qui a résolu mon problème initial -- les résumés en fin de message ont disparu.

Le type project suit l'état en cours : décisions d'architecture actives, initiatives, contraintes temporelles. Sur ShareBox, j'y avais noté la migration vers la v2.0.0 et les problèmes connus. Ce type vieillit vite -- une décision prise en janvier peut être obsolète en mars.

Le type reference pointe vers des ressources externes. Le setup Docker de démo, les ports, la commande de rebuild. Tout ce que Claude ne peut pas déduire du code mais dont il a besoin régulièrement.

Ce que j'y mets -- et ce que j'ai appris à ne pas y mettre

Au début, j'ai fait l'erreur inverse du CLAUDE.md : j'ai voulu tout noter. Chaque gotcha, chaque décision mineure, chaque préférence. La mémoire a gonflé aussi vite que le fichier qu'elle était censée remplacer.

La règle que j'ai fini par adopter est simple : un fichier mémoire doit contenir de l'information non déductible du code ou du CLAUDE.md, et utile dans les prochaines sessions.

Ce qui passe le filtre :

• Une préférence de style confirmée ou corrigée ("pas de résumé en fin de réponse", "toujours passer par telle fonction pour modifier tel comportement")
• Un gotcha invisible dans le code -- une contrainte que Claude ne découvrirait pas en lisant les fichiers
• Une décision d'architecture en cours, pas encore dans le code
• Un pointeur vers une ressource externe utilisée régulièrement

Ce qui ne passe pas :

• Ce qui est visible dans les fichiers -- Claude le retrouvera seul
• Le détail des sessions passées -- le git log est plus fiable
• Les tâches en cours -- elles appartiennent à la session, pas à la mémoire
• Les conventions déjà dans le CLAUDE.md -- duplication inutile

Projet vs global : où mettre quoi

J'ai perdu du temps à mettre des préférences personnelles dans la mémoire projet de ShareBox, pour les re-découvrir absentes quand je travaillais sur un autre dépôt. La mémoire projet (~/.claude/projects/<cwd-sanitisé>/memory/) est isolée par répertoire de travail. Un autre dossier, une autre mémoire.

La mémoire globale (~/.claude/memory/) s'applique partout, tous projets confondus. C'est là que vont les préférences transversales : style de réponse, niveau technique, conventions de communication.

La règle pratique : commencer par la mémoire projet. Si une préférence revient dans tous les projets, la déplacer en global. Ne jamais dupliquer.

Automatiser l'alimentation

Demander manuellement à Claude de sauvegarder chaque préférence, ça marche les premiers jours. Ensuite on oublie. J'ai ajouté une règle dans mon ~/.claude/CLAUDE.md (le CLAUDE.md utilisateur, chargé dans toutes les sessions) :

# Règles globales

## Mémoire automatique

Dès qu'une session révèle une information persistante, la sauvegarder
immédiatement dans le bon fichier mémoire sans attendre que l'utilisateur
le demande :

- Préférence découverte ou corrigée -> memory/user ou memory/feedback
- Correction d'approche            -> memory/feedback
- Décision projet durable          -> memory/project
- Pointeur vers ressource externe  -> memory/reference

Ne pas sauvegarder : état temporaire, travail en cours, ce qui est déjà
dans CLAUDE.md, ce qui est déductible du code.

Le filtre est aussi important que le déclencheur. Sans la partie "Ne pas sauvegarder", Claude note chaque détail de session et la mémoire grossit sans contrôle. C'est exactement le problème qu'on cherchait à éviter.

La mémoire vieillit : le prompt d'audit

Après un mois, j'avais des fichiers project qui parlaient de décisions résolues depuis deux semaines. Claude les lisait, les prenait en compte, et ça créait de la confusion. La mémoire n'est pas un système "fire and forget" -- elle demande de l'entretien.

J'ai écrit un prompt d'audit que je lance en début de session quand la mémoire a dérivé :

Audite les fichiers mémoire dans `.claude/projects/.../memory/`.

Pour chaque fichier :
1. Le contenu est-il encore exact ? (vérifier contre l'état actuel des fichiers si nécessaire)
2. Est-il non déductible du code ou du CLAUDE.md ?
3. Le type est-il correct ? (user / feedback / project / reference)
4. La description dans le frontmatter est-elle assez précise ?

Cohérence globale : doublons, contradictions, mémoires project obsolètes, MEMORY.md à jour ?

Résultat en tableau : Fichier | Problème | Action recommandée
Puis applique les corrections.

Pour ne pas avoir à le retrouver, je l'ai sauvegardé comme commande slash dans ~/.claude/commands/audit-memory.md. Depuis, /audit-memory suffit.

Le résultat

Aujourd'hui, la mémoire de mon projet ShareBox tient en 5 fichiers courts. Un profil utilisateur, deux feedbacks (pas de Co-Authored-By, réponses concises), un fichier projet (architecture ShareBox, Docker, TMDB), une référence (setup démo). Le CLAUDE.md ne contient plus que ce qui concerne le projet lui-même.

Claude ne m'a pas redemandé mon niveau technique depuis des semaines. Il ne met plus de résumé en fin de message. Il sait que le remux est désactivé et pourquoi. Les sessions démarrent directement sur le sujet, sans phase de re-présentation.

Le système n'est pas magique. Il demande de la discipline -- savoir quoi noter, où le noter, et nettoyer régulièrement. Mais c'est exactement ce qu'on fait avec n'importe quel outil de travail. La mémoire auto transforme Claude d'un outil amnésique en un collaborateur qui apprend. À condition de ne pas la laisser devenir, elle aussi, un fichier de 300 lignes que personne ne lit.