`obsidian-second-brain`: The Repo That Turns Obsidian Into a Self-Rewriting Memory System
A deep dive into the adapter pattern, anti-fabrication guardrails, and reconciliation loop that keep an AI vault coherent instead of merely full.
- obsidian-second-brain is trying to maintain knowledge, not just capture it, by rewriting old notes when new evidence arrives.
- Its strongest engineering idea is the boundary between `@generated` and `@user` content, which lets automation update facts without trampling human judgment.
- The adapter layer makes one neutral command set work across multiple LLM CLIs, turning prompt logic into something portable instead of brittle.
- The project treats contradiction as useful signal, because a knowledge base that cannot reconcile disagreement is just a better organized pile of notes.
A Vault That Rewrites Itself
Most AI note tools are really capture tools. They help you dump more into Obsidian, faster, with a nicer wrapper around the same old accumulation problem. `obsidian-second-brain` is aiming at something sharper: a vault that stays coherent over time, even as new evidence lands and old assumptions age out.
That is the real break from the usual second-brain story. The goal is not a bigger notebook. It is a memory system that can revise itself, protect human edits, and keep a running record of why a claim changed.
The Anti-Clutter Trick: Reconciliation, Not Append
The repo’s core move is to treat new information as something to reconcile against existing pages, not just append beside them. That matters because append-only systems hide contradictions in plain sight. They create a vault that is fuller, but not necessarily truer.
| Model | Update behavior | Contradictions | Human edit safety | Portability |
|---|---|---|---|---|
| Append-only second brain | Adds another note or another version | Hidden in the pile | Weak, because the system does not distinguish authorship | High, but shallow |
| Chat-first Obsidian plugin | Answers questions about existing notes | Usually surfaced only when asked | Medium, because chat and storage stay separate | Tied to one UI |
| Karpathy-style LLM Wiki | Builds a living knowledge base | Partly handled by synthesis | Better than capture tools, but often less explicit about guardrails | Conceptual, not always operational |
| obsidian-second-brain | Rewrites existing pages when new evidence arrives | Surface and resolve them | Strong, because sentinel blocks protect `@user` content | High, through adapter-backed commands |
An evolution of Karpathy's LLM Wiki pattern: sources rewrite existing pages instead of just appending, contradictions reconcile automatically, and scheduled agents maintain the vault while you sleep.
Why the Repo Is Built Around the AI, Not the Human
The project’s philosophy is blunt: the vault is optimized for future Claude, not for a human skimming the file browser. That sounds unfriendly until you realize what it buys you. It forces notes to become structured retrieval substrates, with preambles, frontmatter, recency markers, and wikilinks that an agent can parse quickly and consistently.
That is why the repo feels less like a note-taking app and more like a knowledge contract. The note is written today for a machine that will read it later, and that machine needs the note to be predictable.
Every note follows an explicit AI-first design rule (preamble, machine-readable frontmatter, recency markers, mandatory wikilinks, sources verbatim) optimized for future-Claude retrieval rather than human reading.
How Sentinel Blocks Prevent the Usual Automation Disaster
The best engineering idea in the repo is the sentinel-safe write model. Generated content lives in an `@generated` block. Human judgment lives in an `@user` block. That split sounds small, but it solves a giant failure mode: automation that silently overwrites the part a person actually cares about.
<!-- @generated:start -->
## Architecture Summary
- New scan data here
- Confidence: high
<!-- @generated:end -->
<!-- @user:start -->
## Notes from the team
- Keep this example intact
- Human context lives here
<!-- @user:end -->The Adapter Layer Makes One Skill Speak Many Dialects
Once the write model is safe, the next problem is portability. The repo solves that with a neutral `commands/` layer and tool-specific `adapters/` that translate the same intent into Claude Code, Codex CLI, Gemini, and other runtimes. The command is stable. The runtime changes underneath it.
| Layer | Job | What changes | What stays fixed |
|---|---|---|---|
| commands/ | Defines the intent | Nothing runtime-specific | The command logic |
| adapters/ | Translates for each CLI | Tool names and formatting | The underlying behavior |
| scripts/ | Executes research and scans | Implementation details | The workflow goals |
| references/ | Sets the rules | Policy text and note conventions | The vault contract |
What It Means to Treat Contradiction as a Signal
The repo’s research flow is split between open-web discovery and source-grounded vault work. That split is useful because contradiction becomes legible. If the external web says one thing and the vault says another, the point is not to average them into mush. The point is to inspect the gap.
This is the part many AI second-brain tools miss. They optimize for retrieval and summarization. `obsidian-second-brain` is closer to synthesis with accounting. It keeps track of what came from where, how confident the system is, and whether a claim should be rewritten or just flagged.
| Track | Primary source | Strength | Risk |
|---|---|---|---|
| Open web | Perplexity, Grok, live web pages | Freshness | Noise and inconsistency |
| Vault-grounded | Existing notes and internal context | Continuity | Stale assumptions |
| Reconciliation | Both tracks together | Conflict detection | Requires explicit judgment |
How It Compares to Other AI Second Brains
The cleanest comparison is not about features, it is about the job each system thinks it is doing. Append-only tools are capture machines. Chat plugins are query surfaces. Karpathy-style wikis are living notes. `obsidian-second-brain` goes one step further and treats the vault as a maintenance system.
| Project type | Primary promise | What it leaves unresolved |
|---|---|---|
| Append-only second brain | Never lose an idea | Truth drift and duplicated context |
| Chat-first Obsidian plugin | Ask questions about your notes | Whether the notes themselves stay correct |
| Karpathy-style LLM Wiki | Turn notes into a living knowledge base | How to protect human edits and manage contradictions |
| obsidian-second-brain | Maintain a coherent vault over time | The cost is more structure, but the payoff is less drift |
That extra structure is the trade-off. The vault is less casual, less free-form, and more disciplined about format. But if your AI agent is going to keep using the same knowledge base across sessions, that discipline is not overhead. It is the operating system.
Why This Matters Beyond Obsidian
The lesson here is bigger than one repo. If AI is going to live inside our notes, the notes need maintenance semantics. They need boundaries between machine output and human judgment, rules for contradiction, and a way to rewrite stale knowledge without erasing the trail.
That is the real promise of `obsidian-second-brain`. Not a prettier inbox. Not more capture. A memory system that can keep itself honest.
