Code-Navigation | Antoine Weill--Duflos

cortexmd: a long-term memory and code-navigation brain for AI agents

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

cortexmd is a long-term memory and code-navigation brain for AI agents, exposed over the Model Context Protocol. It started as a private project on my homelab called obsidian-mcp, a server that let Claude read, search, and write notes in my Obsidian vault. I built it for myself, then cleaned it up to share.

It does two things.

The first is memory. Agents forget everything between sessions. cortexmd gives them somewhere to put what they learn: memories auto-categorised into kinds like observation, decision, insight, and plan, with a heat lifecycle where reading a memory warms it and inactivity cools it down. Recall is hybrid, fusing full-text and semantic search, boosted by temperature and links. At the start of a session the agent does a wakeup that surfaces the hottest, most relevant memories, so it picks up where it left off.

The second is code navigation. A Rust indexer walks a repo, parses it with tree-sitter, and builds a SQLite symbol database recording each symbol’s name, kind, signature, docstring, file range, and call graph. That index is exposed as cheap MCP tools: symbol search, file outline, callers and callees, change-impact, call-chain, dead code, import cycles, and copy-paste duplicates. The design goal is that an agent navigates code by querying the index, at roughly 60 tokens per result, instead of reading whole files. There is an opt-in shell hook that rewrites things like grep and cat on an indexed repo into the equivalent code-nav call.

The piece that made it shippable is the brain-vault model. cortexmd owns a separate brain vault that is the only thing it ever writes to. Your own vaults are attached as read-only sources, indexed for search and code-nav, never modified, with a default-deny allowlist so private subtrees stay out. Data flows one way, so there is no shared mutable file and no merge race.

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

It runs in two modes: a local-stdio mode with no Docker, no auth, and no network, recommended for one person; and a self-hosted HTTP mode with auth for multi-client setups. The repo is a polyglot monorepo, a TypeScript MCP server and a single Rust binary, kept honest by a shared contract and a CI parity check.

cortexmd is pre-alpha and MIT licensed. APIs and config names are still in flux.

The full story is in a four-part blog series. Start with Giving an AI Agent a Second Brain.

The Token Killer: Navigating Code Without Reading It

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

In part two I wrote about the half of cortexmd that fights forgetting: the memory engine, with its heat and decay and its nightly dream. This post is about the other half, the half that fights waste.

Here is the problem. When you ask an AI agent to work on a real codebase, the default move is to read files. The agent opens a file, the whole thing lands in its context, and now you are paying for every line of it. Most of those lines are noise for the task at hand. You wanted to know what one function does and who calls it, and instead you bought a thousand-line file plus imports plus three helper modules it pulled in to be safe. Do that a few times and the context window is full of code the agent will never use, the signal is buried, and the bill is real.

The fix is to stop reading code and start querying it.

A repo is a graph, not a pile of text

The insight is old and boring and correct: source code is not really a flat pile of text. It is a graph of symbols. Functions, methods, types, and the edges between them, who calls whom. An IDE knows this. “Go to definition” and “find all references” do not read your files top to bottom every time you click. They consult an index. cortexmd gives an agent the same thing.

The indexer is a Rust binary (cortexmd-cli, the same binary that ships the CLI client and the session hooks I will get to). It walks a repo, parses each file with tree-sitter, and writes the result into a SQLite symbol database. For every symbol it records the name, the kind (function, method, type, and so on), the signature, the docstring if there is one, the file range, and, crucially, the call graph: callers and callees. tree-sitter is the right tool here because it is fast, it is incremental, and it speaks a lot of languages, so the same indexing pass works across a polyglot repo instead of needing one bespoke parser per toolchain.

Once that database exists, the agent never has to open a file just to orient itself.

The code-nav tools

The index is exposed to MCP clients as a set of cheap tools. Each one answers a specific question that an agent actually asks while working:

symbol search: find symbols by name, signature, or docstring text. The entry point into everything else.
file outline: the shape of a file (its symbols and their signatures) without the bodies. You get the table of contents instead of the book.
get one symbol: pull the body of exactly one symbol when you have decided you need it, and nothing else.
callers and callees: walk the call graph in either direction. Who calls this, what does this call.
change impact: the transitive answer to “if I change this, who breaks?” This is the one I reach for most before touching anything load-bearing.
call chain: the path from one symbol to another, so you can see how A actually reaches Z.
find dead code: symbols nothing resolves to.
find import cycles: where the module graph loops back on itself.
find semantic duplicates: copy-paste detection, the near-identical bodies that drifted apart.

The code-nav savings view, with cortexmd indexing its own repository (the project dogfooding its indexer). The figures here come from the project’s seeded demo, not a formal benchmark.

The pattern across all of them is the same. The agent narrows before it reads. Search to find the symbol, outline to see the neighbourhood, callers and change-impact to understand the blast radius, and only then, if it truly needs the body, get one symbol. Most tasks never need a full file at all.

Roughly 60 tokens per result

Here is the design goal that drove the whole thing. A code-nav lookup is meant to cost roughly 60 tokens per result. Reading a whole file costs thousands. So querying the index is meant to be many times cheaper than reading, for the same useful answer.

I want to be honest about what that number is and is not. It is a target I designed toward, not a benchmark I am quoting at you. The exact cost depends on the symbol, the language, how much docstring there is. But the shape of it is the entire point: a result is a compact record (name, kind, signature, a range, some edges), not a slab of source. When the unit of work is a 60-token fact instead of a 2,000-token file, an agent can ask twenty questions for the price of one read, and the context window stays full of answers instead of haystack.

It also reads better for the model. A clean list of callers is easier to reason over than the same information smeared across five files the agent had to load to reconstruct it.

Catching the old habit

There is a catch with giving an agent better tools: it has to remember to use them. The muscle memory of “investigate the code” is grep, cat, head, tail. Those habits are deep, and an agent will happily fall back to them and start hauling files into context the moment you stop watching.

So cortexmd ships an opt-in shell hook. When it is on and you are working in an indexed repo, it rewrites those commands into their cheap code-nav equivalents. A grep for a symbol becomes a symbol search. A cat of a file becomes a file outline. The agent thinks it is doing the old thing, and the index quietly answers instead. It is opt-in on purpose, because rewriting someone’s shell commands is exactly the kind of magic you want to consent to rather than discover, and because the rewrite only makes sense on a repo that is actually indexed.

The nice property is that it meets the agent where its habits already are. You do not have to retrain the reflex, you just intercept it.

Dogfooding on its own source

I did not test this on a toy. cortexmd is a polyglot monorepo (TypeScript on one side, Rust on the other, more on that in part four), and I pointed the indexer at the project’s own source and worked on it through its own code-nav tools. That is the test that matters. When you are changing the indexer while navigating with the indexer, the rough edges find you fast. “Change impact says nothing breaks, so why did that break” is a very motivating sentence to read in your own logs.

Dogfooding is also where the two halves of cortexmd meet. The code index tells the agent what the code is right now. The memory engine from part two tells it why the code is the way it is, the decisions and the dead ends that no symbol database will ever record. Structure plus history. One is queried, one is recalled, and together they are most of what I want a collaborator to have.

This is still pre-alpha, so the exact tool names and config will move around. The idea underneath is stable: navigate code by querying an index, not by reading files, and pay 60 tokens for a fact instead of thousands for a haystack.

In part four I get to the part that turned a private homelab tool into something I could put on the internet: why a tool tuned entirely to my own setup could not be shared as-is, the brain-vault redesign that generalised it, and why I open-sourced it.

The project page is here, and the code is at github.com/Leicas/cortexmd.

Series

Giving an AI Agent a Second Brain
The Memory Engine: Heat, Decay, and Dreams
The Token Killer: Navigating Code Without Reading It (you are here)
Open-Sourcing the Brain: the Brain-Vault Model

Giving an AI Agent a Second Brain

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

I work with a coding agent most days now. It is genuinely good. It reads my code, reasons about it, proposes changes, runs the tests, fixes what it broke. And every single time I open a fresh session, it has the memory of a goldfish.

It does not remember the decision we made last week about why a module is structured the way it is. It does not remember that I prefer commas to dashes, or that one corner of the codebase is load-bearing and fragile. It does not remember the conversation where we ruled out an approach for good reasons. All of that context lived in the previous session, and the previous session is gone. So I re-explain. Then I re-explain again the next day.

That is the first problem. The agent forgets.

And it is not only the code. The moment I ask it to help with anything human, the same hole opens up. Ask it to draft an email and it has no idea who the recipient is to me, whether this is a close friend, a colleague, or a partner I need to handle with care, so it has no idea what tone to take, because the tone lived in past conversations it can no longer see. It does a poor job of linking one session to the next, so every thread starts cold. And the way I keep my life split makes it worse: personal in one account, work in another, the way most people do. The moment I cross from one to the other, whatever the agent had learned about me is simply gone. Poof. No memory.

Two problems, not one

The second problem is quieter but it shows up on every invoice. To do anything useful, the agent has to understand the code, and the way it understands code is by reading it. So it reads files. Whole files. To answer a small question about one function, it will pull an entire module into context, and often the modules that call that module too. Multiply that across a working session and you are paying, in tokens, to load the same source over and over, most of which is irrelevant to the question at hand.

Both problems come from the same place: the agent has no persistent store of what it has learned, and no cheap way to look things up. It only has the context window in front of it, and the context window is both forgetful and expensive to fill.

I decided to do something about both. Not because I had a product idea, but because it was annoying me on a daily basis and I had a homelab sitting there asking to be useful.

There was also a personal reason the shape of the solution felt obvious. A while ago, after reading a friend’s long write-up of his own personal-knowledge-management journey, I started keeping notes in Obsidian. Building that second brain for myself changed how I thought about the problem. If a vault of linked notes works as external memory for me, it should work as external memory for the agent too. I could let it read mine to get started, as a read-only source, and then let it build its own brain, one that I could actually open, navigate, and understand. Not a black box of embeddings somewhere, but notes, in a vault, that I own.

The homelab origin

For a while now I have run a small MCP server on my homelab. MCP, the Model Context Protocol, is the standard way to give an AI client tools and data it can reach out to. The server I built was called obsidian-mcp, and its first job was simple: give Claude the ability to read, search, and write notes in my Obsidian vault.

It ran in a Docker container behind a reverse proxy, my notes were already there, and suddenly the agent could reach into them. That alone was useful. But it also turned the vault into a natural place to put the answers to my two problems, because a vault is just structured text that an agent can read and write, and that is exactly what both a memory and a code index need to be backed by.

So the server grew two new capabilities, one for each problem.

The first capability is a memory system, inspired by mempalace, a memory-palace project for AI agents. Instead of letting everything evaporate at the end of a session, the agent can store what it learns: an observation, a decision, an insight, a preference I stated out loud. Those memories do not just pile up forever in a flat list. They have a lifecycle. The ones that get used stay warm and easy to surface, the ones nobody touches cool off and eventually get folded into summaries, and at the start of a new session the agent does a wakeup that brings the hottest, most relevant memories back to the surface. The point is continuity. The agent picks up roughly where it left off instead of from zero. That is the subject of part two.

The second capability is a code index. Rather than read whole files to understand a repository, the agent queries an index of it. A Rust indexer walks the repo, parses it, and records the things you actually want to look up: what symbols exist, their signatures, where they live, and crucially who calls whom. Then the agent asks targeted questions. What does this function look like? Who calls it? What breaks if I change it? Each answer is small and cheap, on the order of a lookup rather than a full read, instead of dragging the entire file into context. The design goal is blunt: a code-nav lookup should cost roughly sixty tokens per result and be many times cheaper than reading the file it came from. That is the subject of part three.

From a private tool to cortexmd

For months this was a personal thing. It ran on my hardware, over my own private Obsidian vault, the one that holds both personal and work notes. I am not going to quote any of it here, and the tool itself is deliberately built so that the data stays mine. But the point stands: it was a tool I made for myself, and I used it every day.

Then I hit a different kind of wall, one that came precisely from how well it worked for me. I will tell it properly in part four, but the short version is that the whole thing was tuned to my own setup, my vault, mounted and synced my way, so it was a great personal tool and impossible for anyone else to run. Making it shareable meant a redesign, and that redesign is what finally turned it into something other people could use.

That redesign became cortexmd. It is open source, MIT licensed, and public at github.com/Leicas/cortexmd. It is honestly pre-alpha. The APIs and the config names are still in flux, and I would not bet a production workflow on it yet. The honest framing is the right one: I built this for myself, then cleaned it up to share. The cleanup is real work and it is most of part four.

What it became: the cortexmd control panel. This screenshot is from the project’s self-contained demo, so the data is seeded samples, not my own vault.

So that is the shape of the series. There were two problems, an agent that forgets and an agent that burns tokens re-reading code. There are two answers, a memory system and a code index, both born inside a homelab MCP server. And there is the redesign that turned a private tool into something you can run yourself.

What is coming

Part 2, the memory engine. Heat, decay, and dreams. The eight categories a memory can fall into, the hot to warm to cold lifecycle, promote-on-access, consolidation, hybrid recall that fuses full-text and semantic search, the session wakeup, and the auto-linking graph that wires notes together as they are stored.
Part 3, the token killer. The Rust and tree-sitter indexer, the SQLite symbol database, the code-nav tools, the roughly sixty tokens per result idea, the opt-in shell hook that rewrites things like grep and cat on an indexed repo into the cheap equivalent, and what it was like to dogfood all of it on the project’s own source.
Part 4, open-sourcing the brain. Why a tool that only worked for me had to be redesigned to share, the brain-vault model that generalises it, the two deployment modes, the polyglot monorepo held together by a shared contract, the rename, and why I care about owning my own data.

If you want to skip ahead to the code, the project page is over here and the repo is on GitHub. Otherwise, part two is where the agent starts to remember.

Series

This is Part 1: Giving an AI Agent a Second Brain (you are here).

Part 1: Giving an AI Agent a Second Brain (this post)
Part 2: The Memory Engine: Heat, Decay, and Dreams
Part 3: The Token Killer: Navigating Code Without Reading It
Part 4: Open-Sourcing the Brain: the Brain-Vault Model

Project page: cortexmd. Source: github.com/Leicas/cortexmd.