Architecture Mémoire Claude Code : 3 Couches Décryptées

Publié le 6 avril 2026

L'architecture mémoire de Claude Code repose sur 3 couches complémentaires révélées par le leak de son code source. La première couche est MEMORY.md, un fichier d'index persistant stocké dans .claude/ où chaque ligne fait ~150 caractères max. Il contient les conventions du projet, les décisions architecturales et les préférences — chargé dans le system prompt à chaque interaction. La deuxième couche est l'auto-compaction : quand la session atteint 5 fichiers ouverts ou 5 000 tokens de diffs, Claude Code compresse automatiquement tout le contexte en un résumé structuré de ~50K tokens qui conserve les décisions, l'état du travail et les prochaines étapes. La troisième couche, les cache-aware boundaries, aligne le contenu du contexte sur les frontières du cache API en plaçant les éléments stables (system prompt, MEMORY.md) en début de prompt pour maximiser les cache hits — réduisant les coûts de 40 à 60%. Pour en tirer parti : crée un MEMORY.md concis et stable, utilise /compact entre les changements de sujet, et travaille par blocs thématiques pour optimiser le cache.

Pourquoi Claude Code a-t-il besoin d'une architecture mémoire en 3 couches ?

Quand tu bosses avec un LLM en mode agent, le problème numéro un, c'est la mémoire. Un modèle comme Claude a une fenêtre de contexte limitée — même si elle est massive (200K tokens), elle se remplit à une vitesse hallucinante quand tu navigues dans un codebase de production. Le leak du code source de Claude Code via un packaging npm défaillant a révélé comment Anthropic a résolu ce problème avec une architecture mémoire à 3 couches d'une élégance redoutable.

D'après l'analyse du code source par Engineer's Codex, cette architecture repose sur trois niveaux distincts : un fichier d'index persistant (MEMORY.md), un système d'auto-compaction intelligent, et des cache-aware boundaries qui optimisent chaque token envoyé à l'API. Chaque couche résout un problème précis, et ensemble, elles permettent à Claude Code de maintenir une cohérence sur des sessions de travail de plusieurs heures sans jamais perdre le fil.

Si tu as déjà utilisé Claude Code sur un gros projet et que tu t'es demandé comment il se souvient de tes conventions, de la structure de ton projet et de tes préférences sans que tu aies à tout répéter — c'est exactement ce système qui travaille en coulisses. Et comprendre comment il fonctionne va te permettre de l'exploiter à fond.

Le problème fondamental : contexte limité, projets illimités

Un codebase moyen en entreprise contient entre 100 000 et 500 000 lignes de code. Comme le détaille Layer5 dans son analyse, le code source leaké de Claude Code lui-même représente environ 512 000 lignes. Charger tout ça dans une fenêtre de contexte, c'est impossible. Même avec 200K tokens, tu ne couvres qu'une fraction d'un projet réel.

La solution naïve serait de tout résumer en amont. Mais ça perd les détails critiques. L'autre extrême — ne charger que le fichier courant — fait perdre toute vision d'ensemble. L'architecture 3 couches de Claude Code est un compromis chirurgical entre ces deux approches. Pour bien comprendre l'ensemble de l'architecture, je t'invite à consulter notre analyse complète des secrets d'architecture révélés par le leak.

Vue d'ensemble des 3 couches

Voici comment les 3 couches s'articulent :

• Couche 1 — MEMORY.md : un fichier d'index persistant qui stocke les métadonnées du projet, les conventions et les décisions architecturales. Chaque ligne fait environ 150 caractères max.
• Couche 2 — Auto-compaction : un mécanisme qui se déclenche automatiquement quand la conversation dépasse certains seuils (5 fichiers ouverts ou 5 000 tokens de diff), compactant le contexte en un résumé de ~50K tokens.
• Couche 3 — Cache-aware boundaries : un système d'alignement du contexte sur les frontières du cache de l'API Claude, pour maximiser les cache hits et réduire les coûts.

Ces trois couches fonctionnent en cascade. MEMORY.md est toujours chargé en premier, l'auto-compaction gère le flux de la session, et les cache-aware boundaries optimisent chaque appel API.

Comment fonctionne MEMORY.md, le cerveau persistant de Claude Code ?

MEMORY.md est la pièce maîtresse de la mémoire long-terme de Claude Code. C'est un fichier Markdown stocké à la racine de ton projet (ou dans ~/.claude/ pour les préférences globales) qui sert d'index structuré de tout ce que Claude Code doit retenir entre les sessions.

D'après l'analyse détaillée de Sabrina.dev, ce fichier est conçu avec une contrainte brutale : chaque ligne ne doit pas dépasser ~150 caractères. Pourquoi ? Parce que MEMORY.md est injecté dans le system prompt à chaque interaction. Chaque caractère compte. Chaque ligne doit être une information atomique, immédiatement exploitable.

Structure et format du fichier MEMORY.md

Le format est volontairement minimaliste. Voici un exemple reconstitué à partir du code source leaké :

# MEMORY.md
## Project
- TypeScript monorepo, pnpm workspaces
- API: Express + Zod validation
- DB: PostgreSQL + Drizzle ORM
- Tests: Vitest, coverage > 80%

## Conventions
- Naming: camelCase functions, PascalCase components
- No default exports
- Error handling: Result pattern, no throw

## Architecture decisions
- Event sourcing for order domain
- CQRS separation read/write models
- Feature flags via LaunchDarkly

Chaque bullet point est une unité d'information autonome. Pas de paragraphes, pas d'explications longues. Claude Code lit ce fichier et sait instantanément dans quel contexte il opère. C'est un pattern que tu peux d'ailleurs appliquer toi-même — on en parle dans notre guide sur les best practices Claude Code.

Mise à jour automatique vs. manuelle

Un point fascinant révélé par le leak : Claude Code peut mettre à jour MEMORY.md automatiquement. Quand tu lui donnes une instruction comme « souviens-toi que nous utilisons Zod pour la validation », il ajoute une ligne au fichier. Mais le code source montre aussi que cette mise à jour passe par un filtre de déduplication — si une information similaire existe déjà, elle est fusionnée plutôt que dupliquée.

Comme le souligne MindStudio dans son analyse des features cachées, tu peux aussi éditer MEMORY.md manuellement. Et c'est souvent la meilleure approche : tu contrôles exactement ce que Claude Code retient. Pense à ce fichier comme un onboarding document ultra-condensé pour ton agent IA.

Hiérarchie des fichiers mémoire

Le leak révèle qu'il existe en réalité plusieurs niveaux de MEMORY.md :

• ~/.claude/MEMORY.md : préférences globales (style de code, langue, conventions personnelles)
• ./.claude/MEMORY.md : spécifique au projet courant
• ./.claude/MEMORY.local.md : spécifique à ta machine (non commité)

Ces fichiers sont chargés en cascade dans le system prompt, du plus général au plus spécifique. Si tu travailles sur plusieurs projets, tes préférences globales sont toujours là, mais les conventions projet prennent le dessus en cas de conflit.

Comment l'auto-compaction empêche-t-elle Claude Code de perdre la mémoire ?

La deuxième couche est celle qui gère la mémoire de session — tout ce qui se passe pendant une conversation active. Et c'est là que l'auto-compaction entre en jeu. D'après l'analyse d'Alex Kim, le mécanisme est à la fois simple dans son concept et sophistiqué dans son implémentation.

Les seuils de déclenchement : 5 fichiers, 5K tokens

L'auto-compaction ne se déclenche pas au hasard. Le code source révèle deux seuils principaux :

• 5 fichiers ouverts/modifiés dans la session courante
• 5 000 tokens de diff accumulés (les modifications de code envoyées dans le contexte)

Quand l'un de ces seuils est atteint, Claude Code lance un processus de compaction. Il prend tout le contexte accumulé — les fichiers lus, les diffs, les résultats de commandes, les échanges conversationnels — et le compresse en un résumé structuré d'environ 50 000 tokens. Ce résumé conserve les décisions prises, les fichiers modifiés, les erreurs rencontrées et les prochaines étapes.

Le résultat ? Tu peux travailler pendant des heures sur un refactoring complexe sans que Claude Code perde le contexte de ce qu'il a fait au début de la session. Pour voir comment ça s'intègre dans un workflow agent complet, check notre article sur KAIROS, l'agent autonome basé sur Claude Code.

Anatomie d'un résumé de compaction

Le résumé généré par l'auto-compaction n'est pas un simple « TL;DR ». D'après l'analyse de Blake Crosley, il suit un format structuré :

• Objectif de la session : ce que l'utilisateur cherche à accomplir
• Fichiers touchés : liste avec un résumé des modifications par fichier
• Décisions prises : choix architecturaux, patterns adoptés
• État courant : où en est le travail, quels tests passent/échouent
• Prochaines étapes : ce qui reste à faire

Ce format permet à Claude Code de « reprendre » exactement là où il en était, même après avoir perdu 80% du contexte brut. C'est comme si tu prenais des notes de réunion ultra-structurées plutôt que de garder l'enregistrement audio complet.

Compaction récursive pour les sessions longues

Un détail particulièrement malin : la compaction peut se déclencher plusieurs fois dans une même session. Si après une première compaction, le contexte se remplit à nouveau et atteint les seuils, une deuxième compaction se produit. Le résumé précédent est alors lui-même résumé et fusionné avec les nouvelles informations.

Cela crée une sorte de mémoire fractale — chaque niveau de compaction perd un peu de détail mais conserve la structure essentielle. En pratique, ça signifie que Claude Code peut maintenir une cohérence sur des sessions de 4-5 heures avec des dizaines de fichiers modifiés, là où un usage naïf du contexte aurait planté au bout de 20 minutes.

Que sont les cache-aware boundaries et pourquoi changent-elles tout ?

La troisième couche est la plus technique et probablement la plus sous-estimée. Les cache-aware boundaries sont un système d'optimisation qui aligne le contenu du contexte sur les frontières du cache de l'API Claude. Et c'est un game-changer en termes de coûts et de performance.

Comme l'explique Penligent dans son analyse technique du source map, l'API Claude utilise un système de prompt caching : si le début de ton prompt est identique à un appel précédent, les tokens cachés sont facturés à prix réduit (jusqu'à 90% moins cher) et traités plus rapidement.

Le principe : stabiliser le début du contexte

L'idée est simple mais l'implémentation est subtile. Claude Code organise le contexte envoyé à l'API de façon à ce que les éléments stables soient toujours au début :

1. System prompt + MEMORY.md (quasi-statique)
2. Résumé de compaction (change rarement)
3. Fichiers de référence (changent occasionnellement)
4. Conversation récente + diffs (change à chaque appel)

En plaçant les éléments les plus stables en premier, Claude Code maximise la portion du prompt qui correspond au cache. Le code source montre que le système calcule explicitement des « boundaries » — des points de coupure dans le contexte qui correspondent aux frontières du cache de l'API.

Impact concret sur les coûts et la latence

D'après les chiffres extraits du code source et corroborés par VentureBeat, ce système de cache-aware boundaries permet de réduire les coûts API de 40 à 60% sur une session typique. La latence est aussi impactée : un cache hit évite de retraiter les tokens cachés, ce qui réduit le time-to-first-token de manière significative.

Concrètement, quand tu tapes une commande dans Claude Code et que la réponse arrive en 2-3 secondes au lieu de 8-10, c'est en grande partie grâce à ce système. Les cache-aware boundaries sont ce qui rend Claude Code utilisable en mode interactif sur de gros projets sans exploser ta facture. Pour une vue complète de toutes les optimisations cachées, consulte notre article sur les 10 features cachées révélées par le leak.

Comment en tirer parti dans ta pratique

Maintenant que tu sais comment ça fonctionne, voici comment optimiser ton usage :

• Garde ton MEMORY.md stable : évite de le modifier constamment, chaque modification invalide le cache du system prompt
• Travaille par blocs thématiques : plutôt que de sauter entre des fichiers sans rapport, concentre-toi sur un domaine à la fois pour maximiser les cache hits sur les fichiers de référence
• Ne relance pas de session inutilement : chaque nouvelle session repart avec un cache vide. Utilise la commande /compact plutôt que de quitter et relancer
• Structure tes instructions de façon répétitive : si tu donnes toujours le même type d'instruction (ex: « refactore ce fichier en suivant nos conventions »), le début du message sera caché

Pour aller plus loin sur ces techniques, notre guide complet Claude Code couvre tous les aspects pratiques.

Comment configurer ces 3 couches pour ton projet dès maintenant ?

Maintenant que tu comprends l'architecture, passons à la pratique. Voici un plan d'action concret pour exploiter chaque couche de mémoire sur ton propre projet.

Étape 1 : Créer un MEMORY.md optimisé

Crée un fichier .claude/MEMORY.md à la racine de ton projet. Suis ces règles :

• Une information par ligne, max 150 caractères
• Organise par sections : Project, Stack, Conventions, Architecture, Testing
• Inclus les décisions non-évidentes (pourquoi tel pattern, pas juste lequel)
• Mets à jour après chaque décision architecturale majeure

Exemple minimal pour un projet Next.js :

# Project
- Next.js 15 App Router, TypeScript strict
- Monorepo turborepo: apps/web, packages/ui, packages/db

# Conventions
- Server Components by default, 'use client' only when needed
- Colocation: component + test + styles in same folder
- Zod schemas in /schemas, shared between client/server

# Architecture
- Auth: NextAuth v5 with database sessions
- State: React Query for server, Zustand for client
- No Redux, no Context for global state

Étape 2 : Maîtriser le rythme de compaction

Tu ne contrôles pas directement quand l'auto-compaction se déclenche, mais tu peux influencer son efficacité :

• Utilise /compact manuellement quand tu changes de sujet dans une session — ça force une compaction propre avant de passer à autre chose
• Donne du contexte narratif : avant un gros refactoring, dis à Claude Code « Nous allons refactorer le module auth pour passer de JWT à sessions. Les fichiers concernés sont X, Y, Z. » Ce contexte sera préservé dans le résumé de compaction.
• Vérifie le résumé : après une compaction automatique, demande « résume ce que tu sais de notre session » pour vérifier que rien d'important n'a été perdu

Étape 3 : Optimiser pour le cache

Pour maximiser les cache hits :

• Crée un fichier .claude/instructions.md avec tes instructions récurrentes — il est chargé dans la partie stable du prompt
• Utilise des commandes slash personnalisées (/project:review, /project:test) plutôt que de retaper les mêmes instructions
• Évite de modifier le MEMORY.md en cours de session sauf nécessité absolue

En combinant ces trois optimisations, tu peux réduire significativement ta consommation de tokens tout en améliorant la qualité des réponses de Claude Code. C'est l'un des avantages les plus concrets révélés par ce leak, comme le confirme The Hacker News dans son analyse.

Meydeey — Architecte IA

+28 000 abonnés YouTube.