The problem
Notes are dots. Obsidian draws the lines between them, and that graph is what wows people the first time they see it. The graph did nothing for me on a Tuesday. I had two small businesses, client work and a plugin project all living in one folder, and every new session, mine or an AI's, started by re-reading the same files to work out where things stood. Decisions got made in chat and lost on close. The same mistake got made three times by three different sessions. And every time an agent went looking for context it read everything, which is how I ended up at 355,000 tokens of context on an average turn.
What I built
A vault with a front door. The folders follow ACE × PARA: Atlas holds the maps and the rules, Calendar holds anything tied to a date, then Projects, Areas, Resources, Archive, and X, which is the system itself: workspaces, scripts, the agent definitions. Three files in the Atlas do most of the work. MAP is the front door and the contract: where everything lives, and where it went when it moved. WORKFLOW is the daily driver. AI-GUIDE is the file every agent reads before it touches anything.
Then the discipline, which matters more than the folders.
- DECISIONS.md. About 1,000 dated entries since October 2024. A decision gets written down in the turn it is made, one to three lines, not at the end of the session.
- MISTAKES.md. 147 dated entries. Each one has what happened, the root cause, the consequence, and the prevention. When the same mistake recurs three times it is promoted to a hard rule in the file every agent reads. Six laws so far, and each one is there because something broke three times.
- Session handoffs. 20 dated files. What shipped, what was decided, the exact open items, and the one line to resume from. Any session, human or agent, picks up cold.
- TOOL-LIBRARY. One catalog of 35 built assets: 17 tools, 3 Obsidian plugins, 11 agents, 4 skills. If it is not in the catalog it does not exist.
How it works
The idea is to group the dots into maps so the AI needs one to three hops instead of a full read. An agent lands on MAP, reads the subheadings, follows one link into the right hub, and is working. Indexes are cheaper than search.
Routine work gets a deterministic tool instead of tokens. If I keep asking an AI to run the
same search, that is a filter, so I build the filter. That became recall: local
memory and a token meter with zero API calls, built on SQLite and a local embedding model. It
puts a short state card in front of every session, warns when a tool result comes back
oversized, and blocks the session at a context ceiling so a runaway build cannot eat the day.
Shell output got the same treatment. I audited 5,416 commands and found the biggest leak was fetching web pages: the output came through verbatim. Changing the route, not the filter, took page fetches from 0% to 98% of output saved. That is the pattern across the whole system. Measure, then build the boring tool that closes the leak.
The plugins I build sit on top of this. Oak is the planner, Altitude is the ink canvas, both plain Markdown, private and offline. Oak's design law is a written file enforced by a linter in the build, which I wrote up in Designing a planner that feels like paper.
Results
- 35 assets in one catalog, 31 of them tracked in git.
- About 1,000 logged decisions and 147 logged mistakes, with six promoted to rules.
- Context per turn: the baseline across 114 sessions was 355k. Orchestrated sessions now run 80 to 95k. Long build sessions still run 140 to 170k. The target is under 60k and I have not hit it.
- Page fetches: 0% to 98% of output saved after the routing change.
I am not claiming time saved or money saved. I have not measured either. What I can say is that a new session no longer starts from zero, and a break that has happened three times does not get to happen a fourth.
Where the habit comes from
Eight years teaching special education, and 200+ enterprise staff trained before that. In both jobs the instruction had to work for someone who was not me and could not ask me. Every file in this vault gets the same test.
What I'd do next
Hit the 60k target. The long build sessions are the gap, and the fix is pushing more of them to cheap subagents so only the summary comes back. Then make the mistake log do more of its own promotion. Right now I count the repeats by hand.