Obsidian + Claude Code: The Cheapest Second Brain You Can Build

Working note No. 11 — on the laboratory notebook, rebuilt around an agent.

Abstract. This note describes the knowledge system behind everything else in this series — and, unusually for this series, you can copy it in ten minutes. The entire setup is a folder of markdown files (an Obsidian vault) plus one protocol file, with the Claude Code CLI pointed at the folder. No plugins, no vector database, no embeddings, no retrieval pipeline. It is also, by a wide margin, the cheapest agent memory we have used: because the agent navigates links and reads only the pages a question actually requires, a session touches a few thousand tokens of notes instead of re-ingesting a corpus — and the protocol file ends the most expensive habit in agent work, re-explaining your context every session. Karpathy's recently published "LLM wiki" arrives, by a different route, at nearly the same architecture. We take this as encouraging.

1. Introduction

Every discipline this series has described depends on record-keeping. A graveyard without burial records is just a mood. A pre-registered constant that lives in someone's recollection is not pre-registered; it is negotiable. The drawer of note No. 9 has a calendar, and a calendar must be written somewhere that survives enthusiasm.

For years the somewhere was the usual sediment: scattered documents, commit messages, the false memory of having written things down. The current arrangement replaced all of it, and is simple enough to describe in one sentence: a vault of plain markdown files, linked into a graph, that a language-model agent reads and writes alongside us.

2. The whole setup

We list it in full because the brevity is the argument:

A folder of markdown files. Ours is an Obsidian vault, though nothing depends on Obsidian — the files are the system.¹ Territories: research studies (one file per hypothesis, proposal to verdict), backtest reports, an incident log, architecture decisions, and an _index.md that summarizes the whole.
Links. [[wikilinks]] between pages do the structural work — a study links to the method that judged it, the incident that motivated it, the earlier funeral it must not repeat. Obsidian renders this as a graph; the graph is stored in the text itself.
One protocol file. A CLAUDE.md at the vault root: the lab's standing rules, loaded automatically into every session. Naming conventions, what a burial record must contain, what the agent may write and may not decide.
The Claude Code CLI, pointed at the folder. cd vault && claude. That is the entire integration.

There is no step five. Setting this up took an afternoon; most of the afternoon was moving old notes in.

3. The token economics

The arrangement is cheap for a structural reason worth spelling out, because it is the opposite of the default architecture.

The default architecture — retrieval-augmented generation — embeds the corpus, stores it in a vector database, and stuffs retrieved chunks into every prompt. You pay to embed everything, you pay to re-embed what changes, and you pay again each session for retrieved context of uncertain relevance.

The navigating agent pays differently. It opens _index.md — one small page — follows two or three links, and reads only the files the question actually requires. A typical session touches a handful of pages, not a corpus. The protocol file compounds the saving: the standing context that users of chat interfaces re-paste every morning — who we are, how we work, what the rules are — loads once, automatically, from disk.² And markdown itself is the cheap format: the same content that costs a fortune as OCR'd PDF or exported HTML is a few hundred tokens of clean text.

The failure modes are cheaper too. When a RAG pipeline retrieves nonsense, the failure is buried in an embedding space. When a navigating agent reads the wrong page, the wrong page is right there in the session log, and the fix is a better link or a better index entry — repairs a human makes in the same medium, in seconds.

4. What the agent actually does

It drafts study writeups from run artifacts. It files burial certificates in the graveyard with cross-links to the refuting evidence. It keeps the index honest. And — its most quietly valuable habit — it flags when a new proposal resembles a resident of the graveyard. The second coming of an idea, which note No. 1 priced at "a lookup," is now priced at zero: the lookup performs itself.

Fig. 1 shows the topology, stylized. Clusters are research themes; the dense node in each cluster is usually a method or an index page; the orphans at the periphery are unfinished thinking, which the graph renders visible instead of forgettable.

The vault as a graph traversed by two kinds of reader

Fig. 1. This figure shows a stylized rendering of the research vault's link graph. Gray edges are links made by the human; red dashed edges are cross-references added by the agent, which traverses the graph the way a researcher follows citations — the red node marks its position mid-traversal. Outlined nodes are orphans: pages not yet linked into the structure, i.e., thinking not yet finished. The topology is illustrative; the real graph's contents are, as usual, not shown.

What does not change is authority. The agent writes pages; it does not write verdicts. Constants are set by humans before studies run; the agent's role in pre-registration is to be the notary, not the judge. One hygiene rule is worth stating: agent-drafted pages must cite their sources — the run artifact, the linked study — because a fluent summary with no provenance is the knowledge-base equivalent of a backtest with no trial count.³

5. Distinguished company

We built this for local reasons, so it was instructive to watch Karpathy (2025) publish, as a general recommendation, nearly the same machine: an Obsidian vault in which raw captured material flows into one directory and an agent continuously refines it into an interlinked wiki of markdown pages with backlinks and a maintained index — explicitly instead of retrieval-augmented generation. His reasoning matches our accounting: markdown is vendor-free, version-controllable, diffable, and — a fact that still feels like a coincidence but is not — the format language models read and write most fluently. The zettelkasten tradition (Ahrens, 2017) arrived at the linked-note graph decades before there was an agent to walk it; the agent, it turns out, is the reader that architecture was waiting for.

6. Conclusion

The laboratory notebook is the oldest institution in experimental science, and its function was never storage; it was the enforcement of honesty across time. Ours now talks back — proposes links, remembers funerals, recites the protocol to every new session — and it costs a folder, one rules file, and the tokens of the pages actually read. If you build one thing from this series, build this. The graveyard can come later; it will need somewhere to live.

Notes

This is the property to insist on if the reader builds one: the application must be dispensable. Our vault would survive Obsidian's disappearance as a folder of readable files; the graph lives in the [[wikilink]] syntax, not in a database.
The protocol file is the closest thing the arrangement has to a constitution, and it accumulates the way constitutions do: each amendment traceable to the incident that motivated it.
The rule has a second function: it keeps the agent's confident register honest. A language model summarizes with the same fluency whether its source is strong or thin; a mandatory provenance link lets the reader — human or machine, next week or next year — reweight the fluency by the evidence.

References

Ahrens, S., 2017. How to Take Smart Notes: One Simple Technique to Boost Writing, Learning and Thinking. CreateSpace, North Charleston.

Karpathy, A., 2025. LLM wiki: an agent-maintained markdown knowledge base. Design note, github.com/karpathy.

Keywords: Obsidian, Claude Code, knowledge graph, plain text, agents, zettelkasten, token efficiency.