Claude Code oublie tout entre deux sessions. Chaque nouvelle conversation repart de zéro : pas de souvenir des fichiers lus, des choix d’architecture pris, ni des bugs corrigés la veille. Claude-Mem résout ce problème en capturant automatiquement les observations de chaque session et en les réinjectant au démarrage suivant.
Ce post explique comment l’installer, comment il fonctionne sous le capot, et comment l’utiliser au quotidien.
Le problème : la mémoire volatile des agents
Un agent IA comme Claude Code travaille dans une fenêtre de contexte limitée. Quand on ferme la session, tout disparaît. On se retrouve à répéter les mêmes explications, re-décrire l’architecture du projet, ou re-découvrir des patterns qu’on avait déjà établis.
C’est un problème connu. Plusieurs startups lèvent des millions pour le résoudre (Mem0, Letta, Supermemory…). Mais côté open source, des solutions pratiques existent déjà, et Claude-Mem en fait partie.
Installation
1. Installer le plugin
Dans un terminal Claude Code :
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-memRedémarrer Claude Code. Le plugin lance automatiquement son hook SessionStart et vérifie les dépendances via un script smart-install.js.
2. Le service worker (optionnel)
Le worker démarre automatiquement via le hook. On peut aussi le gérer manuellement :
npm run worker:start # démarrer le worker (port 37777)
npm run worker:status # vérifier le statut
npm run worker:restart # redémarrerVérifier que tout tourne :
curl http://localhost:37777/api/health3. Interface web
Naviguer vers http://localhost:37777 pour visualiser en temps réel les observations et résumés stockés.
Les 5 hooks en détail
Le plugin enregistre 5 hooks dans plugin/hooks/hooks.json :
| Hook | Déclencheur | Action |
|---|---|---|
| SessionStart | Ouverture de Claude Code | Vérifie le worker, injecte le contexte des sessions précédentes |
| UserPromptSubmit | Envoi d’un prompt | Crée/récupère la session en base, sauvegarde le prompt nettoyé |
| PostToolUse | Après chaque outil | Capture l’observation (outil, entrée, sortie) et l’envoie au worker |
| Stop | Pause utilisateur | Génère un résumé structuré (request, investigated, learned, completed, next_steps) |
| SessionEnd | Fermeture de session | Marque la session comme terminée, notifie l’interface via SSE |
Le hook PostToolUse filtre les outils à faible valeur (TodoWrite, AskUserQuestion…) pour ne garder que les observations utiles.
Architecture du worker
Le worker est un processus Node/Bun séparé qui tourne sur le port 37777 :
┌─────────────────────────────────────────────────────────────┐
│ Worker Service │
├─────────────────────────────────────────────────────────────┤
│ │
│ Express HTTP ──► API REST pour les hooks │
│ │ │
│ ├── SessionStore ──► CRUD SQLite (sessions, │
│ │ prompts, observations) │
│ │ │
│ ├── SDK Agent ──► Compression des observations │
│ │ via Claude Agent SDK │
│ │ │
│ ├── SessionSearch ──► Recherche FTS5 + ChromaDB │
│ │ │
│ └── SSE ──► Events temps réel vers l'interface │
│ │
└─────────────────────────────────────────────────────────────┘Le composant clé est le SDK Agent : pour chaque observation reçue, il appelle le Claude Agent SDK pour compresser le contenu brut en un résumé structuré, puis stocke le résultat en base.
Endpoints principaux
| Endpoint | Méthode | Description |
|---|---|---|
/api/health |
GET | Statut du worker |
/api/context/inject |
GET | Récupère le contexte à injecter (paramètre project) |
/api/sessions/observations |
POST | Enregistre une observation |
/api/sessions/summarize |
POST | Génère le résumé de fin de session |
/api/sessions/complete |
POST | Marque une session comme terminée |
Schéma de la base SQLite
Quatre tables organisent les données :
| Table | Contenu |
|---|---|
sdk_sessions |
ID session Claude, projet, premier prompt, compteur de prompts, statut, timestamps |
user_prompts |
Chaque prompt soumis, lié à une session |
observations |
Nom de l’outil, entrée/sortie nettoyées, observation compressée, timestamp |
session_summaries |
Résumé structuré : request, investigated, learned, completed, next_steps |
La recherche plein texte passe par une table virtuelle FTS5 indexée sur les observations compressées.
Recherche : le workflow MCP en 3 couches
La recherche dans l’historique utilise des outils MCP avec un workflow progressif qui réduit la consommation de tokens d’un facteur ~10 par rapport à un RAG classique :
Couche 1 : Search (index compact)
Requête : "comment j'ai configuré le SSL"
Résultat : liste d'IDs + titres + timestamps (~50-100 tokens chacun)Couche 2 : Timeline (contexte autour d’un point)
Requête : observation #42, ±5 observations
Résultat : vue chronologique de ce qui s'est passé autourCouche 3 : Get Observations (détails complets)
Requête : IDs [42, 43, 45]
Résultat : texte complet, entrées/sorties des outils (~500-1000 tokens chacun)Ce pattern de progressive disclosure évite de charger 10-20k tokens d’un coup. On filtre d’abord, on zoome ensuite.
Configurer le serveur MCP dans Claude Desktop
Pour exposer la recherche dans Claude Desktop :
{
"mcpServers": {
"mcp-search": {
"command": "node",
"args": [
"/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
]
}
}
}Dans Claude Code, le serveur MCP est configuré automatiquement à l’installation du plugin.
Gestion de la vie privée
Les données sensibles peuvent être protégées avec des balises <private> :
<private>Mon token API est xyz123</private>Les hooks suppriment ces balises avant d’envoyer les données au worker. Une seconde balise <claude-mem-context> empêche le plugin de ré-ingérer ses propres résumés.
Retour d’expérience
Quelques points à noter après utilisation :
- Le gain de contexte est réel : sur un projet suivi pendant plusieurs jours, Claude retrouve naturellement les conventions établies et les décisions prises
- L’impact sur les performances peut être significatif : le worker en arrière-plan consomme des ressources. Sur une machine modeste, surveiller l’usage CPU/RAM
- La sécurité de l’API n’est pas durcie par défaut (le worker écoute sur localhost sans auth). Acceptable en local, mais à sécuriser si exposé
Stack technique
| Composant | Technologie |
|---|---|
| Runtime | Node 18+ / Bun |
| Base de données | SQLite (WAL mode) + FTS5 |
| Recherche sémantique | ChromaDB (optionnel) |
| Compression | Claude Agent SDK |
| API | Express (port 37777) |
| Interface | Web viewer temps réel (SSE) |
Liens
Le sujet de la mémoire persistante pour les agents IA est en pleine explosion : Mem0 ($24M levés), Letta ($10M), Supermemory ($2.6M). Claude-Mem propose une approche locale et open source qui fonctionne déjà aujourd’hui avec Claude Code.
Comment ça marche
Claude-Mem s’appuie sur le système de hooks de Claude Code pour intercepter le cycle de vie d’une session :
Au prochain lancement, le hook
SessionStartinjecte silencieusement les résumés des sessions précédentes dans le contexte de Claude. L’agent retrouve ainsi une continuité de connaissance.