Ajouter une mémoire de session comme dans OpenClaw

Fini de ré-expliquer le contexte à chaque session. Claude retient automatiquement ce que vous avez fait, les décisions prises, les problèmes rencontrés — par projet, dans votre repo git, sans base de données. Portable, versionnable, moins d'1 $/mois. Voici comment mettre en place ce système en moins d'une heure.

Publié le 2026-03-22 · Laurent D.

Lundi matin. Vous ouvrez Claude Code sur un bug complexe que vous aviez laissé en suspens vendredi. Claude ne se souvient de rien. Vous ré-expliquez le contexte, re-décrivez l'architecture, re-listez ce qui a été essayé. Quinze minutes perdues avant de pouvoir reprendre où vous en étiez.

C'est exactement le problème que résout la mémoire de session — et c'est ce qu'OpenClaw a résolu en premier.

Qu'est-ce qu'OpenClaw ?

OpenClaw est un framework open source conçu pour Claude Code. Son objectif : transformer Claude d'un assistant sans mémoire en un agent autonome persistant, capable de se souvenir de ce qu'il a fait, de ce qui a été décidé, et de ce qui reste à faire.

OpenClaw fonctionne entièrement en Markdown et Python, sans base de données, sans dépendance externe. Sa philosophie : les fichiers plats, versionnables et lisibles par un humain, sont la meilleure mémoire à long terme.

Son architecture mémoire repose sur trois niveaux : - Mémoire immédiate — le contexte chargé dans la session courante - Logs quotidiens — ce qui s'est passé aujourd'hui (et hier) - Mémoire long terme — les faits durables, condensés et maintenus à jour

J'ai adapté cette architecture pour mes projets Claude Code : un Stop hook qui tourne automatiquement après chaque échange, deux fichiers Markdown par projet (long_memory.md + un log par jour), et deux skills pour charger et consolider la mémoire. Voici comment ça fonctionne et comment le mettre en place.

Pourquoi c'est un vrai plus par rapport à Claude par défaut

Claude Code dispose bien d'une mémoire automatique native — mais elle a deux limites importantes :

	Mémoire auto Claude Code	Système OpenClaw-style
Emplacement	`~/.claude/projects/...` (machine locale)	Dans le repo git du projet
Portabilité	Non — liée à la machine	Oui — suit le repo partout
Versionnement	Non	Oui — `git log` sur la mémoire
Granularité	Globale	Par projet / sous-projet
Inspectable	Difficilement	Markdown lisible directement

Le CLAUDE.md est une autre solution, mais c'est un fichier de règles statiques — pas un journal d'activité. Il ne trace pas ce qui a été fait, les problèmes rencontrés, ni les décisions prises en cours de session.

La mémoire de session comble ce vide : elle capture automatiquement, à chaque échange, ce qui s'est passé. Sans que vous ayez à y penser.

Architecture

Le système repose sur deux types de fichiers Markdown, un hook Stop, et un modèle Haiku qui fait l'extraction.

Structure des fichiers

projet/
  memory_sessions/
    long_memory.md          ← mémoire long terme (condensé permanent)
    logs/
      2026-03-22.md         ← log quotidien structuré par sections
      2026-03-21.md
      archives/             ← logs > 30 jours
      .debug/               ← JSON brut Haiku (gitignored)

Pour un workspace multi-projets, chaque sous-projet a son propre répertoire memory_sessions/ — la mémoire de cmms_doc ne se mélange pas avec celle de competitors.

Template 1 — Le log quotidien (`logs/2026-03-22.md`)

Un fichier par jour, structuré en sections fixes. Haiku y ajoute des bullets à chaque échange — sans jamais dupliquer ce qui existe déjà.

# Log session — 2026-03-22

## Contexte
- Refonte du système de mémoire de session pour le workspace PRODUCT_AGENTS.

## Objectif
- Tester le nouveau format JSON structuré retourné par Haiku.

## Problèmes rencontrés
- Extraction du transcript échouait : messages tool_result filtrés incorrectement.

## Connaissances acquises
- Le transcript JSONL contient beaucoup de messages à contenu vide (tool_use, thinking) — filtrer sur `content[].type == "text"`.

## Travail produit
- Réécriture du parser de transcript dans memory-session.sh.
- Ajout du répertoire .debug/ pour inspecter le JSON brut Haiku.

## Décisions prises
- Appeler `claude` depuis `/tmp` pour éviter que le CLAUDE.md du projet interfère.

## À suivre
- Valider que la découverte des skills fonctionne après le patch.

## Finalisé
- ✅ Valider que la découverte des skills fonctionne après le patch.

Chaque section a un rôle précis. La section Finalisé reçoit les points résolus de « À suivre » — déclenchés quand vous envoyez OK-done à Claude.

Template 2 — La mémoire long terme (`long_memory.md`)

Un condensé permanent, limité à 300 lignes. Ce n'est pas un log — c'est ce que Haiku juge durable : faits techniques, règles métier, décisions structurantes.

# Mémoire long terme — cmms_doc

## 2026-03-09
- Le hook memory-session.sh doit appeler `claude` depuis /tmp (pas depuis le projet) pour éviter l'injection du CLAUDE.md hôte dans la réponse Haiku.
- Format intermédiaire retenu : JSON structuré par sections → Python formate le Markdown.
- Déduplication gérée par Haiku qui relit le log existant avant d'écrire.

Quand long_memory.md dépasse 300 lignes, le skill /memory_promotion consolide et archive les entrées les plus anciennes.

Le mécanisme : le log quotidien nourrit la mémoire long terme

Échange Claude
    ↓
Haiku analyse : quoi retenir dans le log du jour ?
    ↓
Log quotidien mis à jour (sections append, déduplication)
    ↓
Si fait durable détecté → long_memory.md mis à jour
    ↓
/memory_promotion (hebdo/mensuel) → archive les logs anciens,
    consolide long_memory.md si > 300 lignes

Le flux du hook (version simplifiée)

Le déclencheur central est un Stop hook — un script Shell qu'exécute automatiquement Claude Code à la fin de chaque tour de conversation.

Claude répond
    ↓
Stop hook déclenché (settings.json)
    ↓
[Anti-boucle] stop_hook_active = true ? → exit 0
    ↓
Parser le transcript JSONL → extraire le dernier échange humain + assistant
    ↓
Lire les logs existants du jour (pour ne pas dupliquer)
    ↓
Appeler Haiku depuis /tmp avec le prompt structuré
    ↓
Haiku retourne un JSON par sections (objectif, problèmes, travail…)
    ↓
Python fusionne dans le log Markdown du jour
    ↓
exit 0

L'anti-boucle mérite une explication : quand le hook appelle claude, cette invocation se termine et re-déclenche le Stop hook. Claude Code injecte alors stop_hook_active: true dans le JSON stdin. Le hook détecte ce flag en premier et sort immédiatement, sans traitement.

Pourquoi appeler claude depuis /tmp ? Si le hook s'exécute depuis le répertoire du projet, le CLAUDE.md du projet est injecté dans le contexte de Haiku. Résultat : Haiku suit vos règles métier au lieu de retourner du JSON pur. Appeler depuis /tmp neutralise cet effet.

Comment mettre en place le système

1. Les skills de mémoire

Deux skills complètent le hook :

/memory_load [projet] — à appeler en début de session. Lit long_memory.md + les logs du jour et de la veille. Affiche un résumé consolidé. Ce chargement est manuel — la mémoire est enregistrée automatiquement, mais elle ne se recharge pas toute seule.
/memory_promotion [projet] — consolide les logs récents vers long_memory.md et archive les logs de plus de 30 jours. À lancer manuellement, une fois par semaine ou par mois selon votre activité.

Les skills sont des fichiers Markdown dans .claude/skills/{nom}/SKILL.md. Claude Code les reconnaît comme commandes /nom.

2. Brancher le hook Stop

Le hook Stop est déclaré dans .claude/settings.json :

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/memory-session.sh" }
        ]
      }
    ]
  }
}

Quand le Stop hook se déclenche-t-il ? Claude Code déclenche Stop à la fin de chaque tour — c'est-à-dire après chaque réponse complète de Claude, qu'elle soit simple (une phrase) ou complexe (avec des appels d'outils). C'est différent de la fin de session : le hook tourne après chaque échange, pas seulement quand vous fermez Claude Code.

3. Adapter la liste des projets

Dans le hook, une variable PROJECT_PATHS liste les répertoires mémoire de chaque sous-projet :

PROJECT_PATHS = {
    "root": "memory_sessions",
    "cmms_doc": "projects/cmms_doc/memory_sessions",
    "competitors": "projects/competitors/memory_sessions",
}

Haiku analyse l'échange et détermine aux projets concernés — puis écrit dans les bons fichiers.

4. Coût

Haiku 4.5 est délibérément choisi : rapide (~1-2 secondes) et économique. Avec une utilisation intensive de 20 échanges par jour, le coût reste sous 1 $/mois. C'est négligeable pour ce que ça apporte.

Ce que ça change concrètement

Avec ce système en place :

Reprise après week-end : /memory_load en début de session → Claude connaît l'état du bug, les décisions prises, ce qui restait à faire.
Multi-projets : chaque sous-projet a sa propre mémoire. Travailler sur cmms_doc puis competitors dans la même session → les logs sont séparés.
Traçabilité : l'historique des décisions techniques est dans le repo. git log memory_sessions/ raconte l'évolution du projet.
Portabilité : cloner le repo sur une autre machine, la mémoire est là.

Limitation principale

/memory_load est manuel. La mémoire est capturée automatiquement en fin de tour, mais elle ne se recharge pas toute seule au démarrage d'une nouvelle session. Il faut penser à lancer /memory_load en début de session pour en bénéficier.

C'est un choix délibéré — forcer le chargement automatique risquerait de polluer le contexte de sessions courtes ou sans rapport avec le projet.

Pièces jointes

La spécification technique complète (code complet du hook, format JSON, choix d'implémentation, bugs connus) est disponible en pièce jointe :

→ spec_session_memory.md

Exemple concret — log quotidien réel : le fichier ci-dessous est le log de session généré automatiquement le jour où cet article a été rédigé. Il illustre ce que le système capture réellement à chaque échange : contexte, travail produit, décisions prises, points à suivre.

→ session-log-exemple.md

Pour en savoir plus

Du fichier unique au système de contextes : pourquoi la mémoire d'un LLM ne tient pas dans un seul document Un fichier, des directives, et Claude fait le reste — comment j'ai structuré 500 mails sans effort

Clé JSON	Titre Markdown	Contenu	Comportement fusion
`contexte`	`## Contexte`	Sujet/système de la session (1-2 phrases)	Append (dédupliqué) — plusieurs contextes possibles par jour
`objectif`	`## Objectif`	Ce sur quoi porte la session	Append (dédupliqué)
`problemes`	`## Problèmes rencontrés`	Bugs, blocages, erreurs — avec cause/solution si connue	Append (dédupliqué)
`connaissances`	`## Connaissances acquises`	Faits techniques ou métier appris/confirmés	Append (dédupliqué)
`travail`	`## Travail produit`	Ce qui a été livré, créé, modifié	Append (dédupliqué)
`decisions`	`## Décisions prises`	Choix techniques ou fonctionnels actés	Append (dédupliqué)
`a_suivre`	`## À suivre`	Points ouverts, prochaines étapes	Append (dédupliqué)
`a_suivre_done`	(pas de section propre)	Points de "À suivre" à marquer comme résolus → déplacés vers "Finalisé"	Retrait de "À suivre" + ✅ dans "Finalisé"

Fichier	Règle
`logs/YYYY-MM-DD.md`	Structuré par sections — append de nouveaux bullets sans duplication
`long_memory.md`	Maximum 300 lignes — résumé automatique si dépassement (via `/memory_promotion`)
Archive	Logs > 30 jours déplacés vers `logs/archives/`
`.debug/`	JSON brut Haiku, gitignored, utile pour diagnostic

Composant	Fichier	Déclenchement
Stop hook	`.claude/hooks/memory-session.sh`	Automatique — fin de chaque tour Claude
Skill load	`.claude/skills/memory_load/SKILL.md`	Manuel — `/memory_load [projet]`
Skill promotion	`.claude/skills/memory_promotion/SKILL.md`	Manuel — `/memory_promotion [projet]`

Choix	Décision	Raison
Modèle	Haiku 4.5	Rapide (~1-2s), coût minimal, suffisant pour extraction/classification
Appel Claude depuis `/tmp`	Oui	Le CLAUDE.md du projet hôte interdit à Haiku de répondre en JSON pur
Format intermédiaire	JSON structuré par sections → Python formate le Markdown	Séparation claire extraction/formatage, debug facile
Déduplication	Haiku relit le log existant + append sous la même section	Pas de réécriture/fusion — robuste et simple
`flock`	Optionnel (dégradation gracieuse)	Non installé par défaut sur macOS — `brew install util-linux`
Fichiers temporaires	`mktemp -d` avec `trap EXIT`	Évite l'injection de variables shell dans les heredocs Python
Debug JSON	Copie dans `.debug/` (gitignored)	Diagnostic facile sans polluer le dépôt
Mémoire par projet	Oui	Un workspace peut contenir plusieurs sous-projets indépendants
`long_memory.md` (pas `memory.md`)	Oui	Évite la collision avec les `memory.md` existants dans les sous-projets
`memory_sessions/` (pas `memory/`)	Oui	Évite la collision avec les répertoires `memory/` existants
Versionnement	Oui (dans git)	Portabilité entre machines, historique des mémoires

Prérequis	Détail	Installation
Claude Code CLI	`claude` disponible dans PATH	claude.ai/code
Python 3	Stdlib uniquement (json, pathlib, re) — aucun package tiers	pré-installé macOS / `brew install python`
`flock`	Optionnel (dégradation gracieuse si absent)	`brew install util-linux` (macOS) / pré-installé Linux
Homebrew	Gestionnaire de paquets macOS — nécessaire pour `util-linux`	`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
Dépôt git	Pour la portabilité des fichiers `memory_sessions/`	`git init` ou clone

Bug	Cause	Solution
`--stop-hook-active` invalide	Ce flag n'existe pas dans le CLI `claude` — il est uniquement dans le JSON stdin du hook	Supprimé du call CLI
CLAUDE.md interfère	Quand `claude` est appelé depuis le projet, le CLAUDE.md du projet est injecté et modifie la réponse Haiku	Appeler `claude` depuis `/tmp`
Messages vides extraits	Le transcript JSONL contient beaucoup de messages `tool_result`/`thinking` avec `text` vide	Filtrer sur `content[].type == "text"` et ignorer les messages sans texte réel
`flock` absent (macOS)	`flock` vient de `util-linux`, non installé par défaut sur macOS	Dégradation gracieuse : `if command -v flock` avant d'utiliser
Variable shell dans heredoc Python	`"""$VAR"""` dans un heredoc casse si `$VAR` contient des guillemets ou caractères spéciaux	Utiliser des fichiers temporaires (`mktemp`) passés en arguments
`--no-streaming` invalide	Ce flag n'existe pas dans le CLI `claude`	Supprimé — `--print` suffit

Métrique	Valeur
Tokens input estimés	198 000
Tokens output estimés	56 000
Coût pondéré total	478 000 unités
Étape la plus coûteuse	Phase 5 — Lecture analyses + génération fiches concurrent (31%)
Modèle recommandé	Opus 4.6

Facteur	2026-03-07	2026-03-24	Impact
SKILL.md	18 158 B	27 564 B (+52%)	+2 352 tokens contexte
Analyses en base	88	138 (+57%)	+coût phases 5 et 7
Opt. 1 (frontmatter Python)	non impl.	✓ implémentée	-58 350 unités
Opt. 3 (_index.json delta)	non impl.	✓ implémentée	-52 900 unités
Opt. 2 (fiches incrémentales)	non impl.	non impl.	—
Opt. 4 (thèmes incrémentaux)	non impl.	non impl.	—
Opt. 5 (extraire templates)	non impl.	non impl. + SKILL.md a grossi	coût aggravé

#	Étape	Type	Tokens in	Tokens out	Coût pondéré	% total
0	Contexte système (SKILL.md 27 564 o + CLAUDE.md 934 o)	Input fixe	7 125	0	7 125	1%
0b	Read _index.json (~66 000 o, base 138 analyses)	Read	16 500	0	16 500	3%
1-2	Scan + validation data/in/	Bash + Raison	0	50	250	0%
3a	Read documents source (×5, avg 5 000 tok)	Read	25 000	0	25 000	5%
3b	Read template analysis-prompt.md (×5)	Read	2 550	0	2 550	1%
3d-f	Génération 5 analyses (avg 2 334 tok)	Write	0	11 670	58 350	12%
3bis-b	Classification thèmes + AskUser (×5)	Raisonnement	0	500	2 500	1%
3bis-c	update_frontmatter.py (×5)	Bash (Python)	0	0	0	0%
4	Récapitulatif tableau	Write	0	500	2 500	1%
5a-b	Read TOUTES analyses 3 concurrents (138 total, 3 affectés)	Read	102 180	0	102 180	21%
5c	Read fiches existantes (×2)	Read	6 928	0	6 928	1%
5d-e	Génération/régénération 3 fiches	Write	0	10 392	51 960	11%
6	Analyses temporelles (×2 trimestres)	Write	0	375	1 875	0%
7a	Read définitions thèmes (×5)	Read	2 031	0	2 031	0%
7b	Read analyses par thème (×5, ~18 analyses/thème)	Read	40 500	0	40 500	8%
7c	Génération 5 analyses thématiques	Write	0	13 565	67 825	14%
7bis	update_index.py delta (Python)	Bash (Python)	0	0	0	0%
7bis-write	Write _index_delta.json (delta uniquement, ~3 000 o)	Write	0	750	3 750	1%
7ter	Regénération 5 README	Write	0	625	3 125	1%
8	Messages conversation utilisateur	Input	3 670	0	3 670	1%
Total			206 484	38 427	~398 619

Type	Nombre	Taille totale	Tokens moyens
Analyses individuelles	138	~1 287 000 B	~2 334
Fiches concurrent	8	~110 840 B	~3 464
Analyses thématiques	estimé 25	~271 250 B	~2 713
Analyses temporelles	estimé 12	~8 988 B	~187
_index.json	1	~66 385 B	~16 596

Scénario	Tokens in	Tokens out	Coût pondéré	Gain vs précédent audit
Précédent (2026-03-07, 88 analyses)	182 001	80 650	585 251	référence
Actuel (2026-03-24, 138 analyses, opt 1+3 impl.)	206 484	38 427	398 619	-32%
Optimisé (opt. 3+4+5 restantes)	101 000	34 000	271 000	-54% vs précédent

Ajouter une mémoire de session comme dans OpenClaw

Qu'est-ce qu'OpenClaw ?

Pourquoi c'est un vrai plus par rapport à Claude par défaut

Architecture

Structure des fichiers

Template 1 — Le log quotidien (logs/2026-03-22.md)

Template 2 — La mémoire long terme (long_memory.md)

Le mécanisme : le log quotidien nourrit la mémoire long terme

Le flux du hook (version simplifiée)

Comment mettre en place le système

1. Les skills de mémoire

2. Brancher le hook Stop

3. Adapter la liste des projets

4. Coût

Ce que ça change concrètement

Limitation principale

Pièces jointes

Pour en savoir plus

Log session — 2026-03-22

Contexte

Objectif

Connaissances acquises

Travail produit

Décisions prises

À suivre

Finalisé

Spec : système memory_sessions

Modèle d'installation

Présentation

Pourquoi ce système ?

Inspiration : OpenClaw

Architecture

Structure de fichiers

Format du log quotidien

Format JSON intermédiaire (Haiku → Python)

Gestion "OK-done"

Debug JSON

Règles de taille

Composants

Flux du hook

Format JSONL du transcript Claude Code

Anti-boucle

Choix d'implémentation

Prérequis

Installation complète sur macOS

Installation dans un nouveau projet

Étape 1 — Copier le hook

Étape 2 — Adapter la liste des projets

Étape 3 — Enregistrer le hook dans settings.json

Étape 4 — Créer les répertoires et configurer .gitignore

Étape 5 — Copier les skills (optionnel mais recommandé)

Skills

/memory_load [projet]

/memory_promotion [projet]

Code complet

.claude/hooks/memory-session.sh

.claude/skills/memory_load/SKILL.md

.claude/skills/memory_promotion/SKILL.md

Bugs connus et solutions

Spec : skill token_audit

Modèle d'installation

Présentation

Prérequis projet

Fichiers à créer

1. .claude/skills/token_audit/SKILL.md

Étape 7 — Mettre à jour l'index README.md

Gestion des erreurs

3. Ligne à ajouter dans docs/skills/README.md

Instructions d'installation

Test de validation

Audit tokens : competitor_analyze

Résumé

Évolution depuis l'audit 2026-03-07

Détail par étape

Tailles de référence actualisées

Optimisations proposées

1. ✓ Déjà implémentée — Frontmatter Python (étape 3bis-c)

2. ✓ Déjà implémentée — _index.json delta Python (étape 7bis)

3. Synthèse incrémentale des fiches concurrent — Gain estimé : ~14%

4. Analyses thématiques incrémentales — Gain estimé : ~10%

Template 1 — Le log quotidien (`logs/2026-03-22.md`)

Template 2 — La mémoire long terme (`long_memory.md`)

`/memory_load [projet]`

`/memory_promotion [projet]`

`.claude/hooks/memory-session.sh`

`.claude/skills/memory_load/SKILL.md`

`.claude/skills/memory_promotion/SKILL.md`

1. `.claude/skills/token_audit/SKILL.md`

3. Ligne à ajouter dans `docs/skills/README.md`