Why Knowledge Bases Are Better Hosted Online Rather Than as Local Markdown

Harry Smart — Fri, 21 Aug 2026 02:16:12 +0000

Why Knowledge Bases Are Better Hosted Online Rather Than as Local Markdown

Doco series · Article 6

Local Markdown is an excellent medium for personal notes. It is portable, inspectable, offline-friendly, and supported by a deep ecosystem. Obsidian is very good at that job.

But a personal note vault and a shared knowledge base have different users. The moment an AI agent must search, cite, and maintain the same material as you, the limitations of a folder full of files become architectural rather than cosmetic.

Notes are for the future you; a knowledge base serves others

A personal note can be messy as long as its author can find it. A knowledge base creates value when another actor can use it reliably. Today, that actor may be a teammate—or an agent that must answer from it, follow changes, and update it.

The question is no longer “Can a model read Markdown?” Of course it can. The question is whether the storage model gives the agent stable identity, current state, safe writes, and an efficient way to navigate.

A local vault belongs to a device

Move to another computer and the vault must be transported or synchronized. Git works well for engineers but remains a workflow. Cloud drives create their own conflict semantics. Sending a file produces a copy that begins aging immediately.

Mobile access is often access to a synchronized file rather than a shared live workspace. An online knowledge base reverses the relationship: the knowledge has one managed home, and each device is a window onto it.

That convenience has a cost. Online systems depend on network availability and an operator. A responsible system needs exports and self-hosting so access does not become lock-in.

Files are not the same unit as knowledge

The conclusion you need is usually one paragraph inside a file. The value that goes stale may be one number. The sentence an agent should change is one block.

In a plain file system, paragraph-level work falls back to file-level work:

read the whole file to change one sentence;
cite “somewhere in this file” instead of a durable block;
rewrite the file after a path- and line-based edit;
lose the old address when content moves.

Doco gives blocks stable IDs independent of position. An agent can cite and patch the same unit a person sees in the editor.

`grep` and `head` are tools, not a knowledge interface

An agent can search local files quickly:

grep -rn "release window" ./notes
head -n 50 ./notes/operations/release.md

Those commands answer where characters occur and what appears near the beginning of a file. They do not answer whether the search covered the current corpus, which heading contains the match, what the surrounding block means, or whether the index and source agree.

A knowledge interface should let an agent browse structure, inspect an outline, search to a block, read around it under a token budget, and return a citation.

Concurrent edits need more than conflict copies

The file model assumes one writer at a time. Once you and an always-on agent maintain the same vault, that assumption fails.

An agent can read a file, you can save a change, and the agent can write its older copy back. A synchronization tool may create two conflict files, but it cannot explain which paragraph each actor changed or which version the agent used.

Doco uses a shared collaborative document for browser and API writes. Reads return version fingerprints. Stale writes fail explicitly. Stable blocks limit the edit, transactions prevent partial batches, and snapshots support rollback.

Markdown still matters—its role changes

Moving knowledge online does not require abandoning Markdown. Doco imports it and exports individual documents or complete knowledge bases. Word and PDF exports are available as well. Browser-local persistence also lets editing continue through temporary disconnection and merge after reconnecting.

Markdown becomes an exchange format rather than the only authoritative storage shape:

flowchart LR
    MD[Markdown files] -- import --> KB[Structured online knowledge base]
    KB -- export --> OUT[Markdown, Word, PDF]
    HUMAN[Human] <--> KB
    AGENT[Agent] <--> KB

A practical decision rule

Choose local Markdown when the material is primarily for you, offline control dominates, and agents do not need to maintain it. Choose a structured online workspace when humans and agents must search, cite, edit, and observe the same evolving knowledge.

This is not an anti-Obsidian argument. It is a scope boundary. The strongest personal notebook and the strongest collaborative agent workspace do not need to be the same product.

The important difference is not the file extension. It is where knowledge lives, what unit has an identity, and who can safely work on it.

Shareable version: Local Markdown is excellent for personal notes. An agent-maintained knowledge base needs more: stable paragraph addresses, structured search, version-protected writes, and one live state across devices. Doco keeps Markdown as an open import/export format while letting humans and agents work on structured blocks online.

DEV Community: Harry Smart

Why Knowledge Bases Are Better Hosted Online Rather Than as Local Markdown

Why Knowledge Bases Are Better Hosted Online Rather Than as Local Markdown

Notes are for the future you; a knowledge base serves others

A local vault belongs to a device

Files are not the same unit as knowledge

grep and head are tools, not a knowledge interface

Concurrent edits need more than conflict copies

Markdown still matters—its role changes

A practical decision rule

`grep` and `head` are tools, not a knowledge interface