Vault knowledge base + AI agent: 7 design decisions for the long run

A Markdown knowledge base does more than store notes. It has to stay readable for a human, usable by an AI agent, and compatible with vector search. It also has to last for years without turning into a set of notes that contradict one another. Several guides published in 2026 promise that balance. In practice, not all choices hold up equally well.

I keep seven design decisions here. Each one departs from a pattern that became common in 2026, and each one has a cost. My goal is not to offer a universal recipe, but to make those trade-offs visible.

The 2026 context

The 2026 ecosystem around AI-powered knowledge bases rests on three recurring elements.

The first is a community gist published in the spring, which describes a pattern for an LLM-maintained wiki. Raw sources stay intact, and the agent produces compiled notes from them. The pattern then spread through several posts and repositories.

The second is a series of guides on combining Obsidian, an agent, and a Model Context Protocol (MCP) server. That stack is often presented as the normal way to expose a local vault to a natural-language assistant.

The third is more discreet, but more useful for sorting signal from noise. Two ETH Zurich studies published in early 2026 measured the effect of agent context files such as AGENTS.md or CLAUDE.md. As reported, their results temper some of the comfort and efficiency claims found in the most enthusiastic posts.

The gap between those guides and what I observe in practice justifies the seven decisions below.

The seven decisions

1. No automatic cascade updates

The common pattern updates several notes at once when a source changes. On paper, that makes the system look self-correcting.

I prefer a different rule. One ingestion creates or updates a single note. Effects on nearby notes are flagged at the end of the session, then reviewed by hand on a regular schedule.

Automatic cascades also spread errors. The agent decides what is materially affected by a new source, then sometimes fixes the wrong file without anyone noticing right away. After a few months, the base drifts away from what the sources actually say.

The ETH Zurich studies on agent context files report a cost increase of around 20 percent in some cases, with no clear gain in return. What I keep from that is the practical effect. A base that drifts in silence is worth less than a base that forces a reread of the affected points. The first one reassures too quickly. The second stays verifiable.

The cost I accept is a weekly review of about thirty minutes for an active vault with several hundred notes. That is not free, but the budget is clear.

2. No default MCP server

Several guides recommend adding an MCP server to expose the vault to Claude Desktop or Cursor. In a single-user command-line setup, that layer adds mostly one more step.

An agent, such as OpenCode or Claude Code, can read the filesystem directly. It does not need an extra intermediary to open a file that is already available locally.

One widely circulated guide cites a benchmark where a CLI search uses around one hundred tokens, compared with several million through MCP for the same task. I take that as a cited order of magnitude, not as a general law. It is enough to show how quickly the cost rises when you add a layer that brings little to this setup.

If the vault ever needs to be exposed to a remote agent or to multiple users, an MCP server can enter the picture. For now, I leave it out.

3. Fixed taxonomy rather than emerging topics

The common pattern lets categories emerge as ingestions arrive. If a new source does not fit any existing topic, I create one. The system looks flexible, but it moves without guardrails.

I do the opposite. A closed list of domains lives in a versioned file, for example domains.txt. Every note must carry a domain: field whose value appears in that list. A validation hook rejects the write if the domain does not exist.

The technical point is straightforward. In a vault that mixes several domains, technical, commercial, personal, and monitoring, semantic bleed between domains quickly becomes the main source of noise in a vector pipeline. Folder names do not change much there, because an embeddings pipeline reads text, not the filesystem tree. A structured metadata field, on the other hand, can act as a query filter.

The cost I accept is small. The taxonomy evolves slowly, with a few additions or merges per quarter. That is less flexible than a category created on the fly, but much more stable.

4. No manually maintained global index

A single global index looks convenient at first. In practice, it grows fast, becomes painful to reread, and asks for a level of upkeep that few vaults keep up over time.

I prefer several Maps of Content, or MOCs, in a dedicated folder. Each MOC covers one top-level domain, such as telephony, infrastructure, or sales. There is no central file that claims to summarize everything.

The choice addresses a size and maintenance problem. A single index over several hundred notes starts to look like a table of contents heavier than the corpus itself. Local MOCs stay closer to the work context. They are easier to read, fix, and evolve.

The cost I accept is the lack of an immediate overview. If I want to know how many SIP notes exist, a grep or find answers in a few seconds. It is not elegant. It is useful.

5. No durable write without human validation

The common pattern lets the agent write directly into the durable base. Promoting a raw source into a synthetic note, or updating an existing article, then happens without an intermediate step.

I keep a human validation step before any durable write. The agent proposes a target path, a draft note, or an action on the source. The human checks it before the note is written to disk.

The worst case is not an incomplete base. It is a false one. An error rate of just a few percent in durable notes is enough to weaken trust in the whole vault. I no longer use the base the same way if I have to verify every answer by hand.

The cost is modest. Reading and validating a note often takes less than a minute. Over a year, that discipline weighs little. In return, it keeps the vault growing without losing reliability.

Obsidian guides often rely on wikilinks in the body of notes to rebuild the relationship graph. For a vector pipeline, parsing the whole Markdown body on every pass is not ideal.

I add a more explicit layer. The essential links, usually three to five, are duplicated in the front matter under a related: key. The wikilinks stay in the body for human reading and Obsidian’s native graph.

The benefit is twofold. First, the front matter parses without effort. Second, the related: list forces me to choose the central links instead of piling on references throughout the text. The result is less decorative, but easier to use.

The cost is deliberate duplication. It adds an editing constraint, but it avoids rebuilding the graph by reading the whole body of the note.

7. Confidentiality enforcement on the RAG server only

When I talk about confidentiality, the temptation is to filter notes directly in the local agent. In practice, that gives the impression of control rather than actual control.

I place confidentiality rules only on the retrieval-augmented generation (RAG) server. The local agent ignores confidentiality markers in the notes. The rules are enforced on the server that serves users through an authenticated API, for example with single sign-on (SSO) and JSON Web Token (JWT).

The reasoning is direct. A local agent runs under the user’s identity, on a filesystem the user already has direct access to. A cat command is enough to read a file. Filtering at that level does not protect much. The useful layer is the one where the user does not see the files directly, so the RAG server.

The cost that follows from this logic is simple. If a document should not be read in cleartext, it should not remain in the vault. It has to be kept outside the scope, encrypted separately, or stored in a protected space the agent never touches.

A common philosophy

These seven decisions rest on three principles.

The first is design sobriety. A text file is often better than one more automation, a Git commit is often better than a cron job, and a shell script is sometimes enough where a heavier stack would mostly add complexity and failure risks.

The second is skepticism toward popular patterns. A widely shared gist or an impressive benchmark is not enough to validate a choice. What matters is how it behaves over time, with a real corpus and real constraints.

The third is visibility into trade-offs. Every decision has a cost. I prefer to make it explicit from the start rather than discover it later as hidden debt.

What I do not know yet

I still have a few points to check in practice.

  • Over five years, will the fixed taxonomy stay stable, or will I have to refactor it more often than expected?
  • Will human validation of every promotion remain workable beyond a personal setup?
  • Will server-side RAG enforcement hold up against prompt injection attempts more elaborate than the ones I test today?
  • Will the related: field be filled consistently, or will it end up empty out of habit?

These are still working hypotheses. A review after twelve months will show what they are worth in practice.

Three points

1. The 2026 patterns around LLM-powered knowledge bases are useful, but they do not all translate equally well to a vault in practice.

2. The seven decisions here aim for stability, readability, and verifiability. They do not aim to maximize automation.

3. The common logic is design sobriety, skepticism toward technical fashion, and making costs explicit.

Further reading

  • LLM Wiki, community reference gist (April 2026) - gist.github.com/karpathy/442a6bf555914893e9891c11519de94f - describes a raw source plus LLM-compiled wiki pattern.
  • Obsidian skills for agents, kepano reference - github.com/kepano/obsidian-skills - collects official skills for Claude Code, OpenCode, and Cursor.
  • Obsidian + Claude AI Knowledge Management Setup 2026 - buildmvpfast.com - lays out three integration paths.
  • Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (ETH Zurich, 2026) - arxiv.org/abs/2602.11988 - studies the impact of agent context files.
  • On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (ETH Zurich, 2026) - arxiv.org/abs/2601.20404 - complements the efficiency analysis.
  • Public position from Obsidian’s creator on the value of a local MCP server - x.com/kepano - discussed in several community threads.

The blog’s RSS feed lets you follow the rest.