Mémoire persistante pour Claude Code : comment fonctionne réellement le contexte entre les sessions

Le problème central : les sessions sont sans état par conception

Une session Claude Code est une conversation. Lorsqu’elle se termine, la transcription est archivée et le contexte de travail — la compréhension accumulée au fil de dizaines d’appels d’outils — s’évapore. La session suivante reconstitue le contexte à partir de trois sources :

• Votre CLAUDE.md files (project and user scope)
• Les fichiers que Claude lit pendant la session
• Ce que vous saisissez

Aucune de ces sources ne capture les connaissances déduites : les impasses que vous avez déjà explorées, la raison d’être d’un contournement étrange, le fait que vous avez essayé l’approche A et qu’elle a cassé la CI. Reconstituer ces connaissances coûte des tokens et du temps réel à chaque session.

Le réflexe consiste à construire une couche de mémoire : capturer ce qui s’est passé, le condenser et réinjecter la partie pertinente au démarrage. Le projet open source claude-mem est une implémentation de référence claire de ce modèle précis, et mérite d’être étudié, que vous l’adoptiez ou non.

Le modèle d’architecture derrière la mémoire persistante de Claude Code

Toute approche sérieuse de la mémoire persistante dans Claude Code suit la même boucle en trois étapes. Comprendre chaque étape séparément vous permet de choisir de la développer, d’acheter une solution ou de vous en passer.

Étape 1 : Capturer

Vous devez observer ce qui s’est passé au cours d’une session. Claude Code expose des hooks de cycle de vie hooks — des commandes shell qui se déclenchent lors d’événements. Voici les hooks pertinents :

Un hook de capture minimal dans .claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/mem/capture.sh"
          }
        ]
      }
    ]
  }
}

Le hook reçoit sur l’entrée standard un contenu JSON décrivant l’événement. Pour SessionEnd vous obtenez l’identifiant de session et le chemin de la transcription, ce qui permet à capture.sh de lire l’intégralité du journal de conversation :

#!/usr/bin/env bash
INPUT=$(cat)
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path')
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

# Hand the raw transcript to the compression stage
python3 "$CLAUDE_PROJECT_DIR/.claude/mem/compress.py" \
  --transcript "$TRANSCRIPT" \
  --session "$SESSION_ID"

Un piège courant : les hooks s’exécutent avec un délai maximal, et une longue transcription transmise de manière synchrone à un LLM le dépassera largement. En pratique, la capture doit être lancée sans attendre son résultat : placez le chemin de la transcription dans une file d’attente et traitez-la avec un processus en arrière-plan, plutôt que directement dans le hook.

Étape 2 : Compresser

Les transcriptions brutes sont inutilisables comme mémoire : elles sont énormes et pleines de bruit (contenus de fichiers, avalanche d’appels d’outils, vos fautes de frappe). L’étape de compression utilise un LLM pour extraire de la session des faits durables. C’est ici qu’il faut utiliser un appel à Haiku 4.5, plutôt qu’à Opus : la synthèse est exactement le type de tâche à fort volume et à faible enjeu auquel la tarification de Haiku convient.

import anthropic

client = anthropic.Anthropic()

PROMPT = """You are a memory compressor. From this coding session
transcript, extract ONLY durable facts worth remembering next session:
- Architectural decisions and their rationale
- Conventions discovered (naming, error handling, imports)
- Dead ends already explored (so we don't repeat them)
- Unresolved TODOs

Output JSON: a list of {fact, category, files[], confidence}.
Omit anything transient. If nothing durable happened, output []."""

resp = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1500,
    system=PROMPT,
    messages=[{"role": "user", "content": transcript_text}],
)
memories = resp.content[0].text

Notez le champ confidence et l’instruction explicite de produire []. Ces deux éléments limitent les dégâts du mode de défaillance que nous aborderons plus loin. Stockez le résultat dans un système interrogeable : SQLite avec une colonne d’embeddings, ou une base vectorielle indexée par projet et chemins de fichiers.

Étape 3 : Injecter

Au début de la session, vous récupérez les souvenirs pertinents et les injectez. Le hook SessionStart peut écrire sur la sortie standard, et ce contenu est ajouté au contexte de Claude :

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/mem/inject.sh" }
        ]
      }
    ]
  }
}

La décision technique cruciale concerne le filtrage par pertinence. Injecter toute la mémoire est une approche naïve et inadaptée : cela fait gonfler votre contexte et noie les faits utiles. Mieux vaut récupérer les souvenirs en fonction du sujet probable de la session. Si vous ne pouvez pas encore le déterminer, injectez uniquement les faits à haut niveau de confiance qui concernent l’ensemble du projet, et rendez le reste accessible via un serveur MCP pour que Claude puisse interroger la mémoire à la demande :

# A tiny MCP tool the agent calls when it wants history
@mcp.tool()
def recall(query: str, files: list[str] = []) -> list[dict]:
    """Retrieve relevant memories about this codebase."""
    return memory_store.search(query, files=files, min_confidence=0.6)

En pratique, ce modèle de récupération à la demande fonctionne mieux que l’injection systématique. Au lieu de deviner ce qui est pertinent au démarrage, vous laissez l’agent demander « avons-nous déjà travaillé sur ce code de facturation ? » précisément au moment où cela compte. Le hook fournit un petit résumé toujours présent dans le contexte ; le serveur MCP assure la récupération ciblée des souvenirs.

Là où cela échoue — car cela échoue bel et bien

J’utilise des couches de mémoire depuis assez longtemps pour m’en méfier. Les modes de défaillance sont réels et leurs effets se cumulent.

La mémoire compressée par l’IA hallucine. Le système de compression est lui-même un modèle de langage. Il lui arrive d’enregistrer une « décision » qui était en réalité une idée abandonnée, ou d’inverser la justification d’un choix. Vous vous retrouvez alors avec un faux souvenir au ton catégorique injecté au démarrage, auquel l’agent accorde trop de confiance. C’est pire que l’absence de mémoire, car l’erreur est présentée avec assurance. Le champ confidence et la vérification humaine du contenu de la mémoire sont les seuls véritables moyens d’atténuer ce risque.

Le contexte obsolète est un danger silencieux. Vous refactorisez UserService le mardi. Votre mémoire du lundi indique toujours « l’authentification se trouve dans UserService. » Rien ne l’invalide. Les souvenirs perdent en exactitude dès que le code change, et aucun signal clair ne permet de les faire expirer. Associez les souvenirs à des empreintes de fichiers ou à des SHA de commits, et considérez-les comme suspects lorsque le fichier sous-jacent est déplacé.

Les coûts en tokens augmentent à chaque session. La mémoire injectée constitue du contexte que vous payez à chaque échange, qu’il soit utilisé ou non. Une couche de mémoire qui injecte 4K tokens au démarrage ajoute cette quantité à votre coût d’entrée pendant toute la session. Le modèle MCP de récupération à la demande aide, mais la capture et la compression représentent elles aussi des dépenses récurrentes.

Voici une comparaison honnête :

La vérité dérangeante : vous n’en avez probablement pas besoin

Avant de développer tout cela, rédigez un bon CLAUDE.md. Un fichier soigneusement rédigé à la main qui indique « nous utilisons Result<T>, ne jamais lever d’exception ; UserService ne doit pas importer billing/; l’authentification a été déplacée vers auth/ au deuxième trimestre » résout 80 % du problème de mémoire sans aucun risque d’hallucination et avec un coût déterministe. Il est rédigé par un humain, ce qui le rend fiable par construction.

Les couches de mémoire justifient leur coût dans un éventail de situations plus restreint que ne le laisse entendre l’engouement actuel : les travaux exploratoires de longue durée où les connaissances déduites (impasses, investigations inachevées) ne peuvent réellement pas être rédigées à l’avance, puisque vous ne les avez pas encore acquises. Pour le développement courant de fonctionnalités, CLAUDE.md associé à quelques serveurs MCP à périmètre limité couvre davantage de besoins qu’un pipeline de mémoire automatisé, et ne vous ment jamais.

Si vous développez ce pipeline, c’est à l’étape de compression que la maîtrise des coûts compte le plus : effectuer fréquemment des synthèses avec Haiku est peu coûteux, mais seulement si votre tarif par token est raisonnable au départ. C’est l’une des raisons pour lesquelles les équipes font passer ce type de travail en arrière-plan à fort volume par des fournisseurs comme AI Prime Tech.

Conseils pratiques à retenir

• Les sessions sont sans état. Ce sont les connaissances acquises — impasses, justifications, conventions — qui sont réellement perdues, et les reconstituer coûte cher.
• Le schéma est : capturer → compresser → injecter. Reliez la capture et l’injection à l’aide de SessionEnd/SessionStart hooks ; effectuez la capture de manière asynchrone pour éviter de dépasser leurs délais d’exécution.
• Privilégiez la récupération à la demande plutôt que l’injection systématique. Fournissez un très court résumé au démarrage, puis exposez un outil recall MCP pour que l’agent récupère les souvenirs uniquement lorsqu’ils sont pertinents.
• Compressez avec Haiku 4.5, associez à chaque souvenir un niveau de confiance et les empreintes des fichiers sources, et considérez la mémoire comme suspecte lorsque les fichiers changent.
• La mémoire automatisée peut mentir. Un contexte halluciné ou obsolète est pire qu’une absence de contexte, car il fait autorité. Maintenez une supervision humaine du contenu de la mémoire.
• Essayez CLAUDE.md en premier. Pour la plupart des projets, un fichier de contexte rédigé à la main associé à des outils à périmètre limité surpasse une couche de mémoire complète en matière de coût, de fiabilité et de maintenance. Ne recourez à la persistance que si votre travail est réellement long et exploratoire.