Ton IA fait le boulot, puis elle l'efface — à chaque session

#Le paradoxe de la session IA

Tu lances Claude Code sur ton projet. Il passe trente minutes à explorer le codebase : il lit ton architecture, comprend tes conventions, découvre que tes tests d'API ont besoin d'une instance Redis locale, identifie que le build se lance avec un flag non documenté. Tu résolves ensemble un bug complexe. Il apprend que telle approche ne marche pas parce que le middleware réécrit l'URL.

Puis tu fermes le terminal.

Le lendemain, tu rouvres Claude Code. Première question posée : « où est le fichier de config principal ? ». Il ne le sait plus. Le Redis, les conventions, le middleware — tout a disparu. Tu recommences depuis zéro.

Ce n'est pas un bug de Claude Code. C'est une conséquence directe du fonctionnement des modèles de langage : chaque session démarre avec une fenêtre de contexte vide. La documentation officielle d'Anthropic le dit sans détour : « Each Claude Code session begins with a fresh context window. »

Le problème n'est pas que l'IA oublie. Le problème est que tu paies pour le même travail de reconnaissance chaque matin.

#Ce qui disparaît concrètement

Quand on parle de « contexte perdu », on pense d'abord aux préférences (« je code en Bun, pas en Node »). Mais la perte réelle est beaucoup plus profonde. Voici les sept catégories de contexte qui s'évaporent à chaque fermeture de session :

La catégorie la plus douloureuse est la connaissance négative : savoir ce qui ne marche pas et pourquoi. Quand Claude redémarre, il ne sait pas que tu as déjà essayé trois approches avant de trouver la bonne. Il va proposer les mauvaises approches à nouveau, parfois même les implémenter.

#Les deux mécanismes natifs d'Anthropic

Anthropic a répondu au problème avec deux systèmes distincts. Le premier existe depuis le lancement de Claude Code, le second est arrivé avec la version 2.1.59.

#1. CLAUDE.md — la mémoire que tu écris

Le fichier CLAUDE.md est un texte que Claude lit automatiquement au démarrage de chaque session. Tu y mets ce qui ne change pas : stack, commandes, conventions, règles du projet.

Il existe quatre portées possibles, chargées dans cet ordre :

/etc/claude-code/CLAUDE.md         # Organisation (partagée par tous)
~/.claude/CLAUDE.md                # Utilisateur (tes préférences globales)
./CLAUDE.md                        # Projet (commité dans git)
./CLAUDE.local.md                  # Local (ignoré par git, secrets/notes perso)

La commande /init génère un CLAUDE.md de départ en analysant ton projet. C'est le point de départ recommandé.

Exemple minimal pour un projet Next.js + Bun :

# Mon Projet

## Stack
- Bun (pas npm, yarn ou pnpm)
- Next.js 14 App Router
- PostgreSQL via Prisma

## Commandes
- `bun dev` — dev server
- `bun run build` — build production
- `bun test` — tests (jamais `npm test`)

## Conventions
- Les hooks custom vivent dans `src/lib/hooks/` (pas `src/hooks/`)
- Tous les composants serveur par défaut, `'use client'` uniquement si nécessaire
- Les tests d'API requièrent Redis local sur port 6380

## Décisions
- Sessions DB plutôt que JWT (besoin de révocation server-side)
- Pas de Framer Motion (cassait la prerendering Next.js)

#2. Auto Memory — la mémoire que Claude écrit lui-même

Depuis la version 2.1.59 (novembre 2025), Claude Code dispose d'un système de mémoire automatique. Claude décide lui-même quoi retenir, sans que tu aies à l'éditer manuellement.

Le fichier vit dans ~/.claude/projects/<project>/memory/MEMORY.md — un chemin global à ton installation, un par projet. Les 200 premières lignes (ou 25 Ko) sont injectées automatiquement au démarrage de chaque session.

Concrètement, quand Claude apprend quelque chose d'utile pour le futur — ton rôle, tes préférences de tests, une décision technique que tu as validée — il écrit une entrée dans un fichier de mémoire thématique (user.md, testing.md, api.md...) et ajoute une ligne dans MEMORY.md qui pointe vers ce fichier.

#Les trois stratégies manuelles qui comblent le reste

Les mécanismes natifs couvrent les faits stables (stack, conventions) et certaines préférences. Ils capturent mal l'état de session et la connaissance négative. Voici trois stratégies à ajouter.

#Stratégie 1 — Le fichier de session

Crée un fichier .claude/session.md (ou SESSION.md à la racine) que tu mets à jour pendant la session. Tu peux demander à Claude de le maintenir pour toi :

# Session du 22/04/2026

## Objectif
Refactorer le module auth pour utiliser des sessions DB.

## Décisions prises
- On garde `express-session` mais on swap le store Redis pour Prisma
- On ne touche pas aux endpoints publics cette session

## Tentatives qui ont échoué
- ❌ Store custom avec JSON.stringify : TypeError sur les dates
- ❌ Middleware avant `session()` : ordre important, doit passer en dernier

## État
- Fichier en cours : `src/lib/auth/session-store.ts`
- Prochain pas : écrire les tests d'intégration

À la session suivante, tu démarres par « lis .claude/session.md » et Claude se resitue en 10 secondes au lieu de 10 minutes.

#Stratégie 2 — Commenter les décisions dans le code

Les commentaires ne disparaissent pas quand la session se ferme. C'est un stockage gratuit et permanent de ta connaissance négative.

// On utilise un store DB plutôt que JWT parce qu'on a besoin
// de pouvoir révoquer une session côté serveur (RGPD).
// Tenté : JWT + blacklist Redis → trop de maintenance.
export async function createSession(userId: string) {
  // ...
}

La règle : si tu as pris une décision non évidente, ou écarté une alternative raisonnable, écris-le. Tu t'écris à toi-même ET à Claude.

#Stratégie 3 — Messages de commit détaillés

Claude lit git log quand tu lui demandes. Un historique de commits bien écrit devient une timeline de contexte consultable :

fix(auth): revert to Prisma store, Redis store crashed on pool exhaustion

Reason: the Redis connection pool maxed out under load tests (>100 concurrent
sessions). Prisma store is slower but handles the load thanks to DB pooling.

Alternatives considered:
- Larger Redis pool: rejected, moves the problem
- Connection retry: rejected, adds latency on cold paths

Trois lignes de contexte en plus, et le prochain Claude qui ouvre ce repo comprend immédiatement pourquoi ce choix a été fait.

#Récapitulatif — la checklist mémoire

Un projet Claude Code bien équipé contre l'amnésie ressemble à ceci :

La checklist minimale :

1. Exécute /init sur ton projet pour générer un CLAUDE.md de départ
2. Raffine-le avec ta stack, tes commandes et tes conventions implicites
3. Garde-le court — moins de 200 lignes, sinon Claude suit moins bien
4. Ajoute un SESSION.md que tu maintiens pour l'état en cours
5. Commente les décisions dans le code, pas dans la conversation
6. Écris des commits détaillés avec les alternatives rejetées
7. Laisse l'auto memory faire le reste — elle s'active au-delà de 10 k tokens

#La leçon de fond

Les LLMs n'ont pas de mémoire. Cette limite n'est pas une faiblesse temporaire qui disparaîtra avec la prochaine version — c'est une propriété structurelle des modèles actuels. Plus tu l'acceptes et l'adresses explicitement, plus ton workflow devient résilient.

Le vrai piège n'est pas l'oubli. C'est de continuer à travailler comme si l'IA se souvenait, et de passer les premières vingt minutes de chaque session à lui réexpliquer ce qu'on lui a déjà expliqué dix fois. Cinq minutes à écrire un CLAUDE.md remplacent vingt minutes quotidiennes de réexplication.

Le paradoxe se retourne : ton IA ne fait plus le boulot puis l'efface. Elle fait le boulot, tu captures l'essentiel, et la session suivante démarre déjà à mi-chemin.