Good note-taking methods work. Almost nobody keeps doing them by hand.

There's a well-documented way to organize what you learn so it compounds instead of piling up: write one idea per note, link it densely to related notes, and let the connections accumulate over time instead of forcing everything into one hierarchy. It's called Zettelkasten. Paired with PARA (Projects, Areas, Resources, Archive) for the more actionable, time-bound stuff, it's a genuinely proven combination. The problem was never the methods.

The problem is upkeep. Both ask you to make a placement decision and a linking decision every time you write something down: which folder, what does this relate to, does anything else need updating now that this exists. Obsidian, Notion, and Roam all give you the primitives (backlinks, graph views, frontmatter), but none of them make those two decisions for you. The discipline erodes a few weeks in, and what's left is a pile of dated, disconnected files: technically a vault, not actually linked.

What we built

Compound is a personal knowledge base stored as plain markdown, where Claude Code makes the placement and linking decisions instead of leaving them to you. You describe what you learned, it searches the vault, decides whether that extends an existing note or needs a new one, files it under the right PARA folder, and proposes links to what's already there.

git clone <your-new-repo-url>
cd <your-repo>
npm i

From there, the entire capture workflow is one command, repeated:

/capture I learned that <something>

Browsing is a second command, npx quartz build --serve, which turns every note into a page with full-text search, auto-generated backlinks, and a graph view showing the connections that would otherwise only exist in your head.

What's actually worth writing about below isn't that feature list. It's what happened when we stopped trusting our own documentation and went looking for where it was wrong.

We tested our own onboarding instead of trusting it

Before calling this done, we cloned the repo fresh and walked the README's own Quick Start exactly as written: npm i, delete the example notes, npm ci the way CI would run it, instead of assuming the steps we'd written down actually worked in that order for someone who isn't us. They mostly did. A few things didn't survive contact:

The indexer's summary line, the first output a new user sees right after following the README's own "delete the example notes" instruction, read Indexed 1 notes. Wrong pluralization, but exactly the kind of detail that makes a tool feel unfinished on the very first command you run against your own, empty vault.

The instructions Claude follows for /capture had Bash(git add/commit) pre-granted in its allowed tools, even though those same instructions say never to commit without being asked. Nothing in /capture actually uses git, so this was a live permission nobody had ever exercised: a real gap between the stated rule and what was technically permitted, not a hypothetical one, sitting in the one command every user runs constantly.

package.json's repository field still pointed at Kazu-Labs/compound. Left in place, every fork created from the template would silently keep its npm metadata pointing back at the original repo instead of itself. Removed.

Running the formatter caught something the formatter itself wasn't looking for: a general instruction in the capture command's own text had drifted into being indented as a continuation of the last bullet in a list, so it read as scoped to content/archive/ specifically instead of applying to every note. That's a meaning bug wearing a whitespace bug's clothes. We restructured the text rather than letting the formatter's output stand as correct just because it was now consistently indented.

And Node 22 is a hard requirement (engine-strict=true fails npm install below it), but nothing told an nvm or fnm user that before they hit the error. Added the pointer to .node-version, which picks the right version up automatically if you know to run it.

None of these are dramatic on their own. That's the point: they're exactly the paper cuts that don't show up if you only test the code paths you already know work, and never test the walk-in-cold path that's the actual first thing most people will do.

Getting the graph actually right

The other place testing against something real instead of a spec mattered was the indexer that backs /vault-review and /ask (scripts/build-index.mjs). It resolves every [[wiki-link]] in the vault into a link graph, written once to a gitignored .compound/index.json so those commands read a precomputed answer instead of re-deriving it from every note on every call. Two bugs in that resolution logic would have quietly undermined the exact thing /vault-review exists to check.

A note's area: frontmatter field is a real connection: it's how a note declares which ongoing area of responsibility it belongs to. But it isn't a [[wiki-link]], so the first version of the indexer never counted it. An area note with five well-organized notes filed under it and zero inline links back would have been flagged an orphan, which is backwards: that's precisely the note doing its job correctly. Fixed by counting area: as its own backlink source.

Separately, Quartz auto-generates a folder-index page for content/notes/, content/projects/, and so on, so a link like [[notes]] resolves to a real page even though no notes.md file exists to match against. Left unhandled, every one of those would show up in /vault-review as broken: a false positive on exactly the kind of structural link a well-organized vault is supposed to have.

Both bugs share a shape: the indexer was correct against its own logic and wrong against what the vault actually looks like once it's real, not a fixture. In the same pass we also found CLAUDE.md and the note template telling users that a note's links field should match another note's title, while the indexer, and the convention actually in use, resolves by filename slug. Two documents that looked authoritative, disagreeing with the actual code, until one of them got corrected.

What it isn't, yet

/converge, which looks for notes from different sources converging on the same idea, is on-demand today, not a report that runs itself. There's no CLI for /ask outside a Claude Code session, so retrieval currently means opening one. And the low-effort workflow depends on Claude Code specifically. The vault itself is just markdown and YAML, readable and editable in anything, so there's no lock-in if you stop, but the filing discipline this whole thing exists to replace comes back the moment the commands aren't there to do it.

One thing we ruled out on purpose: spaced-repetition review. It's on the roadmap as a maybe, deliberately not a near-term goal. The bet is that compounding, well-linked connections beat a review queue at making knowledge stick, and that's worth proving out before adding a feature that competes with it for attention.

Try it

It ships as a GitHub template, not something to fork. Use this template gives you an independent repo with no visible link back, which matters since almost everyone should keep their own vault private. A few example notes about The Art of War ship with it so the taxonomy and graph view have something to render on first run; delete them once you've captured a few things of your own, and you'll be looking at the exact empty-vault path we tested against.