claude-mem mémoire persistante agents : le dépôt thedotmack/claude-mem se présente comme un « système de compression de mémoire persistante » conçu pour Claude Code. Il observe ce que l’agent fait pendant une session, le résume, puis réinjecte l’essentiel au démarrage de la session suivante. Le dépôt affichait environ 103 000 étoiles et 9 100 forks à la fin d’octobre 2026, sous licence Apache 2.0, avec la version 15.2.1 indiquée dans le README.
Pour une équipe d’exploitation, c’est un petit service qui tourne à côté de l’agent. Il écoute chaque appel d’outil, appelle un modèle de langage pour le résumer, stocke le résultat et modifie le contexte de chaque nouvelle session. Latence, coût en tokens, qualité de ce qui est rappelé et confidentialité deviennent donc des sujets d’exploitation. Cet article suit le README et la documentation du dépôt, lus le 26 octobre 2026.
Précision d’honnêteté : span.observer n’a pas installé claude-mem. Les commandes viennent du README, les réglages de la documentation officielle, et la capture d’interface vient du dépôt du projet. Pour une autre approche de la mémoire d’agent, voir Hindsight, mémoire d’agents IA : l’angle diffère, comme on le verra plus bas.
claude-mem mémoire persistante agents : ce que dit le dépôt
- Auteur et licence : le README cite Alex Newman (
@thedotmack) comme auteur. Le fichier LICENSE est le texte standard de l’Apache License 2.0, et le README le confirme. Les fichiersdocs/license.mdetdocs/ip-boundary.mddécrivent une structure « open-core » : le moteur de mémoire, le serveur, la CLI, les adaptateurs et les outils MCP sont sous Apache 2.0, tandis qu’un cloud hébergé, la synchronisation d’équipe, l’administration et le SSO restent réservés hors du dépôt public. - Technologie : TypeScript, Node.js 20 ou plus, Bun comme gestionnaire de processus, SQLite avec recherche plein texte FTS5, et en option la base vectorielle Chroma (installée via
uv). - Principe : des hooks de cycle de vie de Claude Code (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) transmettent les événements à un worker local. Le worker demande à un modèle de les compresser en « observations » structurées.
- Chiffres relus le 26 octobre 2026 : environ 103 000 étoiles et 9 100 forks, d’après la page du dépôt ; version 15.2.1 d’après le badge du README et le paquet npm. Les étoiles ont été lues par un outil de résumé de page : revérifiez-les avant de les citer ailleurs.
Le README annonce aussi des installeurs pour d’autres environnements que Claude Code (OpenCode, T3 Code, Antigravity, OMP, Pi, OpenClaw). Cet article se limite à Claude Code, le cas d’origine.
Visite de l’interface : le viewer web
Le worker sert une interface web, le « viewer », qui affiche en direct les observations enregistrées. La capture ci-dessous est une image de l’animation cm-preview.gif publiée dans le dépôt du projet : à gauche une session Claude Code, à droite le viewer.

Chaque carte porte un type (par exemple change ou feature), un titre, un court récit et un identifiant. D’après la documentation, le viewer se met à jour par Server-Sent Events et se filtre par projet. Les réglages de contexte s’y modifient aussi, avec un aperçu en direct.
Comment la mémoire est compressée puis réinjectée
Le flux décrit par la documentation d’architecture tient en une ligne : un hook écrit dans la base, le worker lit et traite les entrées avec le SDK de l’agent, puis le hook de la session suivante relit les résumés. En pratique :
- Capture : après chaque appel d’outil (PostToolUse), le hook envoie l’événement au worker. La documentation parle de « 100 fois et plus » par session.
- Compression : le worker confie chaque événement à un modèle. Par défaut,
CLAUDE_MEM_MODELvautclaude-haiku-4-5-20251001avec le fournisseurclaude; d’autres fournisseurs sont listés :codex,gemini,openrouter,openai-compatible. - Résumé : à l’arrêt de l’agent (Stop), un résumé final consigne la demande, ce qui a été fait et ce qui a été appris.
- Réinjection : au démarrage suivant, le hook de contexte ajoute les dernières observations. Le défaut est de 50 (
CLAUDE_MEM_CONTEXT_OBSERVATIONS).

La capture montre l’exemple de configuration manuelle de la documentation : cent observations, vingt sessions, filtrage par type (bugfix, decision, discovery) et affichage du coût en tokens de lecture. Ce ne sont pas les valeurs par défaut.
Recherche en trois couches
Le projet défend une « divulgation progressive » : montrer d’abord un index peu coûteux, puis aller chercher le détail seulement si nécessaire. Le README décrit trois outils MCP : search (index compact), timeline (contexte chronologique) et get_observations (détails d’identifiants filtrés). Le projet avance un gain d’environ dix fois en tokens ; c’est une affirmation du README, pas une mesure reproduite ici.

Installation pas à pas
Prérequis
Le README demande Node.js 20 ou plus, une version récente de Claude Code avec prise en charge des plugins, Bun et uv (installés automatiquement s’ils manquent) et SQLite 3 (fourni).
Étape 1 — Lancer l’installeur
npx claude-mem install
Le README précise que npm install -g claude-mem installe seulement le SDK, sans enregistrer les hooks ni le worker. Après l’installation, l’outil propose une connexion par e-mail à un compte claude-mem avec un essai gratuit de 30 jours de « l’observateur » hébergé. Pour l’éviter, le README propose de passer un indicateur --provider explicite, de définir CLAUDE_MEM_ONLINE_OPTIN=false ou de travailler dans un shell non interactif.
Étape 2 — Ou passer par le marketplace de plugins
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
Redémarrez Claude Code : le README indique que le contexte des sessions précédentes apparaît ensuite automatiquement dans les nouvelles.
Étape 3 — Windows
Les hooks n’ont pas besoin de Git Bash. L’installeur place un lanceur claude-mem.exe dans %LOCALAPPDATA%\claude-mem\bin et l’ajoute au Path de l’utilisateur ; redémarrez le terminal ensuite. En cas d’erreur « Executable not found in $PATH: « claude-mem » », le README renvoie à npx claude-mem doctor.
Comment vérifier que ça fonctionne
- Lancez
npx claude-mem doctor: la documentation indique qu’il affiche une ligne sur le lanceur de hooks. - Démarrez une session Claude Code, faites quelques actions, puis ouvrez le viewer à l’adresse que le worker affiche au démarrage. Des cartes d’observations doivent apparaître.
- Interrogez le worker :
curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health, commande donnée par la documentation de configuration pour lire le port actif.
Observer claude-mem en exploitation
La documentation ne décrit ni export OpenTelemetry ni métriques Prometheus. Ce qu’elle permet de suivre :
- Santé du worker : un service HTTP local, port par défaut
37700 + (uid % 100), modifiable avecCLAUDE_MEM_WORKER_PORT. La page « Worker Service » citeGET /health, la page de configurationGET /api/health: vérifiez laquelle répond sur votre version. - File d’attente :
GET /api/pending-queuemontre les messages en attente, en cours, traités ou échoués (trois tentatives par défaut) et le nombre de messages « bloqués » (plus de cinq minutes en traitement).POST /api/pending-queue/processrelance le traitement. C’est le bon indicateur après un plantage. - Journaux : dossier
logs/du répertoire de données (~/.claude-mempar défaut,CLAUDE_MEM_DATA_DIR), niveau réglé parCLAUDE_MEM_LOG_LEVEL(DEBUG, INFO, WARN, ERROR, SILENT). Les pages de documentation nomment les fichiers de façon différente (worker-out.logd’un côté,worker-YYYY-MM-DD.logde l’autre). - Volume stocké :
GET /api/statset la baseclaude-mem.dbpermettent de suivre la croissance. - Coût : chaque observation passe par un modèle. Le suivi des tokens se fait côté fournisseur ; la méthode de le coût d’un agent IA en tokens avec OpenTelemetry s’applique, et celle d’observer les agents MCP avec OpenTelemetry pour les appels des outils de recherche.
Le worker écoute sur 127.0.0.1 par défaut (CLAUDE_MEM_WORKER_HOST). La documentation recommande de le garder ainsi pour quiconque n’utilise pas l’accès distant. Pour le cadre général de supervision d’un agent de code, voir superviser un agent de code en entreprise.
Ce qui distingue claude-mem de Hindsight
L’article sur Hindsight décrit un serveur de mémoire à déployer avec PostgreSQL, appelé par n’importe quel agent via une API et des opérations retain, recall et reflect. claude-mem part d’un autre endroit : il s’accroche aux hooks de Claude Code, ne demande aucun code côté agent, stocke tout en local dans SQLite et réinjecte un index au démarrage de chaque session. Le premier est une brique de mémoire pour construire un agent ; le second est un module complémentaire pour un agent de code existant.
Limites et points ouverts
- Données sensibles : tout appel d’outil peut être capturé, y compris des chemins, des commandes et des extraits de fichiers. Le README décrit des balises
<private>pour exclure du contenu, et la documentation des filtres (CLAUDE_MEM_SKIP_TOOLS,CLAUDE_MEM_SKIP_BASH_PATTERNS, projets exclus). Ils ne protègent que ce que vous avez pensé à exclure. - Offre commerciale au premier plan : le README met en avant une connexion à un compte, un essai gratuit de 30 jours et une mémoire hébergée par défaut pour l’un des installeurs. Le projet affirme jusqu’à 100 % d’usage supplémentaire sur votre forfait : c’est un argument commercial, non vérifié ici. L’installation locale reste possible.
- Jeton communautaire : la fin du README parle de CMEM, un jeton créé par un tiers mais « officiellement embrassé » par l’auteur. span.observer ne le recommande ni ne le commente ; c’est un signal de prudence pour qui évalue le projet.
- Cadre open-core : certaines fonctions annoncées (équipe, SSO, cloud) sont réservées hors du dépôt Apache 2.0, d’après
docs/ip-boundary.md. - Documentation inégale : la même information (santé du worker, noms des journaux) diffère d’une page à l’autre, et le README décrit d’abord l’installation pour Grok Bot, puis Claude Code. Le chiffre de « 10 fois moins de tokens » et le « 100 % d’efficacité » du skill sont des affirmations du projet.
- Projet très actif : version 15.2.1, plus de 3 600 commits d’après la page du dépôt ; les options évoluent vite.
Bonnes pratiques
- Testez d’abord sur un projet sans secrets, avec
CLAUDE_MEM_CONTEXT_OBSERVATIONSbas. - Ajoutez vos motifs sensibles à
CLAUDE_MEM_SKIP_BASH_PATTERNSavant l’usage réel et gardez le worker sur127.0.0.1. - Choisissez explicitement le fournisseur de compression, avec le modèle le moins cher qui convient, et suivez la consommation chez lui.
- Sauvegardez le dossier de données avant une mise à jour, et surveillez la file d’attente après un redémarrage.
- Relisez ce qui est mémorisé : une observation fausse est réinjectée à chaque session.
Questions fréquentes
claude-mem est-il gratuit et open source ?
Le code du dépôt est sous Apache 2.0 d’après le fichier LICENSE. Le README propose en plus une offre hébergée avec essai gratuit de 30 jours ; elle est facultative selon ses indications.
Les données quittent-elles ma machine ?
Les observations sont stockées dans une base SQLite locale. Mais le résumé passe par un modèle : Claude par défaut, ou Gemini, OpenRouter ou un autre fournisseur selon CLAUDE_MEM_PROVIDER. Le contenu des appels d’outils est donc envoyé à ce fournisseur. La synchronisation cloud est un service séparé décrit par le projet.
Quelle différence avec le fichier CLAUDE.md ?
Un fichier d’instructions est écrit à la main et lu en entier à chaque session. claude-mem génère les entrées automatiquement et n’injecte qu’un index borné, détaillé ensuite à la demande. Les deux se complètent.
Conclusion
claude-mem automatise une tâche que les équipes font à la main : transmettre à l’agent ce qui s’est passé hier. Il s’installe en une commande et se règle par un fichier JSON. Il faut le traiter comme un service : surveiller sa file d’attente, compter ses tokens, limiter ce qu’il mémorise. Sources : dépôt thedotmack/claude-mem et documentation officielle.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.