« On n’avait pas décidé ça hier ? »

J’étais en train de migrer mon email hors de Google. Ça faisait deux sessions de Claude Code qu’on bossait dessus : des issues dans Linear, des décisions prises, des scripts exécutés. J’ouvre une troisième session et je lui demande « qu’est-ce qui reste en suspens du degoogle ? »

Silence. Amnésie totale.

C’est comme bosser avec un collègue brillant qui chaque matin arrive au bureau sans se rappeler absolument rien de ce que vous avez fait la veille. Ni les décisions, ni les erreurs, ni les découvertes. Chaque session est une page blanche.

Et il s’avère qu’il y a un fichier qui résout exactement ce problème. Il est là depuis des mois. Et presque personne ne le connaît.

CLAUDE.md vs MEMORY.md : le manuel et le carnet

Si vous utilisez Claude Code, vous connaissez probablement déjà CLAUDE.md. C’est le fichier où vous dites à l’IA comment travailler : quelle langue utiliser, quels outils vous avez, vos conventions de code.

CLAUDE.md est votre manuel d’instructions. Vous l’écrivez. Vous l’entretenez.

MEMORY.md c’est autre chose. C’est un carnet de terrain que l’IA écrit toute seule. Elle note ce qu’elle apprend en travaillant avec vous : les erreurs qu’elle a commises, les décisions que vous avez prises, les patterns du projet, les trucs qu’elle a testés et qui n’ont pas marché.

Dit simplement :

CLAUDE.mdMEMORY.md
Qui l’écritVousL’IA
Que contient-ilInstructionsApprentissages
Quand ça changeQuand vous voulezAprès chaque session
AnalogieLe règlementLe carnet de terrain

Si CLAUDE.md c’est le contrat que vous donnez au stagiaire le premier jour, MEMORY.md ce sont les notes que le stagiaire prend dans son calepin en bossant.

Où ça vit

~/.claude/projects/<hash-du-répertoire>/memory/MEMORY.md

Chaque répertoire de projet a son propre fichier de mémoire. Si vous bossez dans ~/code/projet-a, il a un MEMORY.md. Si vous ouvrez Claude Code dans ~/code/projet-b, il en a un autre différent. Ils ne se mélangent pas.

Le fichier se charge automatiquement dans le contexte au début de chaque session. Vous n’avez rien à faire.

Il n’y a pas de MEMORY.md global ?

Non. Seulement par projet. Et c’est un problème.

Aujourd’hui j’ai créé un wrapper de op (le CLI de 1Password) qui met en cache les secrets pendant une heure. C’est utile dans tous mes projets, pas seulement dans celui sur lequel je bossais. Mais MEMORY.md l’a noté seulement dans la mémoire de ce répertoire.

CLAUDE.md a bien une version globale (~/.claude/CLAUDE.md), qui se charge dans toutes les sessions. MEMORY.md n’a pas d’équivalent. Si l’IA apprend quelque chose qui s’applique à tout votre environnement (un alias, une particularité de votre système, une préférence), elle doit le noter dans chaque projet séparément. Ou elle ne le note pas.

En pratique, ce que je fais c’est mettre ce genre de connaissance transversale dans mon CLAUDE.md global à la main. C’est pas idéal, mais ça marche.

Si j’efface le projet, la mémoire s’efface ?

Non. La mémoire vit dans ~/.claude/projects/, pas dans votre répertoire de code. Si vous effacez ~/code/mon-projet/, le MEMORY.md reste là, orphelin, prenant de la place sans que personne ne le lise.

Est-ce que quelqu’un fait le ménage ? Ça va être que non. Il n’y a aucun garbage collector qui détecte les répertoires de projet supprimés. Avec le temps, ~/.claude/projects/ va accumuler des mémoires de projets qui n’existent plus.

Si vous êtes du genre à effacer des projets fréquemment, de temps en temps ça vaut le coup de jeter un œil :

1

ls ~/.claude/projects/

Et effacer les répertoires que vous ne reconnaissez plus. Il ne va rien se passer de grave — le pire qui puisse arriver c’est que l’IA reparte de zéro la prochaine fois.

À quoi ça ressemble

Voici un exemple réel. Aujourd’hui, après une session de migration de mon email hors de Google Workspace, mon MEMORY.md ressemblait à ça :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Memory - f@frr.dev

## Degoogle f@frr.dev — TERMINÉ (2026-02-12)

- Email : migré vers iCloud+ custom domain (plan 200 GB, coût 0€)
- ChatGPT : passkey configurée (iCloud Keychain)
- Linear : passkey web + token API fonctionnent
- Google Workspace : annulé après Takeout

## Wrapper op (cache du CLI 1Password)

- Emplacement : ~/.local/bin/op
- Met en cache `op read` pendant 1h, le reste passe direct
- Pourquoi : Claude Code lance un nouveau processus pour chaque commande Bash

## Leçons techniques

- `stat` est GNU sur ce Mac (coreutils via Homebrew). Utiliser `stat -c %Y`
- API Linear : `issueCreate` nécessite l'UUID de l'équipe, pas la clé

Pas de philosophie. Des faits concrets. La prochaine fois que j’ouvre une session ici, Claude sait déjà que le degoogle est fait, que j’ai un wrapper d’op, et que stat est GNU sur mon Mac.

Le vrai problème que ça résout

C’est pas juste « se rappeler des trucs ». C’est éviter que l’IA répète des erreurs.

Aujourd’hui, la première fois que j’ai écrit le wrapper d’op, j’ai utilisé stat -f %m (syntaxe BSD). Ça a foiré parce que mon Mac a GNU coreutils via Homebrew. Je l’ai corrigé avec stat -c %Y.

Sans MEMORY.md, la prochaine fois que j’ai besoin de stat dans ce projet, elle va essayer stat -f %m encore. Avec MEMORY.md, elle sait déjà qu’il ne faut pas le faire.

C’est la différence entre un collègue qui note les choses et un qui fait confiance à sa mémoire. Celui qui note ne répète pas les erreurs.

Comment éviter que ça se remplisse de saloperies

Voici la question évidente : si l’IA écrit ce qu’elle veut, ça ne va pas finir par être une décharge de notes sans intérêt ?

Il y a plusieurs garde-fous :

1. Limite de 200 lignes. Tout ce qui dépasse la ligne 200 est tronqué au chargement. Ça force à être concis.

2. Organisation par thèmes. On peut créer des fichiers séparés (debugging.md, patterns.md) et les lier depuis MEMORY.md. Le fichier principal est un index, pas un fourre-tout.

3. Vous avez le dernier mot. C’est un fichier texte sur votre disque. Vous pouvez l’éditer, l’effacer, ou dire à Claude « nettoie MEMORY.md, ça c’est plus pertinent ».

4. L’IA s’auto-corrige. Les instructions système lui disent de mettre à jour ou supprimer les mémoires qui s’avèrent fausses ou obsolètes.

En pratique, ça marche étonnamment bien. L’IA a tendance à être plus disciplinée que beaucoup d’humains pour prendre des notes — probablement parce qu’elle n’a pas d’ego ni d’attachement à ses propres idées.

Pourquoi personne ne le connaît

Bonne question. Ça fait des mois que c’est dans Claude Code, ça marche par défaut, et je ne me rappelle pas l’avoir vu mis en avant dans un changelog ou un blogpost d’Anthropic.

Ma théorie : c’est une fonctionnalité qui est née comme infrastructure interne pour améliorer l’expérience entre sessions, pas comme une feature face utilisateur. Il n’y a pas d’UI, pas de toggle, pas de panneau de configuration. C’est un fichier texte dans un répertoire caché.

Et c’est là le problème. Les fonctionnalités les plus utiles sont souvent les plus invisibles, parce que personne ne les cherche si on ne sait pas qu’elles existent.

La quatrième couche de mémoire

Si vous avez lu mon post sur Linear, Beads et Tasks, MEMORY.md s’imbrique comme une quatrième couche qui complète les autres :

CoucheHorizonQui écritQue contient-elleExemple
LinearSemaines/moisHumainCe que vous voulez« Lancer v2 en mars »
BeadsJours/sessionsHumain + IACe qu’il faut faire« Corriger le bug dans le cache »
TasksHeuresIACe que je fais« Exécution des tests »
MEMORY.mdPermanentIACe que j’ai appris« stat est GNU ici »

Les trois premières concernent le travail : quoi faire, dans quel ordre, qui le fait. MEMORY.md concerne la connaissance : ce qu’on a appris en le faisant.

Et c’est là la clé. Beads et Tasks sont éphémères par design : une tâche se termine et se ferme, une issue se résout et s’archive. MEMORY.md c’est ce qui reste après. Les leçons, pas les devoirs.

Un exemple concret de comment elles se complètent : aujourd’hui j’ai utilisé Linear pour tracker les issues du degoogle (PER-16 à PER-28). Tasks pour suivre les étapes dans chaque issue. Et MEMORY.md pour noter que l’API de Linear a besoin d’UUIDs pour les équipes, pas des clés. Les issues se sont fermées. Les Tasks ont disparu. La leçon sur les UUIDs reste là pour la prochaine fois.

Comment commencer à l’utiliser

Il n’y a rien à activer. Ça fonctionne déjà.

La seule chose à faire c’est dire à Claude « note ça dans ta mémoire » quand il se passe quelque chose qui mérite d’être retenu :

  • Décisions techniques (« on a choisi iCloud+ pour l’email »)
  • Erreurs et solutions (« stat est GNU, utiliser -c pas -f »)
  • Contexte du projet (« le degoogle est terminé »)
  • Préférences découvertes (« l’utilisateur préfère X à Y »)

Et de temps en temps, réviser ~/.claude/projects/*/memory/MEMORY.md pour voir ce qu’elle a noté et élaguer ce qui est en trop.

Le carnet du bon apprenti

Il y a une phrase de Feynman qui tombe à pic : « The first principle is that you must not fool yourself — and you are the easiest person to fool. »

Un LLM ne se ment pas à lui-même parce qu’il n’a pas d’ego. Il ne pense pas « je m’en rappellerai » ni « c’est trop évident pour le noter ». Si vous lui dites de noter quelque chose, il le note. S’il découvre qu’une note est incorrecte, il la corrige.

D’une certaine manière, il est meilleur pour prendre des notes que la plupart d’entre nous ne le seront jamais. Il lui manquait juste un endroit où les garder.

Maintenant il l’a.