Claude-Mem : un plugin de mémoire persistante pour Claude Code
Claude-Mem est un plugin tiers qui observe ce que fait votre agent, charge un second agent de le compresser en observations, puis injecte un court index de celles-ci dans la session suivante. Voici ce qu'il fait réellement, comment l'installer et le configurer, et où s'arrête son rôle et où commence celui de CLAUDE.md.
Claude-Mem en un coup d'œil
- C'est une couche de mémoire, pas un fichier de règles : des hooks confient chaque appel d'outil à un worker local, un second agent transforme cette activité en observations courtes, et la session suivante démarre avec un index compact de celles-ci.
- Deux procédures d'installation prises en charge : npx claude-mem install (prépare l'environnement d'exécution et ouvre une configuration dans le navigateur), ou le duo /plugin marketplace add thedotmack/claude-mem puis /plugin install claude-mem.
- Apache-2.0, TypeScript, maintenu par Alex Newman (thedotmack). La mémoire est stockée localement dans SQLite, à l'emplacement ~/.claude-mem/claude-mem.db ; la synchronisation cloud est optionnelle.
- Il ne remplace ni CLAUDE.md ni la mémoire automatique de Claude Code : les trois se chargent au démarrage de la session et répondent à des questions différentes. Le tableau comparatif ci-dessous en est la version courte.
thedotmack/claude-mem — README
Sourcegithub.comchecked 2026-11-13
.claude-plugin/marketplace.json — claude-mem 15.18.3
Sourceraw.githubusercontent.comchecked 2026-11-13
Installation Guide
Sourcedocs.claude-mem.aichecked 2026-11-13
Configuration
Sourcedocs.claude-mem.aichecked 2026-11-13
Telemetry — what is collected and how to opt out
Sourcedocs.claude-mem.aichecked 2026-11-13
How Claude remembers your project — CLAUDE.md vs auto memory
Sourcecode.claude.comchecked 2026-11-13
dsh-claude-mem — DeepSeek Harness port (unofficial)
Sourcedeepseekharnessplugins.comchecked 2026-11-13
Les commandes, réglages, valeurs par défaut et chemins de cette page ont été relevés dans le dépôt amont et dans la documentation officielle le 2026-11-13. Les commandes et les noms de réglages restent volontairement non traduits, car une commande traduite est une commande cassée.
Données du dépôt issues de l'API GitHub le 2026-11-13 : 116,640 étoiles, 10,120 forks, créé le 2025-08-31, dernière version v15.18.3 publiée le 2026-11-12. Le nombre d'étoiles bouge chaque jour — à prendre comme un instantané, pas comme une note.
Ce qu'est réellement Claude-Mem
Claude-Mem est un plugin open source pour Claude Code (et pour une douzaine d'autres agents de programmation) qui donne à l'agent la mémoire de son propre travail. Le projet décrit le problème sans détour : chaque nouvelle session repart de zéro, relit les mêmes fichiers, repose les mêmes questions et retombe sur des erreurs que vous aviez déjà corrigées ensemble.
Sa réponse est un second agent qui tourne à côté du vôtre. Les hooks installés dans l'agent hôte confient chaque appel d'outil — ce qui a été lu, modifié et exécuté — à un petit worker local. Ce worker fait tourner un modèle observateur sur l'activité, écrit de courtes observations structurées ainsi qu'un résumé de fin de session, et les stocke dans une base SQLite locale. Au démarrage d'une nouvelle session, l'agent hôte reçoit un index compact des observations pertinentes pour ce projet et ne récupère les détails complets que lorsqu'il les demande.
L'unité de mémoire, ici, est donc une observation sur du travail effectué, et non une instruction que vous avez écrite. Toute la différence avec CLAUDE.md est là, et c'est pourquoi les deux coexistent au lieu de se concurrencer.
- Licence
- Apache-2.0
- Dernière version
- v15.18.3 · 2026-11-12
- La mémoire réside dans
~/.claude-mem/claude-mem.db- Étoiles (2026-11-13)
- 116,640
Le fonctionnement en trois temps
Le README énonce la boucle en trois phrases, et toutes les autres fonctionnalités en découlent :
- 1
Votre agent travaille
Des hooks de cycle de vie dans l'agent hôte confient chaque appel d'outil à un petit worker local. Pour Claude Code, les hooks couvrent SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStop et SessionEnd, plus une entrée Setup pour claude --init et --maintenance. Chaque hook est une commande unique sans shell, claude-mem hook claude-code <event>.
- 2
L'observateur prend des notes
Un second agent transforme cette activité en observations courtes et rédige un résumé à la fin de la session. Par défaut, le modèle de compression est Haiku (CLAUDE_MEM_MODEL=haiku), exécuté sur votre offre Anthropic ; vous pouvez aussi le pointer vers une clé OpenRouter ou Gemini, ou vers l'observateur hébergé de l'éditeur.
- 3
La session suivante démarre avec elles
Au SessionStart, l'agent reçoit un index compact des observations de ce projet — 50 par défaut, réglable via CLAUDE_MEM_CONTEXT_OBSERVATIONS — et ne récupère les détails complets que lorsqu'il en a besoin. L'injection commence à votre deuxième session dans un projet, car la première n'a encore rien à injecter.
La recherche repose sur la même idée de couches. Trois outils MCP — search, timeline, get_observations — renvoient d'abord un index, puis le contexte chronologique, et enfin les enregistrements complets, si bien que l'agent ne paie le détail que sur les lignes qu'il a choisies. La skill mem-search pilote ces outils pour vous, et les chiffres du README lui-même situent une ligne d'index autour de 50–100 tokens contre 500–1 000 pour un enregistrement complet — un ratio par ligne dont le README dit explicitement qu'il ne constitue pas une économie mesurée de bout en bout.
Ce que le worker vous apporte en plus
Le worker local sert une visionneuse à l'URL affichée au démarrage — mémoire, sessions et réglages sur /viewer, plus My Work à la racine — et expose des outils au-delà de la recherche : smart_search, smart_outline et smart_unfold pour naviguer dans le code, save_memory pour écrire une note volontairement, et un suivi de l'état du travail. Chaque observation possède un ID que vous pouvez citer via l'API du worker.
Installer et vérifier
Les deux procédures ci-dessous sont copiées de la documentation amont. Celle de l'installateur est celle que le projet recommande, car elle prépare l'environnement d'exécution et compile le lanceur de hooks ; celle du plugin tient en deux invites dans Claude Code.
Procédure 1 — l'installateur
Lancez ceci dans un terminal. L'installateur vérifie Bun et uv, copie les fichiers du plugin, installe les dépendances, place le lanceur claude-mem dans votre PATH et ouvre une configuration dans le navigateur où vous choisissez les agents, intégrations, skills et le fournisseur de mémoire. Laissez le terminal ouvert pendant que vous utilisez cette page.
npx claude-mem installNe l'installez pas avec npm install -g claude-mem. Le README est explicite : une installation npm globale ne dépose que le SDK/la bibliothèque sur votre machine — elle n'enregistre aucun hook de plugin et ne démarre aucun worker, et elle peut masquer le vrai lanceur dans le PATH.
Procédure 2 — la place de marché des plugins
Envoyez ces deux commandes comme deux invites distinctes dans Claude Code, puis redémarrez-le. Les deux procédures configurent les hooks et démarrent le worker ; le contexte des sessions précédentes apparaît ensuite automatiquement dans les nouvelles sessions.
/plugin marketplace add thedotmack/claude-mem/plugin install claude-memUne installation via la seule place de marché n'a pas d'étape d'installateur : le plugin place donc son lanceur au premier démarrage de session, pendant qu'il compile — cette première session peut tourner sans contexte mémoire, et la suivante en dispose. Lancer npx claude-mem install une fois supprime cet intervalle.
Vérifier qu'il tourne vraiment
Lancez npx claude-mem doctor : il vérifie Bun, uv, le lanceur de hooks et le worker, et vous indique quoi corriger. claude-mem --version affiche le numéro de protocole du lanceur, et l'URL du worker affichée au démarrage sert la visionneuse. Si les hooks signalent « Executable not found in $PATH », doctor montre quel claude-mem est résolu dans le PATH et s'il s'agit bien du lanceur.
npx claude-mem doctorclaude-mem --versionPrérequis avant de commencer
- 1Node.js 20.19 ou ultérieur dans la branche 20.x, ou 22.12 ou ultérieur.
- 2Bun 1.2.16 ou plus récent — le lanceur de hooks est compilé avec lui ; l'installateur installe Bun s'il est absent.
- 3uv, installé automatiquement s'il manque : il fournit la partie Python du service d'embeddings de Chroma pour la recherche sémantique.
- 4Claude Code 2.1.139 ou ultérieur — la première version qui exécute des arguments de hook sous forme exec. Les versions antérieures ignorent les args et lancent un claude-mem nu, donc rien n'est capturé. SQLite est fourni via bun:sqlite.
Les réglages qui changent vraiment le comportement
Tout se trouve dans ~/.claude-mem/settings.json, créé automatiquement avec les valeurs par défaut au premier lancement, et une variable d'environnement du même nom prend le pas sur le fichier. Voici les lignes qui valent la peine d'être connues ; la page de configuration documente le reste.
| Réglage | Valeur par défaut | Ce qu'il fait |
|---|---|---|
CLAUDE_MEM_MODEL | haiku | Modèle utilisé pour compresser les observations quand le fournisseur est Claude. haiku suit le Haiku le plus récent ; un ID complet fige une version. |
CLAUDE_MEM_PROVIDER | claude | Quel fournisseur exécute l'observateur : claude, codex, gemini, openrouter ou openai-compatible. |
CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | Combien d'observations sont injectées au démarrage de la session. Diminuez si le bloc de démarrage vous semble lourd. |
CLAUDE_MEM_MODE | code | Profil de travail et langue des observations générées, par ex. code, code--chill pour moins d'observations, ou code--zh pour le chinois. |
CLAUDE_MEM_DATA_DIR | ~/.claude-mem | Racine des données. Tous les autres chemins — base de données, index Chroma, journaux, réglages, fichiers pid et port du worker — en découlent. |
CLAUDE_MEM_WORKER_PORT | 37700 + (uid % 100) | Port du worker. La valeur par défaut est propre à chaque utilisateur, pour que deux utilisateurs sur une même machine n'entrent pas en collision ; fixez un port si vous scriptez contre l'API HTTP. |
CLAUDE_MEM_CONTEXT_PROJECTS | current | Pour quels projets SessionStart lit la mémoire : current désigne ce checkout, all désigne tous les projets sauf ceux que vous excluez par motif glob. |
CLAUDE_MEM_SKIP_TOOLS | ListMcpResourcesTool, SlashCommand, Skill, TodoWrite, AskUserQuestion | Outils exclus des observations. Utile pour les outils dont la sortie est du bruit plutôt que du savoir. |
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES | false | Indique si le contexte de SessionStart inclut les observations de tous les harnais, et pas seulement celui dans lequel vous êtes. Par défaut false. |
CLAUDE_MEM_SKILLS_DISABLED | (none) | Masque des skills fournies de la liste et des commandes slash de Claude Code, par simple nom de dossier. |
Deux autres à connaître : CLAUDE_MEM_SKIP_BASH_PATTERNS prend une expression régulière comparée à chaque commande shell, pour que les commandes bruyantes ne deviennent jamais des observations, et CLAUDE_MEM_REDACT_ENABLED (désactivé par défaut) active la rédaction automatique des motifs de secrets reconnus avant leur stockage.
Claude-Mem face à la mémoire intégrée de Claude Code
Claude Code transporte déjà du savoir d'une session à l'autre de deux manières, que la documentation d'Anthropic présente comme complémentaires : les fichiers CLAUDE.md que vous écrivez, et la mémoire automatique que Claude rédige lui-même. Claude-Mem est une troisième couche, indépendante, par-dessus.
| Dimension | Intégré à Claude Code | Plugin Claude-Mem |
|---|---|---|
| Qui l'écrit | Vous écrivez CLAUDE.md ; Claude écrit la mémoire automatique à partir de vos corrections. | Un second agent observateur, à partir de l'activité d'outils produite par votre session. |
| Où cela réside | CLAUDE.md à la racine du projet ou ~/.claude/CLAUDE.md ; la mémoire automatique dans ~/.claude/projects/<project>/memory/ avec un index MEMORY.md. | SQLite dans ~/.claude-mem/claude-mem.db, plus les réglages et journaux dans le même dossier. Index Chroma facultatif pour la recherche sémantique. |
| Ce qu'on y met | Des instructions et des règles ; la mémoire automatique retient des apprentissages et des motifs, et seules ses 200 premières lignes ou 25 Ko sont chargées. | Des observations sur du travail effectué — décisions, corrections de bugs, ce qui a été lu et modifié — compressées par un modèle. |
| Quand cela se charge | À chaque session, automatiquement, comme contexte après le prompt système. | Au SessionStart via un hook, à partir de votre deuxième session dans un projet. |
| Comment c'est lu | Le fichier entier ou l'index de mémoire automatique est simplement présent dans le contexte ; /memory liste et ouvre les fichiers. | Un index compact est injecté ; les détails reviennent via trois outils MCP — search, timeline, get_observations. |
| Dépendances et coût | Rien de plus — c'est livré avec Claude Code. | Node, Bun et uv, un processus worker local, et un modèle qui compresse : votre offre Anthropic par défaut, votre propre clé, ou l'observateur hébergé payant. |
La répartition pratique : les règles et conventions dans CLAUDE.md, la mémoire automatique pour les préférences, et Claude-Mem pour l'historique de ce que vous avez réellement fait. Si le détail d'une session ne compte qu'une fois, aucun des trois n'en a besoin ; si une règle doit être suivie à chaque fois, seule CLAUDE.md est sa place. Les deux ne s'excluent même pas au stockage — l'ingestion de mémoire de claude-mem importe les fichiers de sujets de la mémoire automatique de Claude Code dans sa propre base sous forme d'observations, sans dépenser de tokens du modèle.
Tutoriel memory de Claude CodeConfidentialité, limites et réserves honnêtes
Ce plugin enregistre vos sessions de travail : les valeurs par défaut méritent donc d'être lues avant qu'il n'arrive dans un dépôt professionnel.
- 1Local par défaut. Les sessions, observations et résumés sont écrits dans SQLite à ~/.claude-mem/claude-mem.db ; les réglages et journaux se trouvent dans le même dossier. La synchronisation cloud est optionnelle, pas automatique.
- 2Enveloppez n'importe quoi dans des balises <private> et ce ne sera jamais stocké — ce sont les mots du README. La rédaction automatique des motifs de secrets reconnus est un autre interrupteur, facultatif, CLAUDE_MEM_REDACT_ENABLED, désactivé par défaut.
- 3La télémétrie anonyme est activée par défaut (PostHog, liée uniquement à un UUID d'installation aléatoire). Désactivez-la avec npx claude-mem telemetry disable ; DO_NOT_TRACK est respecté et prime sur tout le reste.
- 4La compression est un appel de modèle : l'activité des outils quitte donc la machine pour le fournisseur que vous avez choisi — votre offre Anthropic, votre clé OpenRouter ou Gemini, ou l'observateur hébergé de l'éditeur. Choisissez en connaissance de cause.
- 5C'est un logiciel tiers, pas un produit Anthropic, et il installe des hooks exécutables. Lisez plugin/hooks/hooks.json et les réglages avant de le déployer dans une équipe ; traitez le plugin comme du code que vous exécutez, parce que c'est exactement ce qu'il est.
- 6Il coûte du contexte autant que des tokens : un index injecté, un processus worker, et Bun et uv sur la machine. Si vos sessions sont déjà courtes et autonomes, le gain est faible — mesurez sur votre propre dépôt plutôt que de faire confiance à un chiffre de gros titre.
Rien de tout cela n'en fait une mauvaise installation. Cela en fait un outil à essayer d'abord sur un vrai projet — en excluant par motif glob les dépôts que vous ne voulez jamais voir enregistrés, et en coupant la télémétrie si vous préférez — avant d'en faire le réglage par défaut de tout ce que vous ouvrez.
La télémétrie se coupe en une commande :
npx claude-mem telemetry disable