Everyone who takes notes eventually hits the same wall. You capture diligently — clip an article, jot an idea, forward yourself a link — and a year later you have a folder with four hundred files in it and no idea what’s inside. The notes rot. Not because the tool was bad, but because a folder of files was never actually knowledge. Knowledge is the connections: this idea supports that one, this source contradicts a claim you wrote six months ago, this entity shows up across a dozen unrelated notes. A pile of Markdown has none of that, and no amount of tagging fixes it, because the work of connecting is exactly the work nobody has time to do by hand.
The obvious modern move is to point an AI at the pile. And the obvious modern failure is what happens next: the AI writes a beautiful, confident, cross-linked wiki that is quietly full of things it made up. You’ve traded a folder you don’t read for a wiki you can’t trust. That’s worse.
So we built something with a sharper split down the middle. It’s called the Second Brain: a local, Obsidian-compatible knowledge vault — plain Markdown, all yours, no cloud — that an AI agent maintains as a living wiki, where the mechanics and the judgment are done by completely different things, and where every single claim is chained to evidence you can trace.
The insight: separate the mechanics from the judgment
Most “AI knowledge base” tools blur two very different jobs into one model call. One job is mechanical: fetch a URL, hash its bytes, write a file exactly once, check that no link is broken. The other is judgment: read a source, decide what actually matters, name the concept, choose which existing pages it connects to. Mechanics should be boring, deterministic, and identical every time. Judgment is the part you actually want an intelligent agent for.
The Second Brain draws a hard line between them. The command-line tools that do the mechanics never call a model — not once. They are plain, dry-run-first programs: capture, hash, validate, report. Every act of judgment — summarizing, choosing concepts, writing a claim, deciding a cross-link — is the agent’s, made live in a session. That single split is the whole design, and it’s what makes the result trustworthy: the deterministic parts can’t hallucinate, and the intelligent part can’t quietly corrupt your store, because it can only add claims that cite fixed evidence.
Following one source through the pipeline
Every source takes the same path, and it’s worth walking it end to end.
You supply a source — a URL, a forwarded message, a note. A deterministic ingest step fetches it, extracts readable Markdown, and files an immutable raw receipt. The receipt is the atom of trust: one Markdown file whose frontmatter records where the content came from, when it was captured, and two SHA-256 hashes — one over the fetched bytes, one over the normalized stored body. Those hashes buy two things at once: deduplication (re-ingest the same content and you get the existing receipt back, byte- and mtime-identical) and tamper-evidence (the stored bytes are pinned). Once written, raw/ is never opened for writing again. It is the fixed ground everything else stands on.
Then comes the one judgment step. The agent reads the receipt and distills it into the wiki: a concept page, an entity page, a summary — cross-linked to the rest of the vault with Obsidian-style [[wikilinks]]. Crucially, every knowledge page lists the raw receipts it draws from in a sources field. A claim without a citation isn’t allowed to stand.
Finally, two deterministic tools keep the whole thing honest. link-check scans the entire graph and is only clean when five categories are all empty: no broken links, no ambiguous links, no knowledge page unreachable from the index, no raw receipt that no page cites, and no receipt or schema errors. ripple does something subtler and more valuable: when a new source lands, it reports which existing pages that source probably touches — a review to-do list for the agent, generated by lexical matching, never an automatic edit. That’s the loop that compounds. Add one source, and ripple tells the agent which of its old pages deserve a second look, so the graph gets denser and better-connected every time you feed it, instead of just longer.
The payoff: a web, not a pile
Here’s the difference made concrete. A single raw receipt about, say, global workspace theory might be cited by three different wiki pages — a summary, a concept, an entity for the lab that published it — and those three pages link to each other. Follow any edge and you can trace a claim back to the exact bytes it came from.
That interconnection is the entire value, and it’s the thing a folder can never give you. But an interconnected graph is also the thing that rots fastest if nobody tends it — one renamed page and a dozen links dangle. So the graph isn’t tended by hope; it’s tended by link-check, which mechanically refuses to call the vault clean while a single link is broken, a page is orphaned from the index, or a receipt sits uncited. The web can’t silently decay, because a deterministic tool is watching the joints.
The vault’s shape on disk reflects the same philosophy. Top-level folders are lifecycle layers, not topics: raw/ for immutable receipts, wiki/ for maintained pages (split into concepts, entities, summaries), an append-only log.md, an index.md that every page must be reachable from. Subjects don’t get their own folders — they emerge from the links between pages, so the tree stays flat and the connections do the organizing. It’s a normal folder of Markdown, so it opens in Obsidian and lives in plain git; there’s no proprietary format to be locked into.
What actually shipped, and the rules that keep it honest
The first version is six deterministic pieces, each built as its own slice and each dry-run-first: a vault scaffold, the ingest-and-validate core (ingest, link-check, ripple), a capture adapter that turns a forwarded message into a pending inbox item without ever downloading media, a review-only digest that ships disabled and only proposes, a copy-never-move seeder for migrating a legacy note tree, and a read-only mobile explorer for browsing the graph from your phone.
Underneath them sit five principles we were unwilling to bend:
- Immutable raw. Sources are stored once, hashed, and never edited — the evidence you trace claims back to.
- Dry-run first. Tools print their plan before touching disk, and create files exclusively; nothing is overwritten.
- Copy-never-move. Capture and migration only ever add files. Your existing material is never renamed or deleted.
- No LLM in the CLI. The commands are deterministic. Every summarize, link, and promote decision belongs to the agent.
- Digest never promotes. It suggests follow-up work outside the vault; a human or agent decides what to act on. Nothing runs on a timer.
One honest limit worth stating plainly: the vault directory is a single trust boundary. The provenance in a receipt attests to what a capture declared, not to some external oracle — anyone who can write the vault can assert anything. That’s an acceptable trade for a personal, local store, and it’s documented rather than papered over. Trustworthiness here means auditable — every claim leads back to fixed bytes — not cryptographically adversarial.
That’s the whole idea: a knowledge base an agent genuinely maintains, kept truthful not by trusting the agent but by never letting it write a claim it can’t back up. Notes stop rotting when the connections are real and the evidence is pinned. The second brain isn’t the pile of files — it’s the honest web strung between them.
Common questions
How is this different from just keeping notes in a folder?
A folder of files isn’t knowledge — it’s a pile. The Second Brain adds two things a pile lacks: an interconnected graph of [[wikilinks]] so ideas actually reference each other, and a rule that every knowledge page must cite a stored source receipt. A deterministic link-check keeps the graph honest, flagging broken links, orphaned pages, and claims with no evidence behind them.
Does an LLM run inside the tools? No. That’s the core design line. The command-line tools are fully deterministic — they never call a model. They capture sources, compute content hashes, validate links, and report which pages a new source might touch. Every summarization, concept-naming, and cross-linking decision is made by the agent session, never baked into a CLI.
What is a raw receipt? One immutable Markdown file storing a captured source. Its frontmatter records provenance plus two SHA-256 hashes — one over the fetched bytes, one over the normalized stored body — which give deduplication and tamper-evidence. Once written, a receipt is never edited; re-ingesting the same content returns the existing file byte-for-byte.
Does it edit my knowledge automatically or run on a timer? No. The vault ships with no scheduler — no cron, no timer, no background service. Tools are dry-run-first: they print their plan before touching disk. The digest command only proposes follow-up work outside the vault; it never promotes, writes, or runs on its own. A human or an agent session decides what actually happens.
← all posts