claude-mem : avis, architecture et alternatives pour la mémoire persistante de Claude Code

Pourquoi la mémoire persistante est devenue un enjeu critique pour les développeurs

Claude Code souffre d'une limitation structurelle : chaque session démarre avec une fenêtre de contexte vierge. Pour un développeur qui enchaîne des sessions quotidiennes sur un même projet, cela signifie un cycle répétitif : ré-expliquer l'architecture, redéfinir les conventions, rappeler les décisions passées. Claude passe en moyenne 3 à 5 appels d'outils d'exploration avant de produire quoi que ce soit d'utile dans une nouvelle session.

La mémoire native de Claude Code (fichiers CLAUDE.md et MEMORY.md) ne résout que partiellement le problème. MEMORY.md est limité à 200 lignes et ne propose aucune recherche sémantique. Pour des projets avec des centaines de sessions accumulées, c'est insuffisant.

claude-mem est un plugin open source qui ajoute une couche de rappel complète à Claude Code. Avec 37,2k étoiles GitHub, 174 releases et 22 contributeurs, c'est le projet de mémoire persistante le plus adopté de l'écosystème. Ce qui suit est une analyse technique de son architecture, de ses forces, de ses faiblesses et de ses alternatives.

Architecture technique : SQLite, Chroma et le pipeline de hooks

Vue d'ensemble du système

claude-mem s'intègre à Claude Code via le système de hooks du cycle de vie des plugins. Six scripts de hooks interceptent les événements clés d'une session :

Le Worker Service tourne en arrière-plan comme un serveur HTTP sur le port 37777, géré par le runtime Bun. Il expose une interface web locale et 10 endpoints de recherche via une API REST.

Le stockage hybride SQLite + Chroma

C'est le cœur technique du projet. Deux couches de stockage complémentaires coexistent :

Couche 1 : SQLite avec FTS5

• Stockage structuré : sessions, observations individuelles par appel d'outil, résumés générés par l'IA

• Recherche par mots-clés via BM25 scoring

• Latence faible, aucune dépendance externe

• Base stockée dans ~/.claude-mem/

Couche 2 : Chroma Vector Database

• Recherche sémantique par embeddings

• Permet des requêtes conceptuelles (chercher « problèmes d'authentification » trouve le contexte JWT même sans correspondance lexicale)

• Index stocké dans ~/.claude-mem/vector-db/chroma.sqlite3

• Point notable : Chroma stocke lui-même son index dans un fichier SQLite, ce qui signifie que deux instances SQLite coexistent

L'approche hybride combine la recherche exacte (rapide, déterministe) et la recherche sémantique (flexible, conceptuelle). C'est un pattern classique en RAG (Retrieval-Augmented Generation), mais adapté ici au cas d'usage spécifique de la mémoire de session.

La compression contextuelle

Le mécanisme de compression est central dans le design de claude-mem. Plutôt que de stocker les transcriptions brutes des conversations (qui peuvent être 5 à 10 fois plus volumineuses à cause du bruit des appels d'outils), le plugin :

1. Capture des observations structurées à chaque hook PostToolUse : quel outil a été appelé, ce qu'il a retourné, quel fichier a été modifié, quelle décision a été prise

2. Génère des résumés sémantiques via le Claude Agent SDK au hook Stop : des représentations compressées et significatives de ce qui s'est passé

3. Injecte sélectivement au démarrage de session : seul le contexte le plus pertinent est injecté, basé sur la similarité sémantique et les mots-clés

Le workflow MCP en 3 couches : divulgation progressive

Les 4 outils MCP exposés par claude-mem suivent un pattern de divulgation progressive conçu pour minimiser la consommation de tokens :

Étape 1 : search(query="authentication bug", type="bugfix", limit=10) → Retourne un index compact avec des IDs (~50-100 tokens/résultat) Étape 2 : timeline(observation_id=123) → Contexte chronologique autour de cette observation Étape 3 : get_observations(ids=[123, 456]) → Détails complets UNIQUEMENT pour les IDs filtrés (~500-1000 tokens/résultat)

Ce design atteint une économie d'environ 10x sur les tokens par rapport au chargement complet de toutes les observations. L'idée est de pré-filtrer avant de récupérer le contenu complet.

Les 4 outils MCP disponibles :

1. `search` : recherche plein texte dans l'index mémoire, filtrable par type, date, projet

2. `timeline` : contexte chronologique autour d'une observation ou requête spécifique

3. `get_observations` : récupération des détails complets par ID (toujours en batch)

4. `__IMPORTANT` : documentation du workflow, toujours visible par Claude

Installation et configuration

Mise en place (30 secondes)

/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem

Redémarrez Claude Code. Le plugin est actif. Aucune clé API, aucun fichier de configuration requis.

Prérequis système

Fichier de configuration

Les paramètres sont stockés dans ~/.claude-mem/settings.json (créé automatiquement au premier lancement) :

{ "model": "claude-sonnet-4-20250514", "port": 37777, "dataDir": "~/.claude-mem", "logLevel": "info", "contextInjection": { "enabled": true, "maxTokens": 4000 } }

Interface web locale

Un viewer est disponible à http://localhost:37777 pour :

• Visualiser le flux mémoire en temps réel

• Rechercher dans les observations passées

• Accéder aux observations individuelles via /api/observation/{id}

• Basculer entre les canaux stable et bêta (menu Paramètres)

• Gérer les versions

Contrôle de la confidentialité

Encadrez tout contenu sensible avec des balises <private> pour empêcher son stockage en mémoire :

<private>Cette clé API ou cette note personnelle ne sera pas capturée</private>

Endless Mode : la fonctionnalité bêta qui divise

Endless Mode est une fonctionnalité expérimentale accessible via le canal bêta du viewer web (Paramètres puis changement de canal).

Décrit comme une « architecture de mémoire biomimétique pour les sessions prolongées », il promet :

• Réduction de tokens allant jusqu'à 95 % par session

• Environ 20 fois plus d'appels d'outils avant d'atteindre les limites de contexte

• Des sessions effectivement « infinies » sans épuisement de la fenêtre de contexte

Avis de la communauté : ces chiffres ont été vivement contestés lors des discussions sur Reddit en décembre 2025. Plusieurs développeurs ont qualifié la réduction de 95 % d'« hautement exagérée », précisant qu'elle s'appliquait à une fonctionnalité alors non fonctionnelle. Le mode standard (hors Endless Mode) offre des économies plus modestes mais vérifiables.

Comparatif détaillé des solutions de mémoire persistante

Analyse des différences clés

claude-mem vs Mem0 :

• claude-mem fonctionne entièrement en local ; Mem0 est principalement cloud

• claude-mem utilise les hooks (capture automatique sans action de l'agent) ; Mem0 utilise MCP (l'agent doit appeler explicitement les outils mémoire)

• Mem0 revendique de meilleurs résultats sur les benchmarks (LOCOMO +26 % vs OpenAI) ; claude-mem n'a publié aucune donnée de benchmark

• Mem0 propose un free tier limité à 10 000 mémoires par mois ; claude-mem est illimité

claude-mem vs A-MEM :

• claude-mem : modèle de compaction. Les logs compressés sont statiques et ne se mettent pas à jour mutuellement

• A-MEM : modèle de graphe de connaissances. Les mémoires se lient entre elles et se mettent à jour quand de nouvelles informations arrivent (ex. : « l'auth utilise JWT » + « JWT expire en 1h » donne deux mémoires liées, toutes deux mises à jour)

• A-MEM est plus sophistiqué mais potentiellement plus fragile

claude-mem vs la mémoire native Claude Code :

• CLAUDE.md est écrit par le développeur ; MEMORY.md est écrit par Claude avec une limite de 200 lignes

• claude-mem ajoute la couche de rappel que la mémoire native ne fournit pas : recherche hybride, compression, archivage à grande échelle

• Les deux sont complémentaires. claude-mem ne remplace pas CLAUDE.md, il complète le système

Considérations sur la licence AGPL-3.0

La licence AGPL-3.0 a des implications directes pour les utilisateurs commerciaux :

• Utilisation personnelle ou interne : aucune restriction

• Modification et déploiement comme service réseau : obligation de publier le code source modifié

• Les œuvres dérivées doivent adopter la même licence AGPL-3.0

• Le répertoire ragtime/ est sous licence PolyForm Noncommercial 1.0.0, réservée à un usage non commercial

Si votre entreprise envisage d'intégrer claude-mem dans un produit ou service, une analyse juridique de la conformité AGPL est recommandée.

Limitations et problèmes connus

Problèmes techniques documentés (GitHub Issues, mars 2026)

Limitations conceptuelles

1. Dégradation du RAG à grande échelle : la qualité de récupération diminue à mesure que la base de données grossit. C'est une limitation fondamentale des systèmes RAG, pas spécifique à claude-mem.

1. Logs non interconnectés : les résumés de session compressés restent isolés. Contrairement à un graphe de connaissances (A-MEM), les informations plus récentes ne mettent pas à jour les mémoires plus anciennes. Sur un projet très long, cela peut conduire à des incohérences entre les résumés de différentes périodes.

1. Bruit de récupération : certains membres de la communauté décrivent le système comme « une couche de cache avec des problèmes d'invalidation de cache ». La difficulté à récupérer systématiquement le bon contexte passé est inhérente au pattern RAG.

1. Usage individuel uniquement : pas de mémoire partagée entre développeurs. Sur un projet d'équipe, chaque développeur a sa propre base de données de mémoire, sans possibilité de synchronisation.

1. Pas de benchmarks publiés : contrairement à Mem0 (qui revendique +26 % sur LOCOMO), claude-mem n'a publié aucune donnée quantitative sur la qualité de sa récupération.

Cas d'usage et retours développeurs

Des développeurs utilisant des outils de mémoire persistante pour Claude Code rapportent :

• Réduction d'environ 60 % du temps passé à ré-expliquer des concepts entre sessions

• Code aligné avec les conventions du projet dans environ 85 % des cas (contre 30 % sans mémoire)

• Temps entre le début de session et la livraison d'une fonctionnalité divisé par deux

• Débogage plus précis grâce à la reconnaissance de patterns récurrents

Les scénarios où claude-mem apporte le plus de valeur :

• Projets multi-semaines avec accumulation de contexte significative

• Débogage de régressions où Claude peut référencer le changement exact introduisant le bug

• Refactorisations multi-sessions nécessitant une compréhension architecturale cohérente sur plusieurs jours

• Apprentissage automatique des préférences de codage (fonctions fléchées, patterns TypeScript, conventions de tests)

Verdict technique

claude-mem est un outil bien conçu qui résout un problème réel avec une architecture sensée. Le choix du stockage hybride SQLite + Chroma est pertinent, le pattern de divulgation progressive des tokens est élégant, et l'intégration via les hooks Claude Code rend l'expérience transparente.

Les points forts sont clairs : gratuité, confidentialité locale totale, installation triviale et communauté active (37,2k étoiles GitHub en 7 mois).

Les faiblesses sont tout aussi claires : stabilité imparfaite (fuites de processus, crashs macOS, incompatibilité Windows), absence de benchmarks publiés, et limitations inhérentes au modèle RAG à grande échelle.

Pour un développeur individuel travaillant sur des projets de moyenne à longue durée avec Claude Code, claude-mem est aujourd'hui la solution open source la plus complète. Pour les équipes ou les environnements de production, les problèmes de stabilité et les implications de la licence AGPL-3.0 justifient une évaluation prudente.

L'alternative la plus intéressante pour ceux qui recherchent une approche conceptuellement différente est A-MEM (graphe de connaissances évolutif, licence MIT). Pour ceux qui privilégient le cloud et les benchmarks vérifiés, Mem0 mérite une évaluation.