A year of running Obsidian with Claude Code, and the 2% of my vault that does all the work.
For most of a year, every session started the same way. I'd open a terminal and spend the first fifteen minutes explaining my own project to my own assistant. What we were building. What we'd already tried. Which of the obvious ideas were obvious and already dead. Then I'd get a good answer, close the window, and lose all of it.
The cost was never the tokens. It was doing the same unpaid setup work every morning to get back to where I'd been the night before.
So I did the boring thing: put everything in a folder of markdown files and pointed the agent at it. No plugins, no vector database, no embeddings. Just notes on disk that both of us can read and write.
That worked, and it isn't really what this article is about. After a year, the folder turns out to be the least interesting part. What makes the system work is a small set of documents whose only job is to tell a reader — me, or the model — how to read everything else. They're maybe 2% of the words in the vault, and they carry nearly all of the judgment.
Here's how I found that out.
The critique that was completely correct and completely useless
I asked the agent to argue against the direction I was taking a project. It read the vault and came back with the best version of a thesis I had abandoned two months earlier. Structured, sourced, quoting my own notes back at me — accurately, because I had in fact written all of it.
I sat with it a while before I noticed. That's the part worth dwelling on: nothing about it felt wrong. It wasn't a hallucination. Every claim traced back to something I'd written and believed at the time.
The notes describing the dead thesis were the most thorough notes in the vault. I'd spent two months on that idea, which is exactly why there was so much material and exactly why it made the strongest case. Abandoning it had taken one afternoon and left almost no trace.
That's the thing nobody warns you about. A model reading your notes can't tell a live idea from a buried one, and the weight of evidence points the wrong way, because the dead ideas are usually the well-documented ones. Retrieval was never the hard part. The hard part is ranking, and the ranking isn't in the notes. It's in your head, where it does nobody any good.
Everything below is a way of getting it out.
Sort by how long things live, not by what they're about
My first structure was topical and it rotted within weeks. Most notes belong to three topics at once, so every filing decision turned into a small argument with myself, and the arguments accumulated until the inbox won.
A note has many topics but exactly one lifetime. So the top level is organized by that instead: an inbox for anything without a home yet, one note per ongoing responsibility that never ends, one folder per project that has an actual end state, and an archive for the finished. That's the entire taxonomy.
Filing takes seconds now, because there's only ever one right answer. The topics didn't go anywhere. They live in the links between notes, which is where they belonged in the first place.
Put the rules inside the folder
The most useful document in my vault is four lines long, and there's one in every folder. It says what belongs there, what doesn't, which template to use, and the single maintenance rule.
# Inbox
Anything that doesn't have an obvious home yet.
Process weekly: move it to the right folder, add the frontmatter, link it
to something. This folder should be empty on Friday.
# Areas
Ongoing responsibilities that never finish — health, tax, the apartment.
One note per area. Update it over time.
Do not create a new note per event.
I wrote those for myself, long before any of this. When I pointed the agent at the vault I realized I'd accidentally been writing prompts. It doesn't have to infer my system from folder names, because the system is written down, in the folder, next to the thing it governs.
That's the difference between a habit and a protocol. A habit only works while you're the one filing.
Templates that ask questions
My decision template has four sections and two of them do the work: alternatives considered and consequences. You can't fill it in without saying what you rejected and what the choice closes off.
For about a month it felt like paperwork. Then a project turned, and I went back through two years of decisions to work out which ones still held. The entries with rejected alternatives were the only ones I could actually re-examine. The rest recorded what I'd done, which tells you nothing once the question has become why.
There's a second benefit I didn't plan for. A template like that is also why an agent can produce a usable note from a one-line prompt. It isn't staring at a blank page trying to be insightful; it's answering six specific questions in a fixed order.
The front page should argue, not list
The entry note for each active project used to be a table of contents. After the incident above, it became something closer to a briefing:
# Project
**Direction: settled.** We are building X for Y.
Canonical definition: [[What X Is]] — if the product changes, change that note first.
🛑 The search is closed. The earlier directions are in the archive.
Do not re-apply the old "pick the narrowest slice" rule to the current structure.
## Decided
...
## Still open — these are evidence questions, not direction questions
1. ...
## What outlives any direction
- A forcing event beats a good product. Everything here without a deadline died of slow sales.
Three things do the lifting. It says whether the direction is settled or still being tested. It keeps decided and open apart. And it carries stop signs that name the specific mistake a reader is likely to make.
This is the document that turns the agent from a liability into something useful, because it's a ranking over the whole vault written in ordinary prose. It also turned out to be the note I reread most often myself. I only discovered I needed one when a machine read my notes without it.
Nothing gets deleted, but the dead things wear labels
When a project turns, the old notes move into a dated snapshot rather than the trash, and I write that snapshot's README right then, while I still remember why: what each part was, what's still worth reading, what replaced it.
The section that earns its keep is the list of landmines.
⚠️ The "67% of firms" statistic in these notes is fabricated. Do not reuse it.
⚠️ Several notes cite a deadline that has since passed. Verify against the
primary source before this appears anywhere external.
I started keeping that list because a number I had already disproven nearly made it into an external document. The agent found it, cited it cleanly, and had no way of knowing. The note didn't say so, and as far as anything reading the vault was concerned, it was still true.
An archive with no warning labels isn't a record of what you learned. It's a supply of your old mistakes, indexed and ready.
Some notes shouldn't be written at all
If a fact already lives in a log file or a commit history, copying it into a note just creates a second version that can drift from the first. So part of my vault is generated. A script reads the real sources, writes the notes, overwrites them on every run, and never touches anything handwritten. The boundary is enforced in code, so it doesn't depend on me remembering it.
The cost is real. A generated note is only as current as its last run, and a stale generated note is worse than an obviously old handwritten one, because it looks maintained. I found a dashboard of mine that had been quietly months out of date. Regenerating is part of the weekly routine now, which is the right place for it. That's an operations problem, not a writing one.
The AI part is boring
The integration is cd vault && claude. There's a one-page instructions file at the root covering link syntax, where things go, and what not to touch. Conventions, not personality.
It isn't RAG, and I don't miss it. Chunking notes and retrieving by similarity buys infrastructure I don't need at this size, and when it fails it fails quietly: you get plausible fragments and no way to see what it skipped. My setup reads the briefing and opens the three pages that matter, the way a colleague would. When it opens the wrong page I can see that in the transcript, and the fix is a better link or a clearer stop sign. Five minutes of editing, not a re-index.
Similarity finds what resembles your question. A briefing tells you what to trust. Only one of those is something you can debug.
What it costs to keep running
About half an hour a week: empty the inbox, update the briefings, rerun the generator. Skip it for a month and the vault becomes a museum. Everything above depends on that half hour, and I'd rather say so plainly than pretend the thing maintains itself.
The agent still ignores the instructions file now and then and has to be pointed back at it. Writing the archive README at the moment of archiving is the rule I break most often, and every single time, the reasoning was gone by the time I wanted it back.
And this is a few hundred notes, not a few million. Well-governed and small beats ungoverned and large for the work I do, but the ceiling is real and I've been close enough to see it.
If you want to try it
Make the folder. Write one four-line rules note. Write one honest briefing for whatever you're working on right now, including the things you've ruled out and why you ruled them out. Point Claude Code at it and get on with your day.
Then wait for the first time it argues for something dead, because it will. When it happens, don't correct it in the chat. Go and fix the document that let it happen.
That loop is the entire system. The folder was never the point.
Keywords: Obsidian, Claude Code, agents, knowledge management, plain text.