Navigation-De-Code | Antoine Weill--Duflos

cortexmd : un cerveau de mémoire à long terme et de navigation de code pour agents IA

Wed, 03 Jun 2026 00:00:00 +0000

cortexmd est un cerveau de mémoire à long terme et de navigation de code pour agents IA, exposé via le Model Context Protocol. Tout a commencé par un projet privé sur mon homelab appelé obsidian-mcp, un serveur qui permettait à Claude de lire, chercher et écrire des notes dans mon coffre Obsidian. Je l’ai construit pour moi, puis je l’ai nettoyé pour le partager.

Il fait deux choses.

La première, c’est la mémoire. Les agents oublient tout d’une session à l’autre. cortexmd leur offre un endroit où déposer ce qu’ils apprennent : des mémoires auto-catégorisées en types comme observation, décision, intuition et plan, avec un cycle de vie thermique où lire une mémoire la réchauffe et l’inactivité la refroidit. Le rappel est hybride, fusionnant la recherche plein texte et la recherche sémantique, amplifié par la température et les liens. Au début d’une session, l’agent effectue un réveil qui fait remonter les mémoires les plus chaudes et les plus pertinentes, pour reprendre là où il s’était arrêté.

La seconde, c’est la navigation de code. Un indexeur en Rust parcourt un dépôt, l’analyse avec tree-sitter et construit une base de données de symboles en SQLite qui enregistre, pour chaque symbole, son nom, son type, sa signature, sa docstring, sa plage dans le fichier et son graphe d’appels. Cet index est exposé sous forme d’outils MCP peu coûteux : recherche de symboles, plan de fichier, appelants et appelés, impact des changements, chaîne d’appels, code mort, cycles d’import et doublons issus de copier-coller. L’objectif de conception est qu’un agent navigue dans le code en interrogeant l’index, à environ 60 jetons par résultat, plutôt qu’en lisant des fichiers entiers. Un hook shell optionnel réécrit des commandes comme grep et cat sur un dépôt indexé en l’appel de navigation de code équivalent.

L’élément qui l’a rendu publiable, c’est le modèle de coffre-cerveau (brain-vault). cortexmd possède un coffre-cerveau distinct qui est la seule chose dans laquelle il écrit. Vos propres coffres sont attachés en tant que sources en lecture seule, indexés pour la recherche et la navigation de code, jamais modifiés, avec une liste d’autorisation par refus par défaut pour que les sous-arbres privés restent à l’écart. Les données circulent dans un seul sens, donc il n’y a aucun fichier mutable partagé et aucune course à la fusion.

  SOURCE_VAULTS[]  (read-only, opt-in, allowlisted)
  ┌───────────┐  ┌───────────┐  ┌───────────┐
  │  notes/   │  │  code/    │  │  docs/    │
  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
        │  index (one-way, read)      │
        └──────────────┼──────────────┘
                       ▼
              ┌──────────────────┐
              │     cortexmd     │   <- sole writer
              │   (MCP server)   │
              └────────┬─────────┘
                       │ writes
                       ▼
              ┌──────────────────┐
              │   BRAIN_VAULT    │   memories · journal · diaries
              │ (own dir, not    │   tasks · KG notes · code-repos.json
              │  your vault)     │
              └──────────────────┘

Il fonctionne selon deux modes : un mode local-stdio sans Docker, sans authentification et sans réseau, recommandé pour une seule personne ; et un mode HTTP auto-hébergé avec authentification pour les configurations multi-clients. Le dépôt est un monorepo polyglotte, un serveur MCP en TypeScript et un binaire Rust unique, maintenus cohérents par un contrat partagé et une vérification de parité en CI.

cortexmd est en pré-alpha et sous licence MIT. Les API et les noms de configuration sont encore susceptibles de changer.

L’histoire complète est racontée dans une série de quatre billets de blog. Commencez par Donner un second cerveau à un agent IA.

Le tueur de tokens : naviguer dans le code sans le lire

Sat, 06 Jun 2026 00:00:00 +0000

Dans la deuxième partie, j’ai écrit sur la moitié de cortexmd qui combat l’oubli : le moteur de mémoire, avec sa chaleur, sa décroissance et son rêve nocturne. Ce billet parle de l’autre moitié, celle qui combat le gaspillage.

Voici le problème. Quand vous demandez à un agent IA de travailler sur une vraie base de code, le réflexe par défaut est de lire des fichiers. L’agent ouvre un fichier, le tout atterrit dans son contexte, et vous payez désormais pour chacune de ses lignes. La plupart de ces lignes sont du bruit pour la tâche en cours. Vous vouliez savoir ce que fait une fonction et qui l’appelle, et au lieu de cela vous avez acheté un fichier de mille lignes, plus ses imports, plus trois modules d’aide qu’il a tirés au passage par prudence. Faites cela quelques fois et la fenêtre de contexte se remplit de code que l’agent n’utilisera jamais, le signal est enseveli, et la facture est bien réelle.

La solution consiste à arrêter de lire le code pour commencer à l’interroger.

Un dépôt est un graphe, pas un tas de texte

L’intuition est ancienne, ennuyeuse et juste : le code source n’est pas vraiment un tas plat de texte. C’est un graphe de symboles. Des fonctions, des méthodes, des types, et les arêtes entre eux, qui appelle qui. Un IDE le sait. “Aller à la définition” et “trouver toutes les références” ne lisent pas vos fichiers de haut en bas à chaque clic. Ils consultent un index. cortexmd donne la même chose à un agent.

L’indexeur est un binaire Rust (cortexmd-cli, le même binaire qui embarque le client en ligne de commande et les hooks de session dont je parlerai plus loin). Il parcourt un dépôt, analyse chaque fichier avec tree-sitter, et écrit le résultat dans une base de données de symboles SQLite. Pour chaque symbole, il enregistre le nom, le genre (fonction, méthode, type, et ainsi de suite), la signature, la docstring s’il y en a une, la plage dans le fichier, et, point crucial, le graphe d’appels : les appelants et les appelés. tree-sitter est le bon outil ici parce qu’il est rapide, incrémental, et qu’il parle beaucoup de langages, si bien que la même passe d’indexation fonctionne sur un dépôt polyglotte au lieu d’exiger un parseur sur mesure par chaîne d’outils.

Une fois cette base de données en place, l’agent n’a plus jamais besoin d’ouvrir un fichier juste pour se repérer.

L’index est exposé aux clients MCP sous la forme d’un ensemble d’outils peu coûteux. Chacun répond à une question précise qu’un agent se pose réellement pendant qu’il travaille :

recherche de symboles : trouver des symboles par nom, signature, ou texte de docstring. Le point d’entrée vers tout le reste.
plan de fichier : la forme d’un fichier (ses symboles et leurs signatures) sans les corps. Vous obtenez la table des matières plutôt que le livre.
récupérer un symbole : extraire le corps d’exactement un symbole quand vous avez décidé que vous en aviez besoin, et rien d’autre.
appelants et appelés : parcourir le graphe d’appels dans un sens ou dans l’autre. Qui appelle ceci, et ce que ceci appelle.
impact d’un changement : la réponse transitive à “si je modifie ceci, qui casse ?”. C’est celui que je dégaine le plus souvent avant de toucher à quoi que ce soit de porteur.
chaîne d’appels : le chemin d’un symbole à un autre, pour voir comment A atteint réellement Z.
détection de code mort : les symboles vers lesquels rien ne pointe.
détection de cycles d’imports : là où le graphe de modules boucle sur lui-même.
détection de doublons sémantiques : la détection de copier-coller, les corps quasi identiques qui ont divergé.

Le motif est le même pour tous. L’agent restreint avant de lire. Rechercher pour trouver le symbole, dresser le plan pour voir le voisinage, consulter les appelants et l’impact d’un changement pour comprendre le rayon d’explosion, et seulement ensuite, s’il en a vraiment besoin, récupérer un symbole. La plupart des tâches n’exigent jamais un fichier complet.

Environ 60 tokens par résultat

Voici l’objectif de conception qui a guidé tout cela. Une recherche de navigation de code est censée coûter environ 60 tokens par résultat. Lire un fichier entier en coûte des milliers. Interroger l’index est donc censé revenir bien moins cher que lire, pour la même réponse utile.

Je veux être honnête sur ce qu’est ce chiffre et ce qu’il n’est pas. C’est une cible que j’ai visée en concevant l’outil, pas un résultat de référence que je vous cite. Le coût exact dépend du symbole, du langage, de la quantité de docstring. Mais sa forme générale est tout l’enjeu : un résultat est un enregistrement compact (nom, genre, signature, une plage, quelques arêtes), pas un pavé de code source. Quand l’unité de travail est un fait de 60 tokens au lieu d’un fichier de 2 000 tokens, un agent peut poser vingt questions pour le prix d’une lecture, et la fenêtre de contexte reste pleine de réponses au lieu de meule de foin.

Cela se lit aussi mieux pour le modèle. Une liste propre d’appelants est plus facile à raisonner que la même information étalée sur cinq fichiers que l’agent a dû charger pour la reconstituer.

Attraper la vieille habitude

Il y a un piège à donner de meilleurs outils à un agent : il doit penser à les utiliser. La mémoire musculaire d’“enquêter sur le code”, c’est grep, cat, head, tail. Ces habitudes sont profondes, et un agent y retombera volontiers et se mettra à charger des fichiers dans son contexte dès que vous cessez de surveiller.

Alors cortexmd embarque un hook shell optionnel. Quand il est activé et que vous travaillez dans un dépôt indexé, il réécrit ces commandes en leurs équivalents peu coûteux de navigation de code. Un grep cherchant un symbole devient une recherche de symboles. Un cat d’un fichier devient un plan de fichier. L’agent croit faire la vieille chose, et l’index répond discrètement à la place. C’est optionnel à dessein, parce que réécrire les commandes shell de quelqu’un est exactement le genre de magie à laquelle on veut consentir plutôt que la découvrir, et parce que la réécriture n’a de sens que sur un dépôt réellement indexé.

La belle propriété, c’est qu’il rejoint l’agent là où ses habitudes sont déjà. Vous n’avez pas à rééduquer le réflexe, vous l’interceptez simplement.

Le dogfooding sur son propre code source

Je n’ai pas testé cela sur un jouet. cortexmd est un monorepo polyglotte (TypeScript d’un côté, Rust de l’autre, j’y reviens dans la quatrième partie), et j’ai pointé l’indexeur sur le code source du projet lui-même pour travailler dessus à travers ses propres outils de navigation. C’est le test qui compte. Quand vous modifiez l’indexeur tout en naviguant avec l’indexeur, les aspérités vous trouvent vite. “L’impact d’un changement dit que rien ne casse, alors pourquoi ça a cassé” est une phrase très motivante à lire dans ses propres journaux.

Le dogfooding est aussi l’endroit où les deux moitiés de cortexmd se rencontrent. L’index de code dit à l’agent ce qu’est le code en ce moment. Le moteur de mémoire de la deuxième partie lui dit pourquoi le code est ce qu’il est, les décisions et les impasses qu’aucune base de données de symboles n’enregistrera jamais. La structure plus l’histoire. L’une s’interroge, l’autre se rappelle, et ensemble elles forment l’essentiel de ce que je veux qu’un collaborateur possède.

C’est encore une pré-alpha, donc les noms exacts des outils et la configuration vont bouger. L’idée sous-jacente est stable : naviguer dans le code en interrogeant un index, pas en lisant des fichiers, et payer 60 tokens pour un fait plutôt que des milliers pour une meule de foin.

Dans la quatrième partie, j’aborde la partie qui a transformé un outil privé de homelab en quelque chose que je pouvais mettre sur internet : pourquoi un outil entièrement réglé sur ma propre installation ne pouvait pas être partagé tel quel, la refonte autour du brain-vault qui l’a généralisé, et pourquoi je l’ai passé en open source.

La page du projet est ici, et le code se trouve sur github.com/Leicas/cortexmd.

Série

Donner un second cerveau à un agent IA
Le moteur de mémoire : chaleur, décroissance et rêves
Le tueur de tokens : naviguer dans le code sans le lire (vous êtes ici)
Ouvrir le cerveau : le modèle brain-vault

Donner un second cerveau à un agent IA

Thu, 04 Jun 2026 00:00:00 +0000

Je travaille avec un agent de programmation presque tous les jours maintenant. Il est vraiment bon. Il lit mon code, raisonne dessus, propose des changements, lance les tests, répare ce qu’il a cassé. Et chaque fois que j’ouvre une nouvelle session, il a la mémoire d’un poisson rouge.

Il ne se souvient pas de la décision que nous avons prise la semaine dernière sur la raison pour laquelle un module est structuré comme il l’est. Il ne se souvient pas que je préfère les virgules aux tirets, ni qu’un coin du code est porteur et fragile. Il ne se souvient pas de la conversation où nous avions écarté une approche pour de bonnes raisons. Tout ce contexte vivait dans la session précédente, et la session précédente n’existe plus. Alors je réexplique. Puis je réexplique encore le lendemain.

Voilà le premier problème. L’agent oublie.

Et il n’y a pas que le code. Dès que je lui demande de l’aide pour quoi que ce soit d’humain, le même trou s’ouvre. Demandez-lui de rédiger un e-mail et il n’a aucune idée de qui est le destinataire pour moi, s’il s’agit d’un ami proche, d’un collègue ou d’un partenaire avec qui je dois faire attention, et donc il ne sait pas quel ton adopter, parce que ce ton vivait dans des conversations passées qu’il ne peut plus voir. Il fait un mauvais travail pour relier une session à la suivante, si bien que chaque fil repart à froid. Et la façon dont je cloisonne ma vie aggrave les choses : le personnel dans un compte, le professionnel dans un autre, comme la plupart des gens. Dès que je passe de l’un à l’autre, tout ce que l’agent avait appris sur moi a tout simplement disparu. Pouf. Plus de mémoire.

Deux problèmes, pas un seul

Le second problème est plus discret, mais il apparaît sur chaque facture. Pour faire quoi que ce soit d’utile, l’agent doit comprendre le code, et la façon dont il comprend le code, c’est en le lisant. Donc il lit des fichiers. Des fichiers entiers. Pour répondre à une petite question sur une fonction, il va charger un module entier dans son contexte, et souvent les modules qui appellent ce module aussi. Multipliez cela sur une session de travail et vous payez, en tokens, pour charger le même code source encore et encore, dont la majeure partie n’a rien à voir avec la question posée.

Les deux problèmes viennent du même endroit : l’agent n’a aucun stockage persistant de ce qu’il a appris, et aucun moyen bon marché de consulter les choses. Il n’a que la fenêtre de contexte devant lui, et cette fenêtre est à la fois oublieuse et coûteuse à remplir.

J’ai décidé de m’attaquer aux deux. Pas parce que j’avais une idée de produit, mais parce que ça m’agaçait au quotidien et que j’avais un homelab qui ne demandait qu’à être utile.

Il y avait aussi une raison personnelle qui rendait la forme de la solution évidente. Il y a quelque temps, après avoir lu le long récit d’un ami sur son propre parcours de gestion de connaissances personnelles, je me suis mis à prendre des notes dans Obsidian. Construire ce second cerveau pour moi-même a changé ma façon de voir le problème. Si un coffre de notes liées fonctionne comme mémoire externe pour moi, il devrait fonctionner comme mémoire externe pour l’agent aussi. Je pouvais le laisser lire le mien pour démarrer, en lecture seule, puis le laisser construire le sien, un cerveau que je pourrais réellement ouvrir, parcourir et comprendre. Pas une boîte noire d’embeddings quelque part, mais des notes, dans un coffre, qui m’appartiennent.

L’origine sur le homelab

Depuis un moment, je fais tourner un petit serveur MCP sur mon homelab. MCP, le Model Context Protocol, est la manière standard de donner à un client IA des outils et des données qu’il peut aller chercher. Le serveur que j’avais construit s’appelait obsidian-mcp, et son premier rôle était simple : donner à Claude la capacité de lire, de chercher et d’écrire des notes dans mon coffre Obsidian.

Il tournait dans un conteneur Docker derrière un reverse proxy, mes notes étaient déjà là, et tout à coup l’agent pouvait y accéder. Cela seul était déjà utile. Mais cela transformait aussi le coffre en un endroit naturel où placer les réponses à mes deux problèmes, parce qu’un coffre n’est que du texte structuré qu’un agent peut lire et écrire, et c’est exactement ce sur quoi une mémoire et un index de code doivent reposer.

Le serveur a donc fait pousser deux nouvelles capacités, une pour chaque problème.

La première capacité est un système de mémoire, inspiré de mempalace, un projet de palais de mémoire pour agents IA. Au lieu de laisser tout s’évaporer à la fin d’une session, l’agent peut stocker ce qu’il apprend : une observation, une décision, une intuition, une préférence que j’ai exprimée à voix haute. Ces mémoires ne s’empilent pas simplement à l’infini dans une liste plate. Elles ont un cycle de vie. Celles qui servent restent chaudes et faciles à faire remonter, celles que personne ne touche refroidissent et finissent par être pliées dans des résumés, et au début d’une nouvelle session l’agent fait un réveil qui ramène à la surface les mémoires les plus chaudes et les plus pertinentes. L’objectif, c’est la continuité. L’agent reprend à peu près là où il s’était arrêté plutôt qu’à partir de zéro. C’est le sujet de la deuxième partie.

La seconde capacité est un index de code. Plutôt que de lire des fichiers entiers pour comprendre un dépôt, l’agent interroge un index de celui-ci. Un indexeur en Rust parcourt le dépôt, l’analyse et enregistre les choses que l’on veut réellement consulter : quels symboles existent, leurs signatures, où ils vivent, et surtout qui appelle qui. Ensuite l’agent pose des questions ciblées. À quoi ressemble cette fonction ? Qui l’appelle ? Qu’est-ce qui casse si je la modifie ? Chaque réponse est petite et bon marché, de l’ordre d’une consultation plutôt que d’une lecture complète, au lieu de traîner le fichier entier dans le contexte. L’objectif de conception est franc : une consultation de navigation de code devrait coûter environ soixante tokens par résultat et être bien moins chère que la lecture du fichier dont elle provient. C’est le sujet de la troisième partie.

D’un outil privé à cortexmd

Pendant des mois, ce fut une affaire personnelle. Ça tournait sur mon matériel, sur mon propre coffre Obsidian privé, celui qui contient à la fois des notes personnelles et professionnelles. Je n’en citerai rien ici, et l’outil lui-même est délibérément construit pour que les données restent les miennes. Mais le constat tient : c’était un outil que j’avais fait pour moi, et je l’utilisais tous les jours.

Puis je me suis heurté à un autre genre de mur, qui venait précisément de la façon dont il marchait bien pour moi. Je le raconterai correctement dans la quatrième partie, mais en résumé : tout était réglé sur ma propre installation, mon coffre, monté et synchronisé à ma façon, ce qui en faisait un excellent outil personnel et le rendait impossible à faire tourner pour quiconque d’autre. Le rendre partageable impliquait une refonte, et c’est cette refonte qui en a finalement fait quelque chose que d’autres pouvaient utiliser.

Cette refonte est devenue cortexmd. C’est open source, sous licence MIT, et public sur github.com/Leicas/cortexmd. C’est honnêtement en pré-alpha. Les API et les noms de configuration sont encore en mouvement, et je ne miserais pas un workflow de production dessus pour l’instant. Le cadrage honnête est le bon : j’ai construit ça pour moi, puis je l’ai nettoyé pour le partager. Le nettoyage est un vrai travail et il constitue l’essentiel de la quatrième partie.

Ce que c’est devenu : le panneau de contrôle de cortexmd. Cette capture provient de la démonstration autonome du projet, donc les données sont des exemples seedés, pas mon propre coffre.

Voilà donc la forme de la série. Il y avait deux problèmes, un agent qui oublie et un agent qui brûle des tokens à relire du code. Il y a deux réponses, un système de mémoire et un index de code, tous deux nés à l’intérieur d’un serveur MCP sur un homelab. Et il y a la refonte qui a transformé un outil privé en quelque chose que vous pouvez faire tourner vous-même.

Ce qui arrive

Partie 2, le moteur de mémoire. Chaleur, déclin et rêves. Les huit catégories dans lesquelles une mémoire peut tomber, le cycle de vie chaud vers tiède vers froid, la promotion à l’accès, la consolidation, le rappel hybride qui fusionne recherche plein texte et recherche sémantique, le réveil de session, et le graphe de liaison automatique qui relie les notes entre elles au fur et à mesure qu’elles sont stockées.
Partie 3, le tueur de tokens. L’indexeur en Rust et tree-sitter, la base de données de symboles SQLite, les outils de navigation de code, l’idée des environ soixante tokens par résultat, le hook shell optionnel qui réécrit des commandes comme grep et cat sur un dépôt indexé en leur équivalent bon marché, et ce que ça a donné de l’utiliser sur le propre code source du projet.
Partie 4, l’ouverture du cerveau en open source. Pourquoi un outil qui ne marchait que pour moi a dû être repensé pour être partagé, le modèle du brain-vault qui le généralise, les deux modes de déploiement, le monorepo polyglotte tenu ensemble par un contrat partagé, le renommage, et pourquoi je tiens à posséder mes propres données.

Si vous voulez sauter directement au code, la page du projet est par ici et le dépôt est sur GitHub. Sinon, la deuxième partie est l’endroit où l’agent commence à se souvenir.

Série

Ceci est la Partie 1 : Donner un second cerveau à un agent IA (vous êtes ici).

Partie 1 : Donner un second cerveau à un agent IA (ce billet)
Partie 2 : Le moteur de mémoire : chaleur, déclin et rêves
Partie 3 : Le tueur de tokens : naviguer dans le code sans le lire
Partie 4 : Ouvrir le cerveau en open source : le modèle brain-vault

Page du projet : cortexmd. Source : github.com/Leicas/cortexmd.

Navigation-De-Code | Antoine Weill--Duflos

cortexmd : un cerveau de mémoire à long terme et de navigation de code pour agents IA

Le tueur de tokens : naviguer dans le code sans le lire

Un dépôt est un graphe, pas un tas de texte

Les outils de navigation de code

Environ 60 tokens par résultat

Attraper la vieille habitude

Le dogfooding sur son propre code source

Série

Donner un second cerveau à un agent IA

Deux problèmes, pas un seul

L’origine sur le homelab

D’un outil privé à cortexmd

Ce qui arrive

Série