Note-taking

• Building a Linter for Your Obsidian Vault

  In software we don’t trust ourselves to keep a codebase clean by hand. We run linters. They catch the dead code, the unused import, the function nobody calls anymore, the link that points at a file that got deleted three commits ago. We’ve decided that rot is inevitable and that a machine should hunt for it on every save.

  Our note vaults get no such treatment. They rot exactly the same way, orphan notes with no links in or out, dead [[wikilinks]] pointing at notes you renamed, half-distilled drafts that have sat untouched for months. The difference is nobody’s running a linter on them. So let’s write one.

  Folders are a trap. Links are the currency.

  The instinct, when a vault gets messy, is to reorganize the folders. Resist it. Folders force a note to live in exactly one place, which is a lie, because most ideas belong to several contexts at once. A note on caching strategy is relevant to a performance project, a systems-design reference, and a half-formed blog post, all at the same time. A folder makes you pick one and bury it.

  The health of a vault lives in its links, not its hierarchy. A well-linked note is reachable from a dozen directions. An orphan, a note with zero links in or out, is functionally invisible. You will never stumble back into it. It’s dead the moment you save it. So the single most useful thing a vault linter can report is: which notes are orphans, and which links are broken.

  Step one: parse the markdown, not just grep it

  You could grep for [[ and call it a day, but you’ll get fooled by links inside code blocks, escaped brackets, and frontmatter. Parse it properly.

  Two passes per file. First, pull the YAML frontmatter off the top with a library like python-frontmatter, which hands you the metadata as a dict and the body as a string. That’s where your status, tags, and aliases live. Second, run the body through a real markdown parser such as markdown-it-py and walk the token stream, collecting link tokens while ignoring anything inside a fenced code block.

  Now you have a clean model of the vault: a dict of every note keyed by filename, each with its frontmatter and its outbound links. From there the checks are short:

  • Broken links. For every outbound link, confirm the target file exists. If it doesn’t, the note was renamed or deleted. Flag it.
  • Orphans. Build the reverse index of inbound links. Any note with no inbound and no outbound links is an orphan. Flag it.
  • Stale drafts. Any note still at status: raw whose modified time is older than thirty days. Flag it.

  That’s a useful linter already, and it’s maybe sixty lines of Python. It runs in a second over a few thousand notes.

  Step two: the part grep can’t do

  Broken-link detection is mechanical. The interesting failure is the link that should exist and doesn’t. Two notes that are clearly about the same idea, written six months apart, that have no idea the other one exists. No string match will find those, because they don’t share words. They share meaning.

  This is where a local embedding model earns its place. Run every note body through something like sentence-transformers to get a vector per note, then compute pairwise cosine similarity. Any pair that scores above a threshold but has no link between them is a suggested cross-link. The linter doesn’t create the link, it just surfaces the candidate: “these two notes are conceptually close and unconnected, did you mean to link them?”

  Keep it local. The whole point of a vault is that it’s yours, and you don’t want to ship every private note to an API to find out two of them rhyme. A small embedding model on your own machine handles a personal vault without breaking a sweat, and the vectors never leave the laptop. If you’ve read how vector similarity drives retrieval, this is the same trick pointed at your own notes instead of a document corpus.

  Run it like a linter, not a project

  The mistake would be to build this as a grand one-time cleanup, run it once, fix everything, and never touch it again. The vault will just rot back. Treat it like the linter it is. Wire it into a weekly job, or a git pre-commit hook if your vault is a repo, and have it print a short report: three broken links, eight orphans, five suggested cross-links. You spend ten minutes acting on the list and the vault stays healthy on its own.

  A note vault is a codebase. It accumulates the same entropy, drifts the same way, and benefits from the same discipline we already apply to every other pile of text files we own. We just never thought to point the tools at it. Point them.

  I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].

  Sources

  • Andy Matuschak, “Evergreen notes should be densely linked” — the argument that a note’s value comes from its links, and that organizing by hierarchy fights against that.
  • Eric Holscher, “python-frontmatter” (GitHub) — library for splitting YAML frontmatter from a markdown body, used for the metadata-parsing pass.
  • “markdown-it-py” (GitHub) — a CommonMark parser that exposes a token stream, used here to extract links while skipping code blocks.
  • “Sentence Transformers” — framework for generating local sentence and document embeddings, used to flag conceptually similar but unlinked notes.

  Jul 5, 2026 Python Embeddings Second brain Note-taking Knowledge management

  Enjoyed this?

• The Capture Trap: Why Your Note Vault Is a Graveyard

  Open your notes app and scroll to the bottom of the inbox. How many of those clippings have you reread? How many turned into anything? The answer is probably “almost none.” You have hundreds of saved articles, and half-finished thoughts, and the pile only ever grows. That’s not a second brain. That’s a graveyard.

  I walked through Forte’s CODE workflow recently, four stages from Capture to Express. This post is about the stage everyone skips, and why skipping it is so easy that most vaults quietly die of it.

  Capture feels like work. It isn’t.

  Clipping an article gives you a little hit. You found something useful, you saved it, you can close the tab and feel like you made progress. But you didn’t learn anything. You filed it. The act of saving stands in for the act of understanding, and your brain happily accepts the substitution.

  The Zettelkasten people have a name for this: the collector’s fallacy. Gathering material feels like knowledge work, so you keep gathering, and the gathering itself becomes the hobby. The collection grows. Your understanding doesn’t. You end up with a beautifully organized library you’ve never read.

  Capture is frictionless now, which makes the trap worse. Web clippers, voice memos, a hotkey that drops anything into your inbox. The easier it gets to collect, the faster the graveyard fills.

  Express is where the value is, and it’s the part that hurts

  Express is the stage where you do something with a note: write the post, make the decision, ship the code, send the reply. It’s the only stage that produces anything. It’s also the one that takes effort, because it forces you to actually think about the material instead of just owning it.

  So it gets deferred. Forever. And a vault where nothing ever reaches Express is just an expensive way to forget things slowly.

  The fix isn’t more capture discipline or a prettier folder structure. It’s making Express the default destination of a note instead of an optional last step you’ll get to someday.

  Give every note a lifecycle

  Stop treating notes as either “saved” or “not saved.” Give them a status, a small piece of frontmatter that says where the note is in its life:

  • raw is something you captured and haven’t processed.
  • distilled is a note you’ve summarized in your own words.
  • expressed is one that fed into actual output.

  Now your vault has a pulse. You can query it. “Show me everything still sitting at raw from the last two weeks” turns the invisible backlog into a list you can act on. The graveyard problem was always that dead notes looked exactly like live ones. A status field makes the dead ones visible.

  Point an agent at the backlog

  This is where it gets fun, and where a CLI agent that can read your vault earns its keep.

  Once notes carry a status, you can hand the boring half of Express to an agent. Wire up a weekly job that does three things:

  1. Query every note still sitting at raw.
  2. For each one, draft a two-sentence summary and a single question: is this worth keeping, and what would you make from it?
  3. Drop the results in front of you as a short review list.

  You’re no longer staring at a wall of three hundred clippings. You’re answering ten questions about ten notes, and the agent did the reading. The notes you keep get promoted to distilled. The ones you don’t get archived without guilt. Either way they leave the inbox, which is the whole point.

  The model as a sparring partner

  The last piece is using the model to get from a distilled note to actual output. Hand it a cluster of related notes and an outline, and ask it to argue with you. Where’s the thesis weak? What’s the counterargument? What example would make this land?

  The model doesn’t write the thing for you, and you don’t want it to, that’s how you end up with generic mush in your own voice. It pushes the note one stage further down the pipeline, from a pile of research into a draft with a spine. You take it from there.

  That’s the anti-graveyard loop. Capture stays frictionless, because friction there is bad. But every captured note now enters a pipeline that pushes it toward output instead of letting it rot in an inbox. The status field makes the backlog visible, the agent works it down for you, and the model helps you ship.

  A vault isn’t valuable because of what’s in it. It’s valuable because of what comes out. Build the part that gets things out, and the graveyard turns back into a brain.

  I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].

  Sources

  • Tiago Forte, Building a Second Brain (2022) — the CODE workflow and the “Express” stage as the antidote to collect-and-forget note-taking.
  • Christian Tietze, “The Collector’s Fallacy” (Zettelkasten.de, 2015) — why gathering material feels like learning when it isn’t, and how the collection becomes the hobby.

  Jul 4, 2026 AI Agents Second brain Note-taking Knowledge management

  Enjoyed this?

• CODE: The Four Stages of a Note

  Yesterday I walked through the history of the second brain, the 500-year arc from glued paper slips to LLM-readable vaults. Today I want to zoom in on one piece of it: CODE, Tiago Forte’s four-stage life cycle of a note. If PARA is where things go, CODE is what you do with them. It’s the process half of his methodology from Building a Second Brain (2022), and it breaks down into four moves.

  • C: Capture. Get ideas out of your head and into the system. Don’t filter, collect.
  • O: Organize. Sort captured notes by actionability, not topic.
  • D: Distill. Refine notes over time so each one gets denser and more usable.
  • E: Express. Actually use the knowledge. Write, build, decide, share.

  Let me give you an example of each.

  Capture

  You record ideas, quotes, links, and observations as they happen, straight into a temporary inbox. The one rule here is that you don’t organize while you capture. Sorting mid-thought kills the flow. Just get it out of your biological brain and into a note, and don’t worry about where it lives yet.

  How you do it doesn’t matter much. Quick-capture apps, web clippers, voice memos, a daily notes file, whatever has the least friction. Capture first, organize later. That’s the whole rule.

  Organize

  This is where you move inbox items into the right place, and Forte’s twist is that you sort by actionability instead of subject. A note about React hooks doesn’t go in a “programming” folder. It goes into the project it serves, or into Resources if it’s reference material, or into Archives if the project is already done.

  Organize is also where everyone’s opinions start to diverge. PARA imposes folders. Zettelkasten throws folders out entirely and organizes by links and unique IDs. There’s no single right answer, and most people end up mixing both.

  Distill

  This is Forte’s signature move, also called progressive summarization. You read a note and highlight the key passages. On a later pass, you bold the best of those highlights. On an even later pass, you write a short summary of the bolded parts in your own words. Each pass makes the note denser and faster to reuse. You’re building a highlight reel of your own past thinking.

  The catch is that aggressive summarizing strips context, and there’s real debate about how far to take it. In the age of AI this matters more, not less. If you compress a note down to three bullet points, you’ve thrown away the surrounding detail that a model (or future you) might need. Distill, but don’t shred.

  Express

  Express is the payoff, and it’s the stage most note systems quietly skip. You turn distilled notes into output: a blog post, a decision, some new code, a presentation, a reply to an email. This is the part that makes the thing a brain and not a filing cabinet. A filing cabinet stores. A brain produces.

  By making Express an explicit, named stage, Forte is fixing the most common failure mode of note-taking, which is collect-and-forget. You hoard articles you never reread and clip quotes you never use. Naming the output step forces the question: what is any of this actually for?

  And, by the way, congratulations. You now have yet another thing to maintain.

  CODE vs. Zettelkasten

  CODE isn’t the only game in town, and it’s worth seeing it next to the other big approach.

  	CODE (Forte)	Zettelkasten
  Organizing principle	Actionability (PARA folders)	Links + unique IDs
  Note shape	Action-oriented, distilled	Atomic, linked
  Structure	Imposed folders	Emergent graph
  Goal	Produce output	Think with a partner

  In practice people combine the two. PARA folders for where things go, wikilinks for how they connect. You don’t have to pick a team.

  Why it works

  Strip away the acronym and three things are doing the actual work here:

  • External cognition. Offloading capture frees your biological brain to think instead of remember.
  • Spaced encounter. Each distillation pass re-exposes you to old ideas in a new, denser form.
  • Output bias. Making Express a real stage counters the collect-and-forget trap.

  That’s CODE. Four letters, one honest goal: not to hoard your thinking, but to ship it.

  I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].

  Sources

  • Tiago Forte, Building a Second Brain (2022). The CODE workflow (Capture, Organize, Distill, Express) and its relationship to PARA.
  • The PARA Method: Building a Second Brain. PARA’s four categories (Projects, Areas, Resources, Archives) and the actionability-over-topic sorting principle.
  • Tiago Forte, “Progressive Summarization” (Forte Labs, 2017). The layered highlight/bold/summarize technique that the post calls “Distill.”
  • Zettelkasten (Wikipedia). The link-and-unique-ID organizing principle, atomic notes, and emergent graph structure contrasted with PARA in the comparison table.
  • Niklas Luhmann (Wikipedia). Luhmann’s description of his Zettelkasten as a “thinking partner” (the “Think with a partner” row of the table).

  Jun 28, 2026 Second brain Note-taking Zettelkasten Knowledge management Para

  Enjoyed this?

• A Brief History of the Second Brain

  The phrase “second brain” is glued to Tiago Forte and the productivity wave of the 2010s. But the ambition behind it is nearly five centuries old, and the method is a lot older than the name. So let’s walk the timeline, because the story is more interesting than the buzzword.

  It Starts With Slips of Paper

  Go back to antiquity and you’ll find people keeping personal notebooks of quotes, recipes, and observations. The commonplace book. Nothing fancy, just a place to park the ideas worth keeping.

  Things get more systematic in the mid-1500s. A naturalist named Conrad Gessner suggested cutting notes into individual slips and gluing them onto sheets so you could rearrange and reassemble ideas from pieces. That modular instinct, breaking knowledge into movable units, is the seed of what the Germans would later call the Zettelkasten, the “slip box.”

  About a hundred years later, Thomas Harrison built the Arca Studiorum, the “ark of studies.” It was a literal cabinet where paper slips hung on labeled metal hooks, sorted by subject. The design was published posthumously by Vincent Placcius in 1689, which makes it one of the first documented personal knowledge devices. Leibniz reportedly relied on it for one of his projects. A hundred years after that, Carl Linnaeus was working with standard-sized paper slips, over a thousand of which survived. Basically the index card before the index card existed.

  For roughly 300 years this stayed a scholarly habit. Researchers, clergy, naturalists, the PhD crowd. Not something the general public thought about.

  The Idea Goes Electric (In Theory)

  In 1945, Vannevar Bush wrote an essay in The Atlantic called “As We May Think,” and described the Memex: a desk-sized microfilm machine that would store all of your books, records, and correspondence, with mechanical “associative trails” linking related items together. It never got built. But read that description again and tell me it doesn’t sound like every linked-notes tool we use today.

  Then comes the patron saint of the second brain: Niklas Luhmann. From the 1950s onward he built a Zettelkasten of around 90,000 index cards over four decades. Each card got a unique ID, each linked to others by ID, a physical knowledge graph made of paper. Out of it came dozens of books (some counts say 70) and hundreds of articles. He described the system as a thinking partner he could have a conversation with. His archive was digitized and put online in 2019, so you can go poke around in it.

  Luhmann wasn’t a one-off. The 20th century is full of scholars running the same playbook:

  • Walter Benjamin (Arcades Project, 1927-1940)
  • Roland Barthes (12,250 cards)
  • Hans Blumenberg (30,000+ cards)
  • Arno Schmidt (100,000+ cards for Zettels Traum)
  • Mario Bunge (70 books, 540 articles out of his card files)

  The Computer Was Supposed to Be the Second Brain

  Through the 1980s to the 2000s, we still didn’t have today’s vocabulary. We had the PIM, the personal information manager, and the PKM, personal knowledge management. The personal computer itself was pitched as the thing that would know everything about you.

  Apple, Xerox, and Microsoft all took a swing:

  • NoteCards (Xerox PARC, 1985) was modeled directly on 3×5 index cards with typed links, an early hypertext take on the slip box.
  • HyperCard (Apple, 1987) handed people a hypertext stack system, and its card metaphor was a straight callback to the Zettelkasten. It’s also what inspired Ward Cunningham to build the first wiki in 1994.
  • Outliners like MORE, Ecco Pro, and Lotus Agenda chased hierarchical thought.
  • OneNote (Microsoft, 2003) was the first mass-market freeform digital notebook.
  • Evernote (2008) nailed the capture half with “remember everything,” but stayed folder-and-tag based, never a graph.

  Zettelkasten Goes Public

  In 2017, a writing coach named Sönke Ahrens published How to Take Smart Notes. He translated Luhmann’s dense German academic method into plain English for students and knowledge workers, and put the slip-box workflow, capture, permanent notes, link, develop, in front of a non-academic audience for the first time.

  Almost in parallel, Tiago Forte coined the modern “second brain” and aimed it squarely at the everyday knowledge worker. Through Forte Labs he taught PARA (Projects, Areas, Resources, Archives), an action-oriented filing system that rejects the Dewey Decimal instinct, and the CODE workflow (Capture, Organize, Distill, Express) for the life cycle of a note. The 2022 book Building a Second Brain turned it into a movement.

  From Folders to Graphs

  Then the tools caught up to Luhmann. Roam Research (2020) made bidirectional links the whole point. Its early adopters were overwhelmingly academics, PhD students, and writers, and they showed everyone what diligent linking actually buys you.

  Obsidian launched around the same time and is what most people picture now. Local-first, plain markdown, bidirectional links, a huge plugin ecosystem, and a motto that matters: your data is yours. That’s the real pitch. With Roam, Evernote, or Notion you can get your data in, but getting it back out in a format you own is a different story. You’re renting access to your own thinking. Obsidian doesn’t do that. It’s just markdown files on your disk. For my money that makes it the default, and everything with lock-in is a harder sell.

  Either way, the shift is the headline: we moved from folders and notebooks to graphs. Links and backlinks. The knowledge graph stopped being a Luhmann eccentricity and became the norm.

  And Now You Hook It Up to an LLM

  Which brings us to right now. Somewhere around 2023, people started asking the obvious question: what if you point a language model at your second brain? The best way I’ve found is through a CLI-based agentic harness like Claude Code, pointed at your notes. I’ve been running Claude Code against my own vault for over a year, and the same approach works with other agentic coders. OpenCode is good, and Google’s Antigravity (Gemini) has been pretty good too.

  There are different strategies for structuring a vault so an agent can read and extend it, and I’ll dig into those in a future post. One you may have heard of is Karpathy’s recent “LLM wiki” idea, which isn’t just about plugging an LLM in, it’s an opinion about how to structure the vault so the model works well with it.

  That’s the real evolution. For 500 years the second brain was storage you read from. Now it’s becoming something that reads and writes back.

  Era	Metaphor	Key figure/tool	What it solved
  1540s-1890s	Card file / commonplace book	Gessner, Harrison, Linnaeus	Modular scholarly notes
  1945	Memex (associative trails)	Vannevar Bush	The idea of external memory
  1950s-1990s	Zettelkasten (linked slips)	Niklas Luhmann	Memory as a thinking partner
  1980s-2000s	PIM (folders, notebooks)	HyperCard, OneNote, Evernote	Digital storage
  2010s	Methodology + capture	Tiago Forte (BASB, PARA/CODE)	A repeatable workflow
  2020-22	Knowledge graph	Roam, Obsidian	Connection over hierarchy
  2023-	Agent-readable wiki	LLMs, Claude Code, Karpathy	Active synthesis

  Gessner was gluing paper slips onto sheets so he could rearrange his ideas. We’re doing the same thing. We just gave the slip box a way to talk back.

  I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].

  Sources

  • Vannevar Bush, “As We May Think,” The Atlantic, July 1945 — the Memex proposal.
  • Memex — Wikipedia — background on the Memex device and its hypertext legacy.
  • Zettelkasten — Wikipedia — Gessner’s glued slips, Harrison’s Arca Studiorum (published by Placcius, 1689), Linnaeus’s paper slips, and the 20th-century card-file users (Benjamin, Barthes, Blumenberg, Schmidt, Bunge).
  • Niklas Luhmann — Wikipedia — the ~90,000-card Zettelkasten, digitized and put online by the University of Bielefeld in 2019.
  • NoteCards — Wikipedia — the Xerox PARC hypertext system (1985) modeled on 3×5 index cards.
  • HyperCard — Wikipedia — Apple’s 1987 hypertext stack system; Ward Cunningham traces the wiki concept back to a HyperCard stack.

  Jun 27, 2026 AI Obsidian Second brain Note-taking Zettelkasten Knowledge management

  Enjoyed this?