Claude-Mem : Donner une mémoire persistante à votre assistant IA

Conserver le contexte de travail reste le défi principal des agents de développement basés sur l’intelligence artificielle. Lorsque vous fermez votre terminal ou perdez votre connexion, l’agent oublie les décisions architecturales et les corrections de bugs précédentes.

Claude-Mem résout cette perte de mémoire numérique.

Cet outil capture les observations d’outils, génère des résumés sémantiques et injecte ces données dans vos futures sessions de travail.

• Continuité totale : Claude-Mem conserve le contexte de vos projets d’une session à l’autre sans intervention manuelle.
• Économie de ressources : Son workflow de recherche hybride à trois niveaux réduit la consommation de jetons de près de 90 %.
• Recherche hybride : Le système combine la puissance sémantique de Chroma DB avec l’indexation rapide de SQLite FTS5.
• Contrôle de la confidentialité : L’utilisation des balises <private> empêche le stockage des informations sensibles.
• Architecture robuste : Propulsé par Bun et SQLite pour garantir un service local ultra-rapide.

Démarrage Rapide et Installation

La mise en place s’effectue via votre terminal habituel. Choisissez la commande correspondant à votre environnement de développement :

• Installation standard : npx claude-mem install
• Intégration OpenCode : npx claude-mem install --ide opencode
• Utilisation d’Antigravity CLI : npx claude-mem install --ide antigravity
• Installation directe depuis Claude Code : /plugin marketplace add thedotmack/claude-mem /plugin install claude-mem

Note importante de sécurité : L’installation globale via npm install -g claude-mem installe uniquement le SDK. Elle n’enregistre pas les crochets système. Utilisez toujours les commandes de démarrage rapide ci-dessus. N’oubliez pas de redémarrer Claude Code pour appliquer les changements.

Pour les passerelles OpenClaw, utilisez l’installateur dédié :

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

Cet outil configure vos variables d’environnement, initialise le worker et gère l’envoi de flux d’observations vers Discord, Slack ou Telegram.

Fonctionnalités Majeures

• Mémoire persistante : Vos données survivent au redémarrage des sessions.
• Divulgation progressive : Récupération de l’information par paliers avec estimation du coût en jetons.
• Recherche par compétences : Exploration de l’historique de vos projets via l’outil mem-search.
• Interface d’affichage web : Visualisation en temps réel de votre flux de mémoire à l’adresse locale du worker.
• Intégration Claude Desktop : Recherche de souvenirs directement depuis l’application de bureau.
• Filtre de confidentialité : Les balises <private> excluent l’indexation des données sensibles.
• Citations : Référencement de vos anciennes observations grâce à des identifiants uniques.

Architecture Interne et Cycle de Vie

Le système s’articule autour de composants locaux pour assurer réactivité et confidentialité de vos données.

Le stockage repose sur une base de données SQLite locale complétée par un moteur de recherche vectoriel Chroma. Bun pilote le service HTTP local tandis que le script Smart Install valide l’intégrité de vos dépendances logicielles.

Le fonctionnement repose sur cinq crochets de cycle de vie :

• SessionStart : Analyse de l’état initial et chargement des résumés.
• UserPromptSubmit : Capture et indexation des requêtes de l’utilisateur.
• PostToolUse : Enregistrement des résultats produits par les outils exécutés.
• Stop : Interruption propre des processus de fond.
• SessionEnd : Génération du résumé sémantique final de la session de travail.

A lire — Claude-Mem Guide : Mémoire Persistante pour Claude Code

Optimisation des Jetons : Le Workflow à 3 Niveaux

L’envoi massif de données historiques consomme inutilement vos quotas de jetons. Claude-Mem introduit un motif d’accès structuré en trois étapes pour optimiser ces coûts :

Niveau	Outil MCP	Rôle principal	Coût approximatif
1	search	Obtention d’un index compact avec identifiants uniques	50 – 100 jetons par résultat
2	timeline	Visualisation du contexte chronologique autour d’un résultat	Variable
3	get_observations	Récupération des détails complets des identifiants filtrés	500 – 1 000 jetons par résultat

Cette approche permet de diviser par dix la consommation de jetons lors des recherches historiques complexes.

Voici un exemple typique d’interaction dans votre console :

// Étape 1 : Recherche d'un index de pannes
search(query="bug authentification", type="bugfix", limit=10)

// Étape 2 : Identification des identifiants pertinents (ex: #123)

// Étape 3 : Récupération des détails ciblés
get_observations(ids=[123])

Configuration et Personnalisation

Vos préférences se situent dans le fichier ~/.claude-mem/settings.json. Vous pouvez y modifier le port d’écoute du worker, le niveau des journaux et la langue de traitement.

Le paramètre CLAUDE_MEM_MODE gère à la fois le comportement de l’agent et la langue des résumés produits. Par exemple :

{
  "CLAUDE_MEM_MODE": "code--zh"
}

Les modes linguistiques utilisent le format d’encodage ISO 639-1. Le mode par défaut reste l’anglais (code).

Guide de Résolution des Problèmes

Si vous rencontrez des difficultés, décrivez simplement votre problème à Claude. L’outil d’auto-diagnostic évaluera l’état de la base de données, la disponibilité des ports réseau et les dépendances manquantes.

1. Problèmes d’affichage de l’interface web

Si la page web de visualisation ne se charge pas, exécutez ces vérifications :

• Déterminez le port configuré : PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json) lsof -i :$PORT
• Testez la réponse du point de terminaison de santé : curl http://127.0.0.1:$PORT/health
• Redémarrez le worker en cas d’absence de réponse : npm run worker:restart

2. Dysfonctionnement des connexions temps réel (SSE)

Si l’interface affiche un statut déconnecté, vérifiez le flux brut :

curl -N http://127.0.0.1:$PORT/stream

Les pare-feux d’entreprise ou les VPN actifs bloquent souvent les flux SSE. Désactivez temporairement votre tunnel de connexion pour isoler le problème.

3. Dépendances Python ou ChromaDB manquantes

La version 5.0.0+ requiert un environnement Python valide. Si l’installation échoue :

• Assurez-vous de disposer de Python 3.8 ou supérieur : python3 --version
• Installez manuellement le moteur vectoriel dans le répertoire du plugin : cd ~/.claude/plugins/marketplaces/thedotmack npm install chromadb
• Si Chroma échoue systématiquement, Claude-Mem basculera sur le moteur SQLite FTS5.

4. Gestion de la file d’attente et observations bloquées

Depuis la version 5.x, la récupération automatique de la file d’attente au démarrage est désactivée. Vous devez initier cette opération manuellement pour éviter les doublons d’indexation.

Utilisez l’outil interactif en ligne de commande :

bun scripts/check-pending-queue.ts

Pour forcer le traitement sans confirmation intermédiaire, utilisez l’option dédiée :

bun scripts/check-pending-queue.ts --process --limit 5

Vous pouvez également interroger directement l’API HTTP locale pour suivre l’état de traitement de vos tâches :

curl http://127.0.0.1:$PORT/api/pending-queue

Pour relancer le traitement via une requête POST brute :

curl -X POST http://127.0.0.1:$PORT/api/pending-queue/process \
  -H "Content-Type: application/json" \
  -d '{"sessionLimit": 10}'

5. Erreurs d’exécution sous Windows avec Bun

Sur les architectures Windows, les scripts de crochets peuvent échouer avec un message indiquant que la commande “bun” n’est pas reconnue.

Ce dysfonctionnement s’explique par la limite de taille des variables d’environnement de cmd.exe, plafonnée à 8191 caractères. Lorsque la variable PATH dépasse ce seuil, elle se vide silencieusement.

• Mettez à jour Claude-Mem pour exploiter le lanceur moderne qui résout le chemin absolu de l’exécutable Bun sans passer par l’interpréteur de commandes Windows.
• Nettoyez votre variable d’environnement PATH système en supprimant les entrées obsolètes ou dupliquées.

6. Verrous sur la base de données SQLite

Si la base de données retourne une erreur de type “database is locked”, libérez l’accès au fichier :

• Arrêtez le worker : npm run worker:stop
• Identifiez les verrous résiduels : lsof ~/.claude-mem/claude-mem.db
• Tuez les processus fautifs avant de relancer le service.

Maintenance et Optimisation de la Base de Données

Avec le temps, le fichier SQLite peut augmenter de volume et ralentir la vitesse d’injection du contexte. Appliquez ces requêtes de maintenance de manière périodique :

# Compression physique du fichier de base de données
sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

# Reconstruction complète des index de recherche textuelle
sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
"

Pour auditer la quantité d’informations stockées dans votre coffre de mémoire, exécutez cette requête d’analyse rapide :

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT 'sessions', COUNT(*) FROM sdk_sessions
  UNION ALL
  SELECT 'observations', COUNT(*) FROM observations
  UNION ALL
  SELECT 'summaries', COUNT(*) FROM session_summaries;
"

Pour assurer le bon fonctionnement de l’ensemble, nous vous recommandons de valider régulièrement les versions de vos composants sous-jacents, notamment Node.js qui doit rester supérieur ou égal à la version 20.0.0.