Aller au contenu
Home » De MEMORY.md à un système hybride : optimiser la mémoire de Claude Code

De MEMORY.md à un système hybride : optimiser la mémoire de Claude Code

La mémoire par défaut de Claude Code fonctionne. Mais quand vous gérez plusieurs projets, des dizaines de sessions par semaine, et des centaines de décisions techniques, elle montre ses limites. Voici comment je l’ai progressivement transformée en un système hybride à 3 couches — fichiers curates, base relationnelle, et mémoire vectorielle — et comment vous pouvez faire pareil.

Pourquoi optimiser la mémoire ?

Par défaut, Claude Code utilise un fichier MEMORY.md ou il écrit tout : préférences, faits techniques, décisions, feedback. Ça fonctionne pour un projet simple. Mais avec le temps, trois problèmes apparaissent :

  1. Le fichier grossit et consomme du contexte inutilement. Seules les 200 premières lignes (~25KB) de MEMORY.md sont chargées au démarrage. Au-delà, le contenu est invisible sauf si Claude decide de le relire. Et quand il le relit, tout le fichier entre dans le contexte — y compris les informations non-pertinentes pour la tâche en cours.

  2. Tout est mélangé. Les credentials côtoient les décisions d’architecture, les préférences de style, les procédures de déploiement. Difficile de maintenir, facile de créer des contradictions.

  3. Pas de recherche. Pour retrouver « pourquoi on a choisi Zod v3 pour le backend », il faut lire tout le fichier séquentiellement. Pas de full-text search, pas de recherche sémantique, pas de filtrage par projet ou par date.

La démarche que je vais décrire suit une progression en 3 étapes, chacune ajoutant une couche au système précédent :

Étape 1 : Splitter les fichiers .md (maintenabilité + contexte à la demande)
     |
     v
Étape 2 : Ajouter SQLite (faits structurés + requêtes)
     |
     v
Étape 3 : Ajouter claude-mem (capture automatique + recherche sémantique)

Rappel : comment fonctionne la mémoire native

Avant de l’optimiser, il faut comprendre les mécanismes natifs de Claude Code.

CLAUDE.md : le briefing permanent

Un fichier markdown lu automatiquement au début de chaque session. Trois niveaux :

Niveau Emplacement Portée Versionne ?
Organisation /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) Tous les utilisateurs Non
Projet ./CLAUDE.md ou ./.claude/CLAUDE.md Equipe (commite dans git) Oui
Utilisateur ~/.claude/CLAUDE.md Personnel, tous projets Non

Priorité : Organisation > Projet > Utilisateur. Maximum recommandé : ~200 lignes par fichier.

Détail important : les fichiers CLAUDE.md survivent à la compaction du contexte. Même après un /compact, Claude les relit et les reinjecté.

Auto-mémoire : Claude prend ses propres notes

Depuis la v2.1.59, Claude écrit dans ~/.claude/projects/<project>/memory/. Le <project> est déterminé par le dépôt git — tous les worktrees d’un même repo partagent la même mémoire.

Seules les 200 premières lignes de MEMORY.md sont chargées au démarrage. Les fichiers liés sont lus à la demande.

Auto-Dream : consolidation entre sessions

Mécanisme récent qui s’execute entre les sessions : scan, recherche de corrections/thèmes récurrents, fusion/nettoyage, mise à jour de l’index. Empêche la dégradation mémorielle.

Compaction automatique

A ~83.5% d’utilisation du contexte (1M tokens pour Opus 4.6), Claude compresse l’historique par resume. Les fichiers CLAUDE.md et mémoires sont reinjectés après compaction.

Étape 1 : Splitter les fichiers markdown

Le problème

Un MEMORY.md monolithique de 300 lignes où tout est mélangé. Claude charge les 200 premières lignes au démarrage — le reste est perdu sauf relecture explicite. Et quand il relit, tout entre dans le contexte même si seule une info précise est nécessaire.

La solution : un index + des fichiers thématiques

Transformer MEMORY.md en un index léger qui pointe vers des fichiers spécialisés. Claude ne charge que l’index au démarrage, puis lit les fichiers pertinents à la demande.

Avant (monolithique) :

memory/
└── MEMORY.md  (300+ lignes, tout mélangé)

Après (splitte) :

memory/
├── MEMORY.md              # Index (~50 lignes) — charge au démarrage
├── neuralpro.md           # Stack, routes, config d'un projet SaaS
├── webapp-vitrine.md      # Un autre projet (site web)
├── deployment.md          # Procedures de déploiement VPS
├── gws-cli.md             # Config Google Workspace
├── supabase_access.md     # Tokens et project refs
├── telegram.md            # Config bot Telegram
├── feedback_release_notes.md   # Style des release notes
├── feedback_terminology.md     # Vocabulaire métier
└── feedback_server_scope.md    # Sémantique des commandes

L’index MEMORY.md

L’index est organisé par thème, pas par date. Chaque entrée tient sur une ligne :

# Project Memory -- Index

## Projets
| Projet | Dossier | Stack | Détails |
|--------|---------|-------|---------|
| NeuralPro | `/Dev/NeuralPro/` | Express+Next.js+Supabase | `neuralpro.md` |
| Site Vitrine | `/Dev/webapp-vitrine/` | Next.js+next-intl | `webapp-vitrine.md` |

## Infrastructure
- [Deployment](deployment.md) -- VPS multi-projets (Docker + reverse proxy)

## Feedback
- [Release notes](feedback_release_notes.md) -- Utilisateur final, pas de jargon
- [Terminology](feedback_terminology.md) -- "calls" pas "appels" dans NeuralPro

Les fichiers thématiques

Chaque fichier est autonome et ciblé. Exemples :

neuralpro.md — tout ce qu’il faut savoir sur un projet :

# NeuralPro
- Stack: Express (backend:3001) + Next.js 16 (web:3000) + Supabase
- Auth: magic links via Supabase Auth
- Thème: dark-first, primary=#0EA5E9, glassmorphism
- Plans: Free (5/mo), Growth (200/mo, 99EUR), Enterprise
- Enrichment: Perplexity, Brave, Pappers, Firecrawl, Societe.com
- Zod: v3 backend (openai peer dep), v4 web/admin
- Tests: Vitest, 463 tests, TDD obligatoire
- Cache TTL: news 7j, official 30j, SIREN 90j

feedback_release_notes.md — une correction de comportement :

---
name: Release notes style
type: feedback
---
Les release notes doivent être orientées utilisateur final.
PAS de sections techniques (refactoring, type safety, architecture).
**Why:** L'utilisateur ne sait pas ce qu'est un "format string[]".
**How to apply:** "L'affichage est corrigé" et non "Fixed format string[] vs object[]".

Pourquoi ca marche

  • Contexte à la demande : quand Claude travaille sur NeuralPro, il lit neuralpro.md (30 lignes). Il ne charge pas deployment.md ni webapp-vitrine.md.
  • Maintenabilite : modifier les procédures de déploiement = éditer un seul fichier, pas chercher dans un monolithe.
  • Scalabilité : ajouter un projet = ajouter un fichier + une ligne dans l’index.

Les limites

  • Pas de recherche : Claude doit savoir quel fichier lire. Si l’info est dans un fichier inattendu, il ne la trouvera pas sans lire plusieurs fichiers.
  • Pas de structure pour les données répétitives (liste de facts, de décisions). Markdown n’est pas un format de requête.

Étape 2 : Ajouter SQLite pour les données structurées

Le problème

Certaines informations sont des faits atomiques : un port, une URL, un prix, une version. Les stocker en markdown, c’est gaspiller du contexte pour de la prose autour de données tabulaires. Et quand vous avez 30+ facts répartis sur 5 projets, retrouver un fait précis en lisant des fichiers .md devient pénible.

La solution : une base SQLite cohabitant avec les fichiers markdown

Ajouter un fichier memory.db dans le répertoire mémoire, à côté des fichiers markdown. Claude peut le requêter avec sqlite3.

memory/
├── MEMORY.md
├── neuralpro.md
├── deployment.md
├── ...
└── memory.db    # <-- nouveau

Le schema

4 tables, chacune pour un type d’information différent :

CREATE TABLE projects (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    path TEXT,
    domain TEXT,
    stack TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE facts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT REFERENCES projects(id),
    key TEXT NOT NULL,
    value TEXT NOT NULL,
    category TEXT,  -- thème, billing, infra, auth, stack, tests...
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE décisions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT REFERENCES projects(id),
    title TEXT NOT NULL,
    decision TEXT NOT NULL,
    reason TEXT,
    alternatives TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE problems (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT REFERENCES projects(id),
    description TEXT NOT NULL,
    solution TEXT NOT NULL,
    tags TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Ce que ca contient en pratique

Facts (33 enregistrements dans mon setup) :

neuralpro | backend_port     | 3001        | infra
neuralpro | stripe_price     | 99EUR/mois  | billing
neuralpro | test_count       | 463         | tests
neuralpro | primary_color    | #0EA5E9     | thème
neuralpro | smtp_host        | smtp.provider.fr:465 | infra
vitrine   | future_price     | $4.99/month | billing

Decisions (7 enregistrements) :

neuralpro | Zod v3 backend     | Garder zod@3 dans /src, zod@4 dans /web
          | Raison: peer dependency openai@4
neuralpro | Removed Google Search | Supprimé du pipeline d'enrichissement
          | Raison: 5 autres adaptateurs plus fiables

Problems (3 enregistrements) :

neuralpro | GoTrue résout users vers auth.users en PL/pgSQL
          | Solution: SET search_path=public + référence public.users
          | Tags: supabase, plpgsql, security

Comment Claude l’utilise

L’index MEMORY.md contient une instruction :

## Base SQLite
- `memory.db` -- Faits atomiques, décisions, problèmes résolus
- Requêter via : `sqlite3 memory/memory.db "SELECT ..."`

Quand Claude à besoin d’un fait précis, il fait :

sqlite3 memory.db "SELECT value FROM facts WHERE project_id='neuralpro' AND key='backend_port'"
# -> 3001

Cout en tokens : la requête + le résultat (~20 tokens). Contre la lecture d’un fichier markdown complet (~200-500 tokens).

Quand utiliser quoi

Type d’info Stockage Pourquoi
Procedures, workflows, contexte narratif Fichiers .md Le format prose aide à la comprehension
Feedback utilisateur, préférences de style Fichiers .md (feedback_*.md) La nuance et le « why » comptent
Faits atomiques (ports, URLs, versions, prix) SQLite facts Requetable, compact, pas de prose inutile
Decisions architecturales avec raison SQLite décisions Structure raison/alternatives
Bugs résolus avec solution SQLite problems Recherchable par tags
Credentials, tokens d’acces Fichiers .md dédiés Controle d’acces, éditable manuellement

Les limites

  • Pas de recherche sémantique (« les trucs qu’on à fait la semaine dernière avec Supabase »)
  • Pas de capture automatique — il faut écrire manuellement ou demander à Claude d’insérer
  • Pas d’historique de session — seuls les faits/décisions explicitement sauvegardés sont la

Étape 3 : Ajouter claude-mem (capture automatique + recherche sémantique)

Le problème

Les fichiers markdown et SQLite ne capturent que ce que vous pensez à sauvegarder. Or une session typique produit des dizaines de découvertes, de décisions, de solutions — dont la plupart ne seront jamais enregistrées parce qu’on ne pense pas à le faire sur le moment.

Et quand vous cherchez « comment on avait résolu ce bug de RLS la semaine dernière », ni grep sur les fichiers markdown ni SELECT sur SQLite ne vous aideront si l’information n’a jamais ete sauvegardée.

La solution : claude-mem

claude-mem (~40K stars GitHub, v10.6.3) est un plugin Claude Code qui ajouté une couche de capture automatique et de recherche sémantique. Il ne remplace pas les couches précédentes — il les complète.

Repo : https://github.com/thedotmack/claude-mem

Architecture technique

3 composants :

  1. Hooks lifecycle — interceptent automatiquement chaque événement de session :
  2. SessionStart : injecté le contexte des sessions passees
  3. PostToolUse : capture chaque appel d’outil (lecture, écriture, exécution)
  4. Stop : génère un résumé de la session (ce qui a ete investigue, appris, complète)

  5. SessionEnd : marque la session comme terminee

  6. Worker service — serveur Express.js en arriere-plan (port 37777, géré par Bun) :

  7. Recoit les observations des hooks
  8. Les envoie à un modèle IA pour compression (Haiku par défaut)
  9. Stocke dans SQLite + ChromaDB

  10. Expose une API de recherche et un viewer web

  11. Stockage dual :

  12. SQLite (source de vérité) : observations, sessions, résumés. Tables FTS5 pour recherche full-text.
  13. ChromaDB (recherche sémantique) : embeddings vectoriels des observations pour trouver du contenu par sens, pas par mots-clés.

La compression : le gain principal

Un appel d’outil brut génère 1,000 à 10,000 tokens. claude-mem le compresse en ~500 tokens :

Sortie brute d'outil (5,000 tokens)
         |
         v  Compression IA (Haiku)
         |
Observation structurée (~500 tokens) :
  title: "Fixed RLS policy on notifications table"
  narrative: "Investigation showed that..."
  facts: ["notifications table had no RLS", "Added policy for authenticated"]
  type: "bugfix"
  files_modified: ["supabase/migrations/001.sql"]

Deduplication par hash SHA-256 avec fenêtre de 30 secondes.

La divulgation progressive

claude-mem ne charge pas tout en mémoire. 3 niveaux :

Niveau Contenu Cout
Index ID, date, type, titre ~50-100 tokens/observation
Timeline Contexte chronologique autour d’un point Variable
Détail Narrative, faits, fichiers ~500-1,000 tokens/observation

Au démarrage, seules les 50 dernières observations apparaissent en mode index (niveau 1). Le detail est récupéré à la demande via les outils MCP.

Les outils de recherche

claude-mem expose 6 outils MCP que Claude peut appeler :

Outil Usage
search Recherche full-text + filtres (projet, type, date)
timeline Contexte chronologique autour d’une observation
get_observations Détail complet par ID
smart_search Exploration AST via tree-sitter
smart_outline Squelette structurel d’un fichier
smart_unfold Code source d’un symbole spécifique

Installation

# Via le marketplace Claude Code
/plugin install claude-mem
/reload-plugins

La première session après installation demarre le worker et crée la base ~/.claude-mem/claude-mem.db.

Configuration recommandée

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5",
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "50",
  "CLAUDE_MEM_SKIP_TOOLS": "SlashCommand,Skill,TodoWrite,AskUserQuestion,TaskCreate,TaskUpdate",
  "CLAUDE_MEM_CHROMA_ENABLED": "true"
}
  • Haiku pour la compression : rapide et économique (vs Sonnet qui coûte 10x plus)
  • 50 observations au démarrage : bon equilibre entre couverture et tokens
  • Skip tools etendu : exclure les outils de gestion (bruit sans valeur mémorielle)

Les limites

  • Opacite : les observations compressees ne sont pas facilement éditables
  • Dependances : Bun + ChromaDB (Python/uv) + daemon sur port 37777
  • Consommation : chaque observation = un appel IA pour la compression
  • Pas de curation : capture tout, y compris le bruit

C’est précisement pourquoi claude-mem ne remplace pas les couches précédentes mais les complète.

Le système hybride complet : 3 couches

+------------------------------------------------------------------+
|                    Claude Code Session                             |
|                                                                    |
|  COUCHE 1 -- Fichiers markdown curates                            |
|  Source de vérité pour les connaissances stables                   |
|  Charge : index au démarrage, fichiers à la demande               |
|  +-- MEMORY.md (index, ~50 lignes)                                |
|  +-- {projet}.md (stack, config, conventions)                     |
|  +-- {infra}.md (déploiement, serveurs, acces)                    |
|  +-- feedback_*.md (préférences, corrections de comportement)     |
|  +-- {credentials}.md (tokens, acces services)                    |
|                                                                    |
|  COUCHE 2 -- SQLite memory.db                                     |
|  Faits atomiques, décisions, problèmes résolus                     |
|  Charge : par requête (cout minimal en tokens)                    |
|  +-- facts (cle/valeur par projet et categorie)                   |
|  +-- décisions (choix + raison + alternatives)                    |
|  +-- problems (bug + solution + tags)                             |
|                                                                    |
|  COUCHE 3 -- claude-mem (automatique)                             |
|  Historique de session, recherche sémantique                       |
|  Charge : index au démarrage, detail à la demande                 |
|  +-- SQLite FTS5 (full-text search)                               |
|  +-- ChromaDB (recherche vectorielle/sémantique)                  |
|  +-- 6 outils MCP (search, timeline, smart_search...)             |
+------------------------------------------------------------------+

Regles de routage

Besoin Couche Pourquoi
Stack, ports, URLs d’un projet 1 (fichier .md) Narratif, donne le contexte complet
Un fait précis (version, prix, port) 2 (SQLite) ~20 tokens vs ~300 pour un fichier
Procedure de déploiement 1 (fichier .md) Format étape par étape, prose nécessaire
Préférence où correction de style 1 (feedback_*.md) Le « pourquoi » est essentiel
Credentials, tokens 1 (fichier .md dédié) Controle, éditable, jamais dans claude-mem
« Qu’est-ce qu’on à fait la dernière fois ? » 3 (claude-mem timeline) Historique automatique
« On à déjà vu ce bug ? » 3 (claude-mem search) Recherche sémantique cross-sessions
Decision architecturale avec raison 2 (SQLite décisions) Structuree, requêtable

Ce qu’il ne faut PAS dupliquer

  • Les observations de session dans les fichiers curates (claude-mem les capture)
  • Les credentials dans claude-mem (garder dans les fichiers curates uniquement)
  • Les informations dérivables du code ou de git (architecture, récent changes)

Adapter le setup par projet : un même système, des configs différentes

Le système hybride ne s’applique pas uniformement. Chaque projet peut avoir sa propre configuration de mémoire, adaptée à ses besoins.

Exemple 1 : /Dev/ (portfolio multi-projets)

C’est le contexte global qui couvre tous mes projets. Sa mémoire est généraliste :

memory/
├── MEMORY.md          # Index de 4 projets + infra + feedback
├── neuralpro.md       # Projet SaaS (Express+Next.js+Supabase)
├── webapp-vitrine.md  # Site web (Next.js+next-intl)
├── deployment.md      # VPS, 6+ containers Docker
├── gws-cli.md         # Google Workspace CLI
├── supabase_access.md # Tokens Supabase
├── feedback_*.md      # 3 fichiers de feedback
└── memory.db          # 33 facts, 7 décisions, 3 problems (65KB)

CLAUDE.md global (~/.claude/CLAUDE.md) : regles de priorite des skills, protocole hybride de mémoire (quelle couche pour quel besoin).

Permissions (settings.local.json) : larges — node, pip, ssh, supabase, stripe, GitHub CLI, PDF tools. C’est un contexte de travail quotidien multi-outils.

Exemple 2 : /Dev/DevTeam/ (orchestration multi-agents)

Contexte spécialisé pour coordonner 3 agents IA sur 6 sous-projets. La mémoire est plus dense et plus spécifique :

memory/
├── MEMORY.md          # Index de 6 projets + infra + multi-agent
├── saas-platform.md   # SaaS Next.js multi-tenant
├── terminal-app.md    # App desktop en Rust
├── app-mobile.md      # App Flutter + Supabase
├── editeur-macos.md   # Editeur macOS SwiftUI
├── app-photo-ai.md    # App mobile photo+voice+AI
├── speckit.md         # Workflow spec-kit documenté
├── multi-agent.md     # Protocole d'orchestration 3 agents
├── lessons-learned.md # Rétrospective multi-agent (erreurs, solutions)
├── user_philippe.md   # Profil utilisateur (préférences, devices)
└── memory.db          # Facts + décisions spécifiques DevTeam (~300KB)

Differences clés avec /Dev/ :

Aspect /Dev/ (portfolio) /Dev/DevTeam/ (multi-agent)
Fichiers mémoire 12 13+
SQLite 65KB (généraliste) ~300KB (3 projets indexes)
Spécificité Infra, credentials, feedback Orchestration, allocation agents, lessons
Permissions Node, pip, Supabase, Stripe… Codex, Gemini, Swift, xcodebuild…
Fichier critique deployment.md multi-agent.md
CLAUDE.md projet Aucun (global suffit) Par sous-projet (un CLAUDE.md par app)

Le fichier multi-agent.md est un exemple de mémoire critique qui n’existerait pas dans un setup classique :
– Allocation des agents : Claude = tech lead, Codex = backend/TDD, Gemini = fullstack
– Commandes validées (Gemini TOUJOURS avec -y, Codex avec --full-auto)
– Protocole : smoke test, briefing, contrats, validation gate, logging
– Regles d’or : un fichier = un agent, git séquentiel, chemins absolus

Le fichier lessons-learned.md capture les erreurs multi-agent résolues :
– Collision de fichiers silencieuse (dernier ecrivain gagne)
– Instabilite git (git add . capture du travail incomplet)
– Divergence de contexte (agent A renomme, agent B appelle l’ancien nom)
– Cascade d’erreurs (faux positifs propagees entre agents)

Ce sont des informations qu’aucun système automatique ne capturerait correctement — elles nécessitent de la curation humaine.

Guide pratique : créer votre setup hybride

Phase 1 : Splitter vos fichiers (30 minutes)

1. Auditer votre MEMORY.md actuel

wc -l ~/.claude/projects/*/memory/MEMORY.md

Si > 100 lignes, il est temps de splitter.

2. Identifier les thèmes
Regrouper les informations par type :
– Par projet (stack, config, conventions)
– Par infrastructuré (serveurs, déploiement)
– Par feedback (corrections de comportement)
– Par credentials (tokens, acces)

3. Créer les fichiers
Un fichier par thème. Format :

---
name: Nom du fichier
description: Une ligne pour quand le charger
type: user | feedback | project | référence
---

Contenu structure...

4. Remplacer MEMORY.md par un index
L’index doit tenir en < 50 lignes. Chaque entrée = un lien + une description en une ligne. Pas de contenu dans l’index.

Phase 2 : Ajouter SQLite (15 minutes)

1. Créer la base

sqlite3 ~/.claude/projects/<votre-projet>/memory/memory.db << 'SQL'
CREATE TABLE projects (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    path TEXT, domain TEXT, stack TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE facts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT REFERENCES projects(id),
    key TEXT NOT NULL, value TEXT NOT NULL,
    category TEXT,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE décisions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT REFERENCES projects(id),
    title TEXT NOT NULL, decision TEXT NOT NULL,
    reason TEXT, alternatives TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE problems (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT REFERENCES projects(id),
    description TEXT NOT NULL, solution TEXT NOT NULL,
    tags TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
SQL

2. Insérer vos premiers faits
Extraire les faits atomiques de vos fichiers .md et les insérer :

sqlite3 memory.db "INSERT INTO projects VALUES ('monprojet','Mon Projet','/path','domain.com','Next.js+Supabase',datetime('now'))"
sqlite3 memory.db "INSERT INTO facts (project_id,key,value,category) VALUES ('monprojet','backend_port','3001','infra')"

3. Ajouter l’instruction dans MEMORY.md

## Base SQLite
- `memory.db` -- Faits atomiques, décisions, problèmes résolus
- Requêter via : `sqlite3 memory.db "SELECT ..."`

4. Nettoyer les fichiers .md
Retirer des fichiers les faits qui sont maintenant dans SQLite. Garder le narratif, le contexte, le « pourquoi ».

Phase 3 : Ajouter claude-mem (5 minutes)

/plugin install claude-mem
/reload-plugins

Modifier ~/.claude-mem/settings.json :

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5",
  "CLAUDE_MEM_SKIP_TOOLS": "SlashCommand,Skill,TodoWrite,AskUserQuestion,TaskCreate,TaskUpdate"
}

Phase 4 : Configurer le routage (10 minutes)

Ajouter dans votre ~/.claude/CLAUDE.md les regles de routage :

## Hybrid Memory System

### Layer 1 -- Curated Files (source of truth)
Location: ~/.claude/projects/<project>/memory/
When to read: FIRST for project-specific facts
When to write: User préférences, architecture, credentials, feedback

### Layer 2 -- SQLite memory.db
When to query: Structured facts, décisions, solved problems
When to insert: New atomic facts, architectural décisions

### Layer 3 -- claude-mem (automatic)
Capture: Automatic via hooks
When to search: Session history, "what did we do last time", bug patterns

Bilan : forces, faiblesses, et quand utiliser quoi

Critère Fichiers .md SQLite claude-mem
Controle Total (humain écrit) Total (humain ou Claude) Aucun (automatique)
Curation Manuelle, haute qualite Manuelle Aucune
Transparence Lisible, éditable, git-friendly Requetable mais moins lisible Opaque (compression IA)
Recherche Sequentielle (lire le fichier) SQL (exact) Full-text + sémantique
Cout en tokens 200-500 par fichier lu ~20 par requête ~50-100 par index, ~500 par detail
Capture Manuelle Manuelle Automatique
Dependencies Aucune sqlite3 (préinstallé) Bun + ChromaDB + daemon
Scalabilité ~20 fichiers max confortables Milliers de rows Illimite
Ideal pour Contexte, procédures, feedback Faits, décisions, lookups Historique, découverte, retrouvaille

Le setup minimal

Si vous ne voulez faire qu’une chose : splittez vos fichiers (Étape 1). C’est le meilleur rapport effort/bénéfice. 30 minutes de travail, zero dépendance, gain immediat en maintenabilité et en contexte.

Le setup recommandé

Étapes 1 + 2 (fichiers + SQLite). Couvre 90% des besoins avec zero dépendance externe. La plupart des developpeurs n’ont pas besoin de recherche sémantique cross-sessions.

Le setup complet

Les 3 étapes. Pour les developpeurs qui travaillent sur plusieurs projets, font beaucoup de sessions, et veulent pouvoir retrouver « ce truc qu’on à fait y’a deux semaines ». Le cout en complexite (daemon, ChromaDB) est réel mais le gain en retrouvabilité aussi.

Conclusion

La mémoire par défaut de Claude Code est un bon point de depart. Mais traiter MEMORY.md comme un fourre-tout, c’est accepter de perdre du contexte, des tokens, et du temps.

Le système hybride propose ici repose sur une idée simple : chaque type d’information à un format optimal.

  • Le contexte narratif va dans des fichiers markdown curates
  • Les faits atomiques vont dans SQLite<