Claude | 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.

Ouvrir le code du cerveau : le modèle du brain-vault

Sun, 07 Jun 2026 00:00:00 +0000

Dans la partie 3 j’ai décrit le volet navigation de code de cette chose : un indexeur Rust qui parcourt un dépôt, construit une base de données de symboles, et permet à un agent d’interroger la structure du code pour à peu près le coût d’un simple grep au lieu de lire des fichiers entiers. Cela, plus le moteur de mémoire de la partie 2, constituait l’outil privé que je faisais tourner sur mon homelab depuis quelques mois. Ça marchait. Je l’utilisais tous les jours.

Mais il avait une limite inscrite dans ses fondations, et cette limite est la raison d’être de ce billet.

Le problème : il ne marchait que pour moi

La version privée, celle qui s’appelait encore obsidian-mcp à l’époque, était entièrement façonnée autour de mon installation. Elle lisait mon coffre Obsidian personnel, celui que je garde synchronisé entre mes machines et que je traite comme la source de vérité pour tout ce que je fais. Ses conventions, ses chemins, la façon dont elle découvrait et indexait les notes, tout supposait mon environnement, ma structure, mes habitudes. Au quotidien, c’était invisible. C’était un outil vraiment bon, et il s’améliorait à mesure que je m’appuyais dessus.

L’ennui, c’est qu’il était bon pour moi d’une façon qui le rendait impossible à confier à quelqu’un d’autre. Vous ne pouviez pas simplement le pointer sur vos propres notes et le voir fonctionner. Il attendait mon coffre, monté comme je le monte, synchronisé comme je le synchronise. Il lisait depuis un espace réglé pour exactement une personne, et cette personne, c’était moi. Comme outil personnel, c’était parfait. Comme projet à passer en open source, c’était une impasse, car la première chose sur laquelle tomberait tout autre utilisateur, c’est que toute la conception supposait discrètement qu’il était moi.

La question qui a guidé la refonte n’était donc pas comment corriger un bug. Elle était plus simple et plus exigeante : que faudrait-il pour qu’une personne qui n’est pas moi fasse tourner ceci sur ses propres notes, en toute sécurité, sans hériter de mon installation ? Y répondre honnêtement voulait dire séparer deux choses que la version privée avait emmêlées, les notes que je lis et les données que l’outil écrit.

La refonte : le modèle du brain-vault

Le correctif qui a rendu cortexmd partageable est presque embarrassant de simplicité une fois qu’on s’est brûlé. cortexmd possède son propre brain vault séparé, et ce brain vault est la seule chose dans laquelle il a le droit d’écrire. Mémoires, journal, journaux d’agents, tâches, notes du graphe de connaissances, la liste des dépôts de code indexés : tout cela vit dans le brain vault, et cortexmd en est l’unique rédacteur.

Vos propres coffres, ceux que vous modifiez à la main dans Obsidian, sont attachés en tant que coffres sources en lecture seule. cortexmd les indexe pour la recherche et la navigation de code, et il ne les modifie jamais. Pas une mise à jour de chaleur, pas une étiquette, pas un seul octet. Attacher un coffre source se fait sur option, avec une liste d’autorisation qui refuse par défaut, de sorte que vous pouvez garder des sous-arbres privés entièrement hors de l’index et n’exposer que les parties que vous voulez que l’agent voie.

Les données circulent dans un seul sens. Les coffres sources entrent, le brain vault sort, et les deux ne se chevauchent jamais. Vous attachez le coffre qui est le vôtre, l’outil le lit et n’y réécrit rien, et le cerveau qu’il construit vit entièrement ailleurs. C’est ce qui le rend général : il n’y a plus aucune supposition que le coffre soit le mien, monté à ma façon, ou synchronisé à ma façon. C’est aussi ce qui le rend sûr, car un outil qui n’écrit jamais dans vos notes ne peut pas les écraser, et il n’y a aucun fichier partagé qu’un agent de synchronisation puisse bifurquer. Le couplage qui maintenait la version privée collée à ma machine a tout simplement disparu.

  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)     │
              └──────────────────┘

Le brain vault par défaut est un répertoire de données dédié, quelque chose comme ~/.local/share/cortexmd/brain, jamais votre véritable coffre Obsidian. Vous pouvez le pointer ailleurs, mais le défaut garde les écritures de l’outil et vos notes dans deux endroits clairement séparés dès la première exécution.

Deux façons de le faire tourner

Une fois que l’histoire de l’écriture était saine, l’histoire du déploiement devait suivre. cortexmd se livre avec deux modes, et ils sont d’égale importance plutôt qu’un vrai et un de jouet.

Le défaut recommandé pour une seule personne est local-stdio. Il tourne sur votre propre machine, parle MCP via stdio avec n’importe quel client que vous utilisez, et lit vos coffres directement depuis le disque. Pas de synchronisation. Pas de Docker. Pas d’authentification. Aucun réseau du tout. Pour une personne sur une machine c’est tout ce dont vous avez besoin, et c’est le mode vers lequel j’orienterais presque tout le monde en premier. Tout l’intérêt de la refonte était qu’un seul utilisateur puisse obtenir le cerveau complet sans aucun du poids opérationnel que la version privée avait fini par accumuler autour d’elle.

Le second mode est l’auto-hébergement HTTP, et c’est explicitement la voie avancée. Ici cortexmd tourne comme un serveur Express avec une authentification en bonne et due forme (clé d’API ou OAuth2), et les coffres sources sont tirés en lecture seule via un transport. Ce transport est une interface que j’ai appelée la couture IVault, avec des implémentations pour le disque local, git-pull, WebDAV et S3. C’est le mode pour les configurations multi-clients ou véritablement distantes, où plusieurs clients MCP partagent un cerveau ou bien les données sources vivent ailleurs que sur le disque du serveur lui-même. Cela représente plus de pièces mobiles, et vous n’y avez recours que lorsque vous en avez réellement besoin.

L’important, c’est que les deux modes partagent le même modèle source-en-lecture-seule, cerveau-rédacteur-unique. Le mode HTTP conserve la même garantie : vos sources restent en lecture seule et le cerveau est la seule cible d’écriture. Il change seulement la façon dont les sources en lecture seule parviennent à l’indexeur.

Un monorepo polyglotte tenu ensemble par un contrat

L’autre chose que l’ouverture du code m’a forcé à nettoyer, c’est la couture entre les deux langages dont ce projet est fait, car ce sont vraiment deux projets portant un seul manteau.

packages/server est le serveur MCP en TypeScript : Node 22, Express, le moteur de mémoire, la logique de rappel, les définitions d’outils qui apparaissent aux clients sous l’espace de noms mcp__cortexmd__. crates/cli est un unique binaire Rust, cortexmd-cli, qui est l’indexeur tree-sitter plus le client en ligne de commande, les crochets de session, et le HUD de la barre d’état. Deux chaînes d’outils, collées ensemble par la CI.

La partie difficile d’une scission comme celle-ci, c’est l’endroit où elles doivent s’accorder exactement. Les identifiants de symboles que l’indexeur Rust produit doivent être identiques octet pour octet à ceux que le côté TypeScript attend, sinon toute la couche de navigation de code pointe silencieusement vers rien. Il y a donc un répertoire contract/ qui contient le format de fil partagé, la spécification des identifiants de symboles, et un jeu de golden fixtures. Une vérification de parité en CI fait passer les mêmes entrées à travers les deux côtés et fait échouer la compilation si le producteur Rust et le consommateur TypeScript sont un jour en désaccord sur ce que devrait être un identifiant. Le contrat est l’arbitre, et il garde les deux langages honnêtes sans qu’aucun n’ait à faire confiance à l’autre.

Le changement de nom, et ce que c’est maintenant

Quand j’ai rassemblé tout cela pour le partager, l’ancien nom ne convenait plus. obsidian-mcp décrivait ce que c’était au départ : un pont vers le coffre d’une seule application. Ce que c’était devenu, c’était un cerveau de mémoire et de navigation de code qui utilisait par hasard le markdown de style Obsidian comme un format de stockage parmi d’autres. Alors c’est devenu cortexmd, et c’est le nom sous lequel il se livre.

Une note d’honnêteté : ceci est en pré-alpha. C’est public et sous licence MIT à github.com/Leicas/cortexmd, et les noms de configuration ainsi qu’une partie des API sont encore mouvants. Je l’ai construit pour moi d’abord, l’ai fait tourner sur mon propre homelab au-dessus de mon propre coffre privé de notes personnelles et professionnelles, j’ai réalisé qu’il était câblé trop étroitement sur ma propre installation pour être partagé, je l’ai généralisé, puis je l’ai nettoyé suffisamment pour le mettre là où d’autres personnes peuvent l’utiliser. Ce n’est pas un produit fini et je ne prétends pas que c’en est un.

Ce dont je me sens bien, c’est de sa forme. Vos notes restent les vôtres, sur votre disque, en lecture seule, avec les parties privées exclues par défaut. Le cerveau que l’agent construit vit dans son propre endroit et ne va jamais retoucher vos fichiers. Dans le mode par défaut rien ne quitte votre machine : pas de cloud, pas de compte, pas de réseau. C’est la version local-first, propriétaire-de-vos-données de l’idée que je voulais vraiment depuis le début, et il a fallu la détacher de ma propre installation pour y arriver.

Si quoi que ce soit de tout cela vous est utile, la page du projet a la vue d’ensemble et les liens : cortexmd. Et si vous voulez le lire depuis le début, la partie 1 est l’endroit où la série commence.

Série

Ceci est la partie 4 d’une série en quatre parties sur cortexmd.

Partie 1 : Donner un second cerveau à un agent IA
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 code du cerveau : le modèle du brain-vault (vous êtes ici)

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

Le moteur de mémoire : chaleur, déclin et rêves

Fri, 05 Jun 2026 00:00:00 +0000

Dans la première partie j’ai décrit deux problèmes qui revenaient sans cesse me mordre quand je travaillais avec des agents IA. Le premier, c’est qu’ils oublient tout entre les sessions. Le second, c’est qu’ils brûlent des tokens à relire du code qu’ils ont déjà vu. Ce billet porte sur le premier problème, et sur la partie de cortexmd à laquelle je tiens le plus : le moteur de mémoire. L’approche d’ensemble est inspirée de mempalace, un projet de palais de mémoire pour agents IA ; ce qui suit, c’est la façon dont cortexmd en construit sa propre version.

La solution naïve à l’oubli, c’est de tout déverser dans le contexte. Garder un gros fichier de notes, le coller au début de chaque session et espérer que l’agent le lise. J’ai essayé des variantes de ça, et ça s’effondre vite. Le fichier grossit sans limite. Des faits anciens et périmés voisinent avec la seule chose qui compte vraiment aujourd’hui, sur un pied d’égalité. Vous payez pour toute la pile à chaque tour, et le signal qui vous intéresse se retrouve enseveli sous du bruit dont vous avez cessé de vous soucier depuis longtemps. Une mémoire humaine ne fonctionne pas comme ça, et elle ne le devrait pas. L’objectif de conception était donc simple à énoncer mais plus difficile à construire : l’agent devrait se souvenir comme le fait une personne, où ce que vous utilisez reste vif et ce que vous cessez de toucher s’estompe.

Huit sortes de mémoire

Quand un agent stocke quelque chose, cortexmd ne le traite pas comme un bloc de texte indifférencié. Chaque souvenir est auto-catégorisé dans l’une de huit sortes : observation, décision, idée, conversation, fait, préférence, plan et réflexion. La distinction compte parce que ces choses se comportent différemment dans le temps et veulent être retrouvées différemment. Une préférence (je veux toujours l’orthographe britannique, je déteste les tirets cadratins) est un fait durable sur ma façon de travailler, et elle devrait continuer à remonter. Un fragment de conversation est contextuel et surtout utile peu après qu’il s’est produit. Une décision est quelque chose que vous voulez pouvoir retrouver des mois plus tard quand vous vous demandez pourquoi diable vous avez fait ça. Étiqueter la sorte dès le départ donne au reste du système quelque chose à partir de quoi raisonner, au lieu de forcer chaque étape ultérieure à deviner à partir du texte brut.

Chaleur : chaud, tiède, froid

L’idée centrale est que chaque souvenir a une température, et que la température décline. Un souvenir frais ou récemment utilisé est chaud. Laissez-le intact et il refroidit vers tiède, puis après environ un mois d’inactivité il dérive vers froid, et les souvenirs plus froids finissent par être archivés plutôt que gardés au premier plan de l’esprit de l’agent.

Le détail crucial, c’est la promotion à l’accès : lire un souvenir le réchauffe. C’est toute l’astuce. Vous n’avez pas à curer manuellement ce qui est important. L’importance se révèle par l’usage. Les souvenirs vers lesquels vous et l’agent revenez sans cesse restent chauds précisément parce que vous revenez sans cesse vers eux, et ceux que vous ne touchez jamais coulent d’eux-mêmes. C’est le même instinct qu’un cache de type least-recently-used, sauf que ce qui est mis en cache, c’est le sens qu’a l’agent de ce qui compte en ce moment, et l’éviction est gracieuse : froid puis archivé, pas supprimé.

Pourquoi se donner tout ce mal au lieu d’un seul stock plat ? Parce que la température donne au rappel un a priori. Quand l’agent part chercher quelque chose, il ne fait pas face à une mer plate de notes également plausibles. Il a un sens intégré de ce qui a été actif récemment, et ce signal ne coûte rien de plus à maintenir parce qu’il découle de l’usage normal.

Consolidation : ranger le tiroir des froids

Laisser les souvenirs refroidir n’est que la moitié de l’histoire. Si vous laissez simplement les souvenirs froids s’empiler, vous vous retrouvez avec un tiroir plein de bouts quasi dupliqués : cinq notes légèrement différentes sur la même tâche terminée depuis longtemps, chacune un peu périmée, aucune ne valant la peine d’être lue seule. Alors cortexmd consolide. Les souvenirs froids apparentés sont repliés ensemble en résumés, de sorte que l’essentiel survive en un endroit cohérent tandis que les fragments redondants cessent d’encombrer. Le détail n’est pas jeté à la légère, il est compressé en quelque chose que vous voudriez réellement lire plus tard. Le refroidissement décide de ce qui n’est plus urgent ; la consolidation décide quoi en faire.

Rappel hybride

Bien stocker la mémoire ne sert à rien si vous ne pouvez pas la récupérer. Le rappel dans cortexmd est hybride. Il lance une recherche lexicale en texte intégral (la correspondance par mots-clés, bonne pour les termes et noms exacts) et la fusionne avec une recherche sémantique sur des embeddings (la correspondance par le sens, bonne quand vous vous souvenez de l’idée mais pas des mots). Le lexical seul rate tout ce qui est formulé autrement que votre requête. Le sémantique seul peut dériver vers des choses vaguement dans le sujet mais pas ce que vous vouliez dire. Fusionner les deux compense les faiblesses de chacun.

Par-dessus le score fusionné, le classement est rehaussé par trois choses : la température (les souvenirs plus chauds remontent, parce que la récence d’usage est un signal), l’importance (certains souvenirs sont simplement plus lourds) et les liens (un souvenir connecté à d’autres souvenirs pertinents est plus susceptible d’être celui que vous voulez). Le résultat est un classement qui reflète non seulement la similarité textuelle mais aussi à quel point un souvenir est actif et connecté. C’est bien plus proche de la façon dont vous vous rappelez réellement les choses qu’un simple score de similarité.

Le réveil

Tout cela se rejoint au début d’une session dans ce que j’appelle le réveil. Au lieu de commencer chaque conversation comme une page blanche, l’agent effectue un réveil de la mémoire qui fait remonter les souvenirs les plus chauds et les plus pertinents. C’est la différence entre un collègue qui entre en sachant déjà où vous en êtes restés hier et un que vous devez briefer de zéro chaque matin. Le réveil s’appuie sur tout ce qui précède : le modèle de chaleur décide ce qui est actif en ce moment, le rappel hybride décide ce qui est pertinent, et l’agent commence la session déjà orienté. C’est le moment où tout le moteur justifie son existence, parce que c’est le moment où vous sentez l’agent se souvenir de vous.

La phase smarter-brain : liens et rêves

Les pièces ci-dessus formaient le cœur du système de mémoire v2.0. Une phase ultérieure, que je vois comme le travail smarter-brain, a ajouté quelques choses qui font que le cerveau ressemble moins à une base de données et davantage à quelque chose qui réfléchit pendant que vous êtes absent.

L’onglet Intelligence du tableau de bord : santé du coffre, insights de rêve, grappes thématiques, et compteurs d’entités et du graphe de connaissances. Données de démonstration issues du coffre d’exemple seedé du projet.

La première, ce sont les liens automatiques du graphe de connaissances. À mesure que les données sont stockées, cortexmd trace de lui-même des liens entre les notes apparentées, au lieu d’attendre que je les câble à la main. Le lien manuel est exactement le genre de tâche administrative qui semble sympa et n’arrive jamais vraiment, donc avoir les connexions qui se forment automatiquement comme effet secondaire du stockage signifie que le signal de liens dans le rappel ne cesse de s’enrichir sans aucun effort de ma part.

La deuxième, c’est le rêve. cortexmd lance une passe de consolidation planifiée, sur un calendrier calme, que j’ai nommée le rêve à cause de ce qu’elle fait et du moment où elle le fait. Elle réconcilie les notes similaires, avec une attention particulière aux plus anciennes, celles qui ont refroidi, et les replie dans des notes de projet. C’est le jardinier d’arrière-plan du cerveau : pendant qu’il ne se passe rien, il parcourt les coins refroidis, remarque que ces trois pensées à moitié finies ne sont en réalité qu’une seule chose, et les range en une note de projet cohérente. Vous réveillez l’agent le lendemain et le cerveau est un peu mieux organisé que vous ne l’aviez laissé, sans que vous n’ayez rien fait.

La troisième, c’est quelque chose que j’ai emprunté tel quel à Obsidian : une vue graphe du coffre, rendue sur un canvas dans le tableau de bord web. Parce que le graphe de connaissances est réel, vous pouvez le regarder. Voir le cerveau comme une constellation de notes liées, avec les grappes denses et les orphelins solitaires étalés devant vous, rend le tout concret d’une manière qu’une liste de lignes ne fait jamais.

La vue graphe du coffre dans le tableau de bord. Chaque point est une note, chaque trait un lien. C’est le coffre de démonstration autonome du projet : les noms de notes sont des données d’exemple seedées, pas mes propres notes.

Cliquez sur un nœud et la note s’ouvre dans le panneau latéral avec ses liens. Mêmes données de démonstration seedées.

Pourquoi un modèle de chaleur l’emporte

Pour rassembler le tout : la raison pour laquelle un modèle de chaleur bat le fait de tout déverser dans le contexte, c’est que l’attention est la ressource rare, pour un agent exactement comme pour une personne. Un stock plat traite une note d’il y a huit mois et une décision de ce matin comme des égaux, vous fait payer pour les deux à chaque tour, et force l’agent à redécouvrir ce qui compte à chaque fois. Le modèle de chaleur encode ce qui compte comme une propriété des données elles-mêmes, le tient à jour gratuitement par l’usage ordinaire, compresse ce qui a refroidi au lieu de l’accumuler, et fait remonter la tranche active et pertinente au réveil. L’agent porte moins, et ce qu’il porte, c’est ce qu’il faut.

Voilà pour l’oubli. L’autre moitié du problème d’origine, l’agent qui brûle des tokens à relire du code qu’il a déjà vu, demande un mécanisme complètement différent. C’est un indexeur Rust et une base de données de symboles, et c’est le sujet de la troisième partie : le tueur de tokens.

cortexmd est en pré-alpha et sous licence MIT. Le code, y compris le moteur de mémoire décrit ici, vit sur la page du projet et sur GitHub à github.com/Leicas/cortexmd. Les noms et la configuration sont encore mouvants, alors traitez les détails comme un instantané plutôt que comme un contrat.

Série

Ceci est la deuxième partie d’une série de quatre billets sur cortexmd :

Donner un second cerveau à un agent IA
Le moteur de mémoire : chaleur, déclin et rêves (vous êtes ici)
Le tueur de tokens : naviguer dans le code sans le lire
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.

Claude | Antoine Weill--Duflos

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

Ouvrir le code du cerveau : le modèle du brain-vault

Le problème : il ne marchait que pour moi

La refonte : le modèle du brain-vault

Deux façons de le faire tourner

Un monorepo polyglotte tenu ensemble par un contrat

Le changement de nom, et ce que c’est maintenant

Série

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

Le moteur de mémoire : chaleur, déclin et rêves

Huit sortes de mémoire

Chaleur : chaud, tiède, froid

Consolidation : ranger le tiroir des froids

Rappel hybride

Le réveil

La phase smarter-brain : liens et rêves

Pourquoi un modèle de chaleur l’emporte

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