Why I Moved My Agent Knowledge Base Off Local Markdown

I moved the shared, agent-maintained part of my knowledge base off local Markdown because synchronization, paragraph identity, permissions, and concurrent writes had become application problems. I still use Markdown as an open import/export format; I no longer ask a folder of files to behave like a live multi-user database.

Doco series · Article 13 · Migration retrospective

This is not a breakup letter to Markdown. Plain text remains one of the best formats for notes: readable, portable, diffable, and supported almost everywhere. Obsidian's documentation is explicit that a vault stores notes as local Markdown files in a folder, which is exactly why it is durable and easy to inspect; see How Obsidian stores data.

The boundary changed when the knowledge base stopped being only mine. I wanted people to edit in a browser while an agent searched, cited, and maintained the same material. At that point, every advantage of “just files” remained—but several missing behaviors became my responsibility.

Doco is the system I am building in response, so this is a first-party migration account rather than a neutral product comparison.

The first warning was copy ambiguity

On one computer, a Markdown vault feels canonical. Add a laptop, a phone, a cloud-sync folder, a Git remote, and an automation job, and “the file” becomes several replicas connected by workflows.

Most of the time, the replicas converge. The difficult moments are the ones that matter:

• a device edits an old copy after waking from sleep;
• a sync provider creates a conflict file;
• a teammate sends an exported folder that immediately diverges;
• an agent reads before a pull and writes after a human change;
• a path changes and an external citation stops resolving.

Git makes divergence explicit and auditable. Its merge documentation also explains the operational truth: overlapping changes can stop the merge and leave conflicts for the user to resolve. That is a good engineering workflow, but it was not the real-time writing experience I wanted for every teammate and agent action.

The second warning was paragraph identity

Agents rarely need to replace an entire document. They need to update a deadline, add one observation, or fix a policy paragraph.

In a local file, the common addresses are path, heading, line number, or surrounding text. Each is positional:

• move the file and the path changes;
• rename the heading and the selector changes;
• insert a paragraph and line numbers move;
• edit the surrounding sentence and a text-match patch may fail.

I wanted a paragraph to retain an identity independent of where it appeared. In Doco, document blocks carry stable IDs in the ProseMirror/Yjs state. Moving a block preserves its ID; copying it creates a new one. A citation can point to the same logical paragraph after an outline is reorganized.

ProseMirror's guide describes documents as structured nodes rather than an undifferentiated text buffer. That structure is a better substrate for tables, callouts, tasks, code blocks, and bounded agent edits than pretending every operation is a line-oriented patch.

The third warning was the read-write race

The dangerous workflow looked harmless:

1. the agent reads policy.md;
2. I edit and save policy.md;
3. the agent writes a complete replacement based on its older read;
4. my change disappears or survives only in history.

A Git diff may reveal the loss later. A conflict-aware write prevents it at the boundary.

The online system returns a content version with the read. The agent must present that version when it writes. If the document changed, the update fails and the agent must reread. This follows the conditional-request model of HTTP If-Match, which is designed to prevent accidental overwrites of changed resources.

The important shift was psychological: a conflict became an expected result, not an exceptional mess to hide with “last writer wins.”

The fourth warning was permissions

A process that can open a local vault often inherits broad filesystem access. Restricting it usually means sandboxing directories or creating copies. Neither model naturally expresses “search this knowledge base, read those two documents, and update only documents in this workspace until Friday.”

An online API can issue hashed, revocable tokens with separate read and write scopes, rate limits, and finite lifetimes. It can also record which actor changed which block from which source version.

That does not make online access automatically safe. It moves safety into an explicit capability boundary that can be reviewed and tested.

What I kept from Markdown

The migration did not require converting every note into a proprietary dead end.

• Markdown remains an import format.
• A single document or complete knowledge base can be exported back to Markdown.
• Images are exported alongside the documents with relative links.
• Self-hosting keeps the service boundary under the operator's control.
• Local browser persistence supports temporary disconnection.

Markdown changed roles. It became a durable interchange and backup format while the collaborative document became the active source of truth.

This separation is useful even outside Doco. A database can be authoritative without trapping users if it supports complete, documented exports. A file can remain portable without carrying all concurrency, authorization, and indexing responsibilities itself.

A migration path that did not require a big bang

The practical sequence was incremental:

1. Classify the vault. Personal scratch notes stayed local; shared operational knowledge became the migration target.
2. Import without deleting. The original Markdown remained a rollback source while headings, links, tables, and attachments were checked.
3. Choose canonical documents. Duplicate policies were resolved before automation could cite them.
4. Start agents read-only. Search and citations were verified against the browser.
5. Enable one bounded write. A reversible block update tested identity and version conflicts.
6. Test export. The exit path was verified before declaring the online workspace authoritative.
7. Archive the old shared vault. Read-only history is less confusing than two writable sources of truth.

The hardest work was not format conversion. It was deciding which copy was canonical and which workflows still assumed local paths.

When I would stay with local Markdown

I would keep local Markdown as the source of truth when the notes are primarily personal, offline access is central, Git review is acceptable, and automation operates inside the same trusted device boundary.

I would move a collection online when several people and agents need one current state, paragraph-level addresses, permissioned tools, live edits, and conflict-protected writes.

The decision is not Markdown versus rich text. It is personal files versus a shared operational system.

FAQ

Did you stop using Markdown?

No. Markdown remains useful for authoring, exchange, versioned exports, and offline archives. I stopped using a local folder as the only authoritative state for shared human-agent work.

Is Git a bad collaboration system for documents?

No. Git is excellent when contributors are comfortable with branches, diffs, and explicit merges. It is less suitable for teammates who expect live browser editing or for frequent small agent updates that should appear immediately.

Does moving online sacrifice ownership?

It can if the service lacks exports or self-hosting. The migration should include a tested exit path. Doco supports Markdown export and an MIT-licensed self-hosted deployment for that reason.

Should every personal note move to an online knowledge base?

No. Move only the material whose collaboration and agent requirements justify the operational service. Keeping private scratch notes local reduces complexity and exposure.

Bottom line

Local Markdown did not fail at being a file format. I asked it to provide stable block identity, shared live state, permissions, indexing, and concurrency control. Moving the shared agent knowledge base online let each layer do one job well—and keeping open Markdown export made the decision reversible.

Originally published on Doco.

Doco is an open-source document workspace where humans and AI agents write together. Explore Doco.