Your Obsidian vault cannot be your AI agents' knowledge base

An Obsidian vault fails as an AI agent knowledge base for three structural reasons: it is private to one machine, its claims carry no citations, and nothing tells you when a note stopped being true. Agents read whatever they are handed and have no way to tell a current note from one that expired three sprints ago — so the confident wrong answer and the correct one arrive looking identical.

This is not a criticism of Obsidian. It is very good at the job it was built for, which is one person thinking. The failure is a category error: a personal thinking tool being asked to be a shared source of truth.

Can agents read an Obsidian vault at all?

Yes, and this is worth clearing up first because it is where the conversation usually starts. A vault is a folder of plain markdown. Any agent with file access reads it without ceremony, and there are MCP servers that will wire one up for you in an afternoon.

Access was never the problem. Reading and trusting are different operations, and a vault carries no signal that separates them. A note written last week and a note that stopped being true in 2024 are the same kind of object, in the same folder, with the same authority. A human reading their own vault discounts automatically — oh, that one is old — using knowledge that is nowhere in the file. An agent has nothing to discount with.

So the easy half gets solved, the hard half is not noticed, and the setup looks like it is working right up until it confidently acts on something that expired.

The three failures, in order of how much they cost

1. It is private, so knowledge is per-person

A vault lives on a laptop. Sync it and you have a shared folder, not shared knowledge — because the vault has no notion of review. Nobody approves a note. Nobody is accountable for one. Two engineers keep two vaults, each correct about different things, and the agent gets whichever vault its operator happens to own.

The symptom is easy to recognise: the same question gets two answers depending on who asks their agent.

2. Claims carry no provenance

A note says “we do migrations in two steps.” Is that a decision someone made, an observation from one incident, or something a colleague believed in 2024? The note does not say, and after a few months nobody remembers.

For a human reader this is friction. For an agent it is fatal, because the agent cannot weigh a claim it cannot trace. It will follow a stale note with exactly the confidence it follows a correct one.

3. Nothing marks a note as expired

This is the one that quietly does the most damage. A vault has no death state. Notes accumulate, and the only mechanism for removing a wrong one is a person remembering it is wrong — which reliably fails, because the person who knows the note is stale is not the person reading it.

The result is a corpus that grows monotonically more confident and less accurate.

What does documentation for agents have to be?

Every property below exists because of a specific way vaults fail:

Property	The failure it answers
Lives in the repository	Reviewed like code, not synced like a folder
Cites a decision, task or file	A claim you cannot trace is a claim you cannot weigh
Written when work closes	Not “whenever someone remembers”, which is never
Has an archived state	A wrong note must be removable by something other than memory
Loaded by what the task declares	Fifty notes is not context, it is noise

That last row is the one most tools miss. Handing an agent an entire knowledge base is not context engineering; it is a bigger prompt. What a task needs is the subset relevant to this task, selected by something the task itself declared.

Why not just give the agent the whole vault?

The obvious move, and it fails in three specific ways:

Volume is not context. Four hundred notes in a prompt means the three relevant ones are diluted by three hundred and ninety-seven that are not. That is a bigger prompt, not better grounding, and it costs accuracy rather than buying it.

Nothing says which notes apply here. A vault’s links encode association — this reminded me of that — not applicability to the task in front of you. Those are different relations, and only one of them is useful for selection.

Contradictions have no resolution. Two notes disagree about how deploys work. Nothing in the vault records which one won, because the winner was decided in a conversation. The agent resolves it by picking whichever reads closest to the prompt, and reports the result with the same confidence either way.

The outcome is worse than a short curated file would have been: an answer that is well-phrased, apparently well-sourced, and wrong.

Does RAG over the vault fix it?

Partly, and it is worth being precise about which part, because this is the most common proposed fix.

Retrieval solves selection. That is genuine — it turns “the agent read four hundred notes” into “the agent read the four closest ones”, which is a real improvement and the annoyance people feel most.

It does not touch provenance or staleness, and on staleness it leans slightly the wrong way. Retrieval surfaces whatever is textually nearest the question, and a confidently written stale note — “we do migrations in two steps” — is frequently the nearest thing to a question about migrations. The correct note may be newer, hedged, and worded less like the question. Embeddings have no opinion about dates or truth; they rank similarity.

So RAG upgrades the problem from the agent read everything and could not tell what was current to the agent read the four most relevant things and could not tell what was current. Better, and not the fix.

What about Notion, Confluence or a wiki?

They answer one of the three failures cleanly and leave the other two roughly where they were.

Shared: yes. This is the real gain, and it is not nothing — one corpus, many readers, no more “the same question gets two answers depending on whose vault the agent read”.

Provenance: no. A wiki page rarely says which decision it came from or which incident produced it, for the same reason a vault note does not: whoever wrote it knew, so writing it down felt redundant.

Staleness: arguably worse. A vault’s bad notes are at least buried. A wiki’s are indexed, searchable and linked from four other pages, so scale makes a stale claim more discoverable rather than less, and nothing in the tool archives it. The mechanism for removing a wrong page is still a person remembering.

And one failure the wiki adds: it is not where the code changes. A note in the repository is in front of you in the diff at the moment you alter the thing it describes. A note in a wiki is read when somebody goes looking — which is the behaviour you were trying to fix.

How CommitCycle does it

CommitCycle calls these playbooks — per-topic, per-project knowledge files that live in your repository. Four properties, each answering one row above:

• They cite. Every claim points at a decision, a task or a file. A lint checks the citations resolve; a playbook with no citable content is not created at all.
• They are fed at the close of work, one bullet at a time, when the person still remembers why. Not in a retro, not when someone remembers.
• They are loaded by the task’s declared topics, so a task about the database does not load the frontend’s conventions.
• They can be archived. archived is a real state, which is what makes the corpus able to shrink.

And an adversarial pass — cycle challenge — proposes the practices the repository visibly lacks, each with a named source. You can refuse, and your refusal is recorded with its grounds. “We deviate from this on purpose, and here is why” is knowledge too, and it is the kind that vaults never capture because nobody writes down what they decided not to do.

The honest part

There is a real objection here and it deserves a straight answer: “if you generate a playbook from my legacy repository, won’t it just codify my mess?”

Yes. By design, description alone codifies the mess — with receipts. That is why the challenger exists. It proposes what the repo lacks rather than only describing what it has, and a human accepts or refuses each proposal. There is no auto-accept, and a test holds that door shut.

What this does not replace

Keep the vault. This is not a migration.

Obsidian remains better than anything here at thinking — at half-formed ideas, at connections you have not made yet, at notes that are for you and are allowed to be wrong. What moves out of it is the subset that other readers rely on being true. That subset was always the part that hurt when it went stale, and it was never the part Obsidian was designed to hold.

A useful line to draw: if being wrong about this note would mislead someone else, it does not belong in a personal vault.

Where it goes instead, for the notes an agent is meant to read, is a skill in the repository — same markdown, but versioned with the code it describes and loaded only when the task calls for it.

Where CommitCycle actually is

CommitCycle runs its own development — the board, the gate, the audit records and the playbooks described above are in use on its own repository today. The enforcement half installs: a Claude Code plugin, or the commitcycle package on npm for the CLI alone. The hosted board is invitation-only while this is small. Phase 0 is measured and published with its limits.

So this post is not asking you to migrate anything today. It is making an argument you can evaluate on its merits, and if it lands, the waitlist is the honest next step. If the argument is wrong, that is worth more to us than a signup.

---

The four failure modes this comes from, and the mechanisms that answer them, are documented in full: the AGENTS.md context block, zones, and the audit record.