1,222 notes, 24 categories, zero vendor lock-in. My knowledge management system fits on a thumb drive.
The starting point
The oldest notes in this vault are from June 2013. Talk notes, loose ideas, book quotes, technical decisions, reflections on teams and processes. They started out in Google Keep, in scattered files, in tools I no longer remember the name of. Over time I migrated them into markdown files by hand. Slowly, in bursts, never quite finishing.
The second brain always had valuable stuff in it. Interesting ideas, connections between concepts, reference material that had taken me hours to compile. I found notes when I needed them, connected ideas across sessions. But I had this persistent feeling that there was more in there than I was getting out. Hundreds of notes that didn't talk to each other. Knowledge that accumulated but didn't compound.
And then there was the Google Keep backlog. Over the years I'd piled up around 1,500 notes and links in Keep. Quick captures, things I meant to process "later." The problem was that Google Keep has no API, so getting stuff out was painful enough that I just... didn't. The backlog grew. Every time I opened Keep I felt the weight of it.
Last Christmas I decided to just rip the band-aid off. Exported everything via Google Takeout, deleted it all from Keep, and sat down with the raw files. Using AI I built a throwaway classification pipeline: a combination of heuristics and a human-in-the-loop process where the system proposed a category and I made the final call. In a couple of days, 1,500 notes were classified and integrated into the vault. Bye bye, Google Keep.
That was the moment it clicked. The friction of processing notes had been the bottleneck for years, not the lack of a system. Once I could generate tooling on demand to solve a specific problem, the backlog that had haunted me for ages just... dissolved.
Separately, I'd been curating recommended technical talks in eferro-picks for years. 855 talks, 465 speakers, gathered over 6 years. Another project with valuable information sitting in its own repo, its own structure, disconnected from the vault.
Both projects are now one. What I have is an Obsidian vault of markdown notes on Dropbox, versioned with Git, maintained by an AI agent that understands the structure. The talks from eferro-picks live inside the vault now. 402 of the 855 have full notes so far: all recent talks get them automatically, and I'm gradually backfilling the older ones that only had a title and a link. The vault is the source of truth for the talks, not the other way around. I even have automated pipelines to process new talks I watch and want to recommend (but that's a story for another post).
It's not an app. It's a folder of text files with a system on top. And for the first time in over ten years of note-taking, I feel like I'm getting out of it the value I always sensed was there.
Why plain text files
The most important decision in the system is the most boring one: everything is markdown. .md files I can open with any text editor, on any operating system, with no special tooling.
It sounds like a non-decision. It isn't. There's no database. No proprietary format. No server. If Obsidian disappears tomorrow, or Dropbox, or Claude, the notes are still readable. I can search with grep, edit with emacs, sync with rsync. The format will outlive whatever tool I'm using to read it this year.
Dropbox syncs across devices with zero configuration. Git versions everything, so every change is recorded, I can see diffs, I can roll back. Between the two I get sync and version control almost by accident. Dropbox keeps files up to date across machines, Git keeps the history.
There's a side effect I didn't appreciate until I was living it: I can edit a note on my laptop, close the lid, pick up my phone and keep writing where I left off. Or switch to another machine at home. No export, no sync button, no waiting. Dropbox just does it. Obsidian on mobile opens the same files, same links, same structure. It sounds trivial, but it removes the last excuse for not capturing an idea when it shows up.
Not sophisticated tools. Tools that work, and have been working for decades.
Obsidian is the reading interface. Wiki-links ([[Note]]) create a navigable knowledge graph, backlinks connect ideas both ways, the graph view shows you clusters you didn't know were there. But Obsidian is a view on files, not a platform. If something better comes along, I switch. The files don't care.
 |
The vault's knowledge graph in Obsidian.
The clusters form naturally from wiki-links and shared tags. |
And it turns out that "just text files" goes further than notes. Diagrams in the vault are Mermaid, a text format that renders into flowcharts and architecture visuals. Obsidian stores Excalidraw sketches as JSON inside regular .md files. The presentations for the master's program I teach live in Marp: markdown with a few annotations that compiles into slide decks, PDFs and PowerPoints. I can git diff a diagram the same way I diff a note, and an AI agent can generate a Mermaid flowchart as easily as it writes prose. To the agent it's all text.
The structure: PARA, loosely
Notes are organized following Tiago Forte's PARA methodology, without being religious about it.
Projects for things with a deadline or deliverable. Right now: a master's program I'm teaching, this blog, a house renovation. Areas for ongoing stuff: writing, professional network. Resources is where most of the vault lives, reference material organized by topic across about 24 categories. Archive for completed projects that should stop getting in the way.
If you've read my blog before, the topics won't surprise you. The most tagged subjects are engineering culture, AI, agile, continuous delivery, software design, architecture, product and XP. Throw in DevOps, lean, teams and testing and you have a pretty accurate map of what I spend my time thinking about. The vault just makes it explicit.
Then there's The Forest (the vault borrows the digital garden metaphor), a directory with Maps of Content: thematic indexes connecting scattered notes. And Sources, where the 402 talk notes live.
Beyond folders, notes carry two kinds of tags. Topic tags (on/software-design, on/lean, on/ai) say what a note is about. Maturity tags say how developed it is: state/seedling for a raw capture, state/budding for something I've worked on but isn't finished, state/evergreen for a note I consider solid. Most of the vault is still seedlings and budding notes. The evergreen ones are the minority, which is honest: note count and idea quality are different things.
The structure isn't perfect. What matters is that it's predictable. If I'm looking for a quote, I know it's in 3_Resources/Quotes/. Finished projects go to 4_Archive/. This predictability is what lets an AI agent work on the vault without asking me where things go.
The leap: an AI agent that gets the vault
Here's where it gets interesting. Claude Code is not a chatbot I ask things about my notes. It's an agent that operates directly on the files. Creates notes, edits them, runs scripts, checks the vault's health. All while following rules I've written over time.
The rules live in .claude/rules/, configuration files the agent reads at the start of every session. Where to put each type of note. What YAML frontmatter to include. Naming conventions. How to verify links aren't broken. Not suggestions. Constraints.
Here's what that looks like in practice. I say: "create notes for these 7 mental models." The agent creates 7 files in 3_Resources/system_thinking/, each with the right structure (core idea, software applications, limitations, connections), tags them on/mental-model, updates the central Map of Content in The Forest/Mental Models.md placing each in the right domain category, and before writing any wiki-link, checks that the target note actually exists. I don't touch a file. But the rules that made this work? I wrote those myself, one session at a time, encoding what I'd learned about how my vault should behave.
Three layers, one system
What makes this a system and not just "a chatbot writing files" is three layers working together. I keep coming back to this because it's the part people misunderstand.
The first layer is the agent with domain context. Claude Code doesn't see loose files. It knows a new talk note needs topics from the 80+ taxonomy and a link to the speaker's page. A quote goes in Quotes/ with the author's name as tag. A project has a deadline, an area doesn't. Rules give it semantics, not just file paths.
The second layer is 15 Python scripts behind 30 Makefile targets.
One group keeps the vault healthy: a script that parses every wiki-link and checks it against existing files, another that validates YAML frontmatter, another that finds stray images and moves them next to the notes that reference them.
A second group powers the talk pipeline: sync from eferro-picks, pull metadata from YouTube via yt-dlp, run content through NotebookLM, generate blog post HTML.
A third handles the master's presentations: Mermaid to PNG, Marp to PDF and slide decks.
The agent runs all of this through make targets. When it checks for broken links, it's not guessing. It's running a real script with real output.
The third layer is 6 skills. These aren't prompts. They're protocols: which tools to use, in what order, what to verify, what to ask me before proceeding. When I say "process this talk," the agent doesn't figure it out from scratch. It follows a written workflow that I've refined over multiple iterations. Same when I say "check vault health" or "organize the inbox." Each skill encodes a complete task, not a vague instruction.
Take away any one layer and the thing falls apart. Without scripts the agent would improvise something different every time. Without the agent the scripts are just CLI tools I'd have to remember to run. Without rules the skills wouldn't know what decisions to make.
How it actually evolved
The current state of the system is less interesting than how it got here. Because none of this was planned.
The talk pipeline started as a single script to sync a JSON with the vault. I was doing it by hand and it was tedious, so I automated the sync. Then I wanted the agent to be able to run it, so I wrote a skill. Then I wanted automatic topic extraction, so I plugged in NotebookLM. Then I wanted to publish talks as blog posts, so I wrote another script. Over a weekend, iterating with the agent. From copy-paste to a pipeline processing 402 talks and spitting out HTML.
The pattern repeats. I use the vault, hit a friction. Write a script for the mechanical part. Wrap it in a skill so the agent can orchestrate it with judgment. Add rules so the agent remembers the lesson next time. Now the agent is better at that task, which frees me to notice new frictions.
The master's program presentation rules followed the same arc. After session 3, I jotted down what worked and what hadn't. Slides had too much text. Extra material should be in separate files. Speaker notes needed a timeline. I turned those lessons into rules. From session 4 on, Claude Code applied them without me having to say anything. The rules became the shared memory between me and the agent.
Zero broken links
Of all the rules in the vault, one appears in three separate files. I consider it the most important: zero broken links.
In Obsidian, a wiki-link [[Something]] is a promise that "Something" exists as a note. If it doesn't, the link is noise. It suggests content that isn't there, pollutes the knowledge graph, blurs the line between what's real and what's aspirational. And broken links breed. One becomes five, five become thirty, and suddenly your graph is full of ghosts.
The rule is simple: if you're not sure a note exists, use plain text. The agent checks before writing any [[Concept]]. If the file doesn't exist, it writes "Concept" without brackets. After every edit, make find-broken-links. If it created broken links, it fixes them before moving on.
Prevention, not correction. Same principle as tests in code. Cheaper to not introduce the bug.
What this isn't
I don't want to oversell this.
It's not effortless. Rules need writing, scripts need maintaining, structural decisions need making. There are 15 Python scripts and 30 Makefile targets for a personal vault. Is that over-engineering? Probably, partly. Some of it is hobby. Some is me poking at what's possible when you point an AI agent at a folder of text files.
It's not a system where AI does the thinking. Claude Code doesn't decide what's worth keeping, how to categorize a concept, or which connections matter. I'm the one who decided mental models live in system_thinking/ regardless of their domain. I'm the one who decided that domain categorization happens in the MOC, not in the filesystem. The agent executes those choices at scale. But the design is mine.
And it's not for everyone. You need to be comfortable with a terminal, with Git, with text files. If you want a polished app with automatic sync and zero setup, use Notion. Seriously. It's fine.
The question I'm left with
Every time I codify a rule or a skill, the agent gets more capable. But also more opinionated. The rules reflect my decisions today: my taxonomy, my structure, my conventions. What happens when my thinking changes? Do the rules become inertia, or are they an explicit record of decisions I can consciously revisit?
Git has the full history. I can see when I added each rule and why. I can change them. But there's a gap between being able to change them and actually doing it when the system works well as-is.
After years trying tools, what works for me turns out to be the most boring stack imaginable: text files, a synced folder, an agent that knows the garden's rules. 1,222 notes and counting.
Whether the system helps me think better or just organize faster what I was already thinking, I genuinely don't know. Probably both. Probably the distinction doesn't hold up under scrutiny.
Related reading
The methodology and ideas behind this:
- The PARA Method — Tiago Forte's original post on the organizational system this vault uses
- Evergreen notes — Andy Matuschak's thinking on notes that evolve and compound over time, which inspired the seedling/budding/evergreen maturity model
- Building a Second Brain — Tiago Forte's broader framework for personal knowledge management
The tools:
- Obsidian — The editor I use as a view on the vault's markdown files
- Claude Code — The AI agent that operates on the vault
- Marp — Markdown to slide decks
- Mermaid — Diagrams as text
