codebase-memory-mcp : ce que le README permet vraiment de comprendre

Un backend d'analyse structurelle pour les clients MCP

codebase-memory-mcp est une implémentation en C qui indexe un dépôt dans un graphe de connaissances persistant et l'expose via 15 outils MCP. Le README le décrit comme un backend d'analyse structurelle plutôt que comme un LLM : le modèle présent dans votre client MCP, par exemple Claude Code, assure la traduction du langage naturel en requêtes de graphe. L'analyse utilise des grammaires tree-sitter vendorisées compilées dans le binaire, couvrant 158 langues, complétées par la résolution sémantique de types Hybrid LSP pour les langues listées comme Python, TypeScript, JavaScript, JSX, TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust et Perl. Le graphe enregistre les fonctions, les classes, les chaînes d'appel, les routes HTTP et les liens entre services. Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale.

Vitesse d'indexation et pipeline à mémoire d'abord

L'affirmation de performance principale du README est une indexation complète du noyau Linux, 28 millions de lignes de code et 75 000 fichiers, en 3 minutes, mesurée sur un Apple M3 Pro, produisant 4,81 millions de nœuds et 7,72 millions d'arêtes. Une indexation rapide du même dépôt a pris 1 minute 12 secondes avec 1,88 million de nœuds ; Django a été indexé en environ 6 secondes avec 49 000 nœuds et 196 000 arêtes. Le pipeline est décrit comme RAM-first : compression LZ4, SQLite en mémoire, un seul dump à la fin et libération de la mémoire vers le système d'exploitation après l'indexation. Le README fait aussi état d'une efficacité en tokens : cinq requêtes structurelles ont consommé environ 3 400 tokens contre environ 412 000 pour une exploration grep fichier par fichier, soit une réduction de 99,2 %. Ces chiffres proviennent du tableau de benchmarks du README et d'un preprint arXiv cité ; la source n'établit pas comment ils ont été reproduits indépendamment. Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale.

Distribution, installation et démon partagé

Le projet est distribué sous forme d'un binaire statique unique pour macOS (arm64/amd64), Linux (arm64/amd64) et Windows (amd64), sans dépendances d'exécution. La commande install détecte automatiquement les agents de codage installés et écrit des entrées MCP, des instructions durables, des compétences et des hooks de cycle de vie là où c'est pris en charge. Un démon de coordination par compte est partagé entre tous les clients configurés : la première session adossée au démon le démarre, chaque session enregistre son propre travail et la dernière session l'arrête. Tous les processus CBM actifs doivent exécuter exactement la même version, le même build exécutable, la même ABI de coordination et la même racine de cache canonique ; un processus en conflit échoue avant de travailler et enregistre le conflit dans daemon-conflicts.ndjson sous le répertoire de journaux du cache. Les mises à jour passent par le script d'installation sur toutes les plateformes, pas depuis le binaire en cours d'exécution, et le README affirme que cbm n'effectue aucune requête réseau de sa propre initiative. Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale.

Configuration multi-agents et niveaux d'outils

L'installateur configure 43 surfaces clientes : 37 détectées automatiquement et 6 conditionnelles, conditionnel signifiant que l'installateur n'écrit que lorsque la plateforme documentée ou un chemin de configuration déjà existant prouve que la cible est active. Pour les clients avec un format d'agent personnalisé documenté, l'installateur crée trois définitions à partir d'un contrat canonique : Scout (niveau 1), environ 3 à 4 appels étroits pour une découverte préliminaire rapide ; Verify (niveau 2, par défaut), des preuves de graphe orientées tâche ; et Auditor (niveau 3), un périmètre borné avec des limitations non résolues explicites. La matrice du README couvre des clients comme Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, VS Code, Cursor et d'autres, avec des notes sur les hooks installés ou retenus. Elle précise aussi que les hooks installés sont fail-open et uniquement contextuels, et que les clients sans événement de cycle de vie générant du contexte stable reçoivent des fichiers durables qui portent le contrat entre les sessions. Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale.

L'artefact de graphe partagé en équipe

L'indexation produit un seul fichier compressé, .codebase-memory/graph.db.zst, qui peut être committé dans le dépôt afin que les coéquipiers évitent une réindexation complète. C'est un instantané SQLite compressé en zstd : index retirés, compactage via VACUUM INTO, puis compression avec zstd 1.5.7, avec un rapport typique de 8 pour 1 à 13 pour 1. Deux niveaux existent : best, avec zstd -9 plus retrait des index et VACUUM INTO, écrit lors d'un index_repository explicite, et fast, avec zstd -3, écrit par le watcher pour des mises à jour incrémentales à faible latence. Lorsqu'un coéquipier exécute codebase-memory-mcp sans base locale mais avec l'artefact présent, index_repository importe d'abord l'artefact puis exécute l'indexation incrémentale, évitant le coût complet de réindexation. Le README indique qu'une ligne .gitattributes avec merge=ours est créée automatiquement au premier export afin que les modifications concurrentes n'entrent pas en conflit sur l'artefact binaire, et que l'artefact est facultatif. Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale.

Mode CLI et outils de requête

Chaque outil MCP peut être invoqué comme commande locale à exécution unique : codebase-memory-mcp cli <tool>, avec des drapeaux générés depuis le schéma d'entrée de l'outil, consultables via cli <tool> --help. Les commandes CLI ne démarrent ni ne se connectent au démon de coordination et ne laissent aucun processus persistant. Les commandes qui modifient les données utilisent des verrous partagés par projet, appuyés sur le système d'exploitation, sérialisant les travaux en conflit sur le même projet tout en laissant les projets sans rapport avancer indépendamment. La progression va uniquement vers stderr, laissant stdout exploitable par machine pour le résultat de la commande ; --progress force l'affichage quand stderr est redirigé, et --json renvoie l'enveloppe complète du résultat MCP. Les outils de requête incluent search_graph, trace_path, detect_changes, query_graph avec un sous-ensemble openCypher en lecture seule, get_code_snippet, get_architecture, search_code, manage_adr et ingest_traces. Tout ce qui sort du sous-ensemble Cypher pris en charge échoue avec une erreur unsupported claire plutôt que de renvoyer des résultats vides. Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale.

Confidentialité, diagnostic et licence MIT

Le README déclare que l'outil fonctionne 100 % en local, ne collecte aucune télémétrie et que le code, les requêtes, l'environnement et l'usage ne quittent jamais la machine. C'est précisément pour cela que, lorsqu'un problème ne peut pas être reproduit côté mainteneur, l'utilisateur doit capturer les données lui-même : définir CBM_DIAGNOSTICS=1 avant le démarrage de la première session adossée au démon fait écrire au démon un fichier de tendance mémoire trajectory.ndjson, une ligne JSON toutes les 5 secondes avec rss, committed, peak, page_faults, fd et queries, plus un snapshot.json. Le projet est publié sous licence MIT, qui accorde le droit d'utiliser, copier, modifier, fusionner, publier, distribuer, sous-licencier et vendre des copies, et fournit le logiciel tel quel, sans garantie. Le texte de licence ne dit rien sur la posture de sécurité, les engagements de support ou l'aptitude à la production ; le README affirme en revanche que les binaires de sortie sont signés, munis de sommes de contrôle et analysés par plus de 70 moteurs antivirus. Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale.

Conclusion éditoriale

Le test le plus parlant commence par index_repository sur un petit dépôt, puis search_graph, trace_path et get_code_snippet. Pour l’artefact partagé, observez .codebase-memory/graph.db.zst et la règle merge=ours dans .gitattributes. Le mode CLI se lance avec codebase-memory-mcp cli <tool> --help et renvoie la progression sur stderr ; --json fournit l’enveloppe MCP. Pour le diagnostic, CBM_DIAGNOSTICS=1 doit être défini avant la première session afin de produire trajectory.ndjson et snapshot.json. Ces repères rendent vérifiables l’index, les requêtes, le partage et la collecte locale. Ce projet s’adresse aux lecteurs capables de vérifier ces éléments dans codebase-memory-mcp ; il ne convient pas à un usage fondé sur des garanties absentes du README.

Sources officielles

1. Official documentation
2. Official README
3. Project repository
4. Release notes