vault-compiler — building a knowledge base that keeps up with you

I rediscovered a pattern I’d already figured out three weeks earlier.

Same bug. Same ServiceNow REST quirk where the API silently drops fields you didn’t include in the sysparm list. Same two hours poking at it. The second time I even had the feeling of remembering — the shape of the answer sitting behind my eyes and I couldn’t quite grab it.

I stopped, went to my vault, searched, and found it. A perfectly fine note from three weeks ago. Written by me. Explaining exactly the thing I’d just spent the morning re-learning.

That was the moment.

The llm-wiki idea

Around the same week I’d read Karpathy riffing on the idea of an “llm-wiki” — the notion that the right place for your accumulated knowledge isn’t a polished public blog, it’s a private wiki your models can read. The frame clicked immediately. I’d been trying to build documentation. What I actually wanted was a wiki for my own work that my agents could also use.

The problem wasn’t where to put the notes. I had Obsidian. I’ve had Obsidian for years. I love Obsidian.

The problem was that I never opened it during work.

I’d open it at the end of a session, sometimes. Usually I’d forget. By the time I remembered, the thing I wanted to write down had blurred into “something about ACLs, I think?” and I’d close the tab and tell myself I’d remember next time.

Reader, I did not remember next time.

The first version was bolted to one project

The first version lived inside my servicenow-skills repo and was called sn-compiler. Small TypeScript script, a handful of modes — flag mid-session, drain flags into drafts at session end, promote a draft into the vault. Scoped tightly to that one project.

It worked. For about a week I actually captured things.

Then I opened a different project — the crypto stuff — hit a gotcha I wanted to capture, and realized my little compiler was trapped inside one repo. The tool that was supposed to keep up with me only kept up when I was working on one thing.

So I extracted it into vault-compiler and made it project-agnostic. Any repo with a vault/ directory, any stack. The compiler resolves paths from $(pwd) and gets out of the way.

The pipeline

Five modes, all verbs:

• flag — mid-session capture. I or the agent drop a JSON marker into vault/.flags/ the instant something notable happens. Intent, evidence, type, confidence, tags.
• drain — at session end, flags turn into drafts in vault/drafts/. Consumed flags get archived so nothing runs twice.
• review — list what’s pending.
• promote — move a draft into vault/discoveries/ or vault/patterns/. The only step that really requires me to think.
• graph — walk the vault, build an adjacency map from wikilinks and tags, compute centrality, write out vault/_map.md and vault/_map.json.

I only really do review and promote myself. Everything else runs from hooks.

The best capture is the one you don’t have to remember

A Stop hook runs drain at the end of every session. A PostToolUse hook re-runs graph whenever a file in the vault changes. I don’t have to remember either one. I don’t have to context-switch. I don’t have to open Obsidian mid-debug to file a thought.

I just say “flag that” to the agent I’m pairing with, or the agent notices something on its own and flags it, and the pipeline takes it from there. By morning there’s a stack of drafts waiting for me to skim and promote.

The entire capture problem was a willpower problem, and the fix was removing willpower from the equation.

What the graph actually shows you

The first time I ran graph on a vault that had been accumulating for months I wasn’t expecting it to surprise me. I thought I knew what was in there.

I was wrong about which notes were load-bearing. The centrality map had one tiny three-paragraph note about idempotency in upsert operations sitting at the middle of a cluster I didn’t know existed. A dozen other notes linked to it. I’d written it on a Tuesday afternoon and forgotten about it the same day.

That’s what the graph tells you. Not “here’s what you wrote” — I already knew that. It tells you which ideas in your head are doing the most work. Which ones keep getting reached for. Which discoveries turned out to be the quiet foundations under everything else.

Once I could see that, I started writing differently. The central notes get more care. The orphans get linked up or pruned.

Why I needed this to exist

I don’t think I’m unusually forgetful. I think AI-assisted work generates insights faster than any manual capture process can absorb them. Five years ago I’d finish a day with one or two things worth writing down. These days it’s closer to ten, across three projects, and half are things my agent noticed before I did.

If I don’t have a pipeline that runs while I work, I lose them. Three weeks later I spend two hours re-learning them.

Not anymore. (Or at least — a lot less often. I’m not above rediscovering things. I’d just rather the rediscovery happen once.)

-D