DEV Community: Harry Smart

Designing a Document API That AI Agents Cannot Break

Harry Smart — Tue, 08 Sep 2026 05:57:35 +0000

You cannot make an AI agent incapable of proposing a bad edit, but you can design a document API so one stale, oversized, duplicated, or partially authorized request cannot silently corrupt the source of truth. The core controls are stable block identity, version preconditions, atomic operations, idempotent retries, least privilege, audit evidence, and recoverable history.

Doco series · Article 14 · API engineering guide

“Agents cannot break documents” is a useful design goal only after it is translated into failure modes. No API can guarantee that a grammatically valid change is factually wise. It can guarantee that concurrency, retries, partial failures, and permission mistakes behave predictably.

Doco is the document system I am building, so the examples below describe its first-party contract. The principles apply to any API that lets autonomous or semi-autonomous clients maintain important text.

Define “break” before defining endpoints

An agent breaks a document system when it can cause one of these outcomes without an explicit, recoverable signal:

Failure	Unsafe behavior	Required control
Lost update	Old content silently replaces a newer edit	Version precondition
Wrong target	A moved paragraph can no longer be addressed	Stable block ID
Oversized mutation	One sentence change replaces the whole document	Bounded block operation
Partial batch	Two of five edits apply before the third fails	Atomic transaction
Duplicate retry	Network retry creates the same section twice	Idempotency key
Excess authority	Read workflow can delete or publish	Narrow scopes
Invisible origin	Nobody can explain who changed what	Audit event and provenance
Bad recovery	A mistake is permanent	Snapshots and rollback

This table is more valuable than a long endpoint list. It turns a slogan into acceptance tests.

Give every editable block a stable identity

A path identifies a file. A line number identifies a temporary position. A heading identifies a label that users routinely rename. None is a durable paragraph address.

Store a stable block ID in the canonical structured document:

{
  "id": "block_01K0Y7R5F…",
  "type": "paragraph",
  "content": [{ "type": "text", "text": "Rollback begins after five minutes." }]
}

Moving the block preserves the ID. Copying it creates a new one. Deleting it makes the old address explicitly absent rather than accidentally selecting whatever text now occupies line 42.

Stable IDs also improve audit logs and citations: the same identifier can connect a search result, read response, write operation, change event, and browser highlight.

Make every write conditional on what the agent read

A safe edit begins with a read that returns a version:

GET /v1/documents/doc_123?view=tiptap
ETag: "sha256:abc123"

The write must include that version:

PATCH /v1/documents/doc_123/blocks/block_456
If-Match: "sha256:abc123"
Content-Type: application/json

{"text":"Rollback begins after three minutes."}

If another actor changed the document, the server rejects the request and returns the current version. RFC 9110 defines If-Match specifically for conditional requests and avoiding lost updates.

Do not hide the conflict behind an automatic last-write-wins retry. The agent must reread the new state, reconsider its intended change, and either stop or submit a new proposal.

Keep edits narrow but version the whole document

Block-level operations reduce the mutation surface:

insert after block_A;
replace block_B;
delete block_C;
move block_D under heading block_E.

Yet the precondition should represent the canonical document content, not only the target block. A change elsewhere may alter the meaning of the planned edit. For example, a teammate may add an exception above a policy paragraph without touching the paragraph itself.

Use JSON Patch only when its positional path semantics match the document model. In tree-shaped collaborative documents, domain operations over stable IDs are often clearer than array indexes such as /content/17.

Make batches atomic

Agents frequently perform multi-step changes: create a heading, insert two paragraphs, and update a summary. Applying each request independently can leave half a result when the third operation fails.

Accept an ordered batch under one document version and execute it in one transaction:

{
  "operations": [
    {"op":"insert_after","after":"block_A","block":{"type":"heading","text":"Recovery"}},
    {"op":"insert_after","after":"$0","block":{"type":"paragraph","text":"Restore the latest snapshot."}},
    {"op":"replace","block_id":"block_SUMMARY","text":"Recovery procedure added."}
  ]
}

Either every operation validates and applies, or none does. References such as $0 can target the stable ID allocated by an earlier operation in the same batch.

Design retries before production traffic does it for you

Networks fail after the server commits but before the client receives the response. The agent retries because it cannot know whether the first request succeeded. Without idempotency, “append this checklist” creates two checklists.

Creation and batch endpoints should accept an idempotency key bound to the authenticated actor and normalized request body:

Idempotency-Key: task-8f4a-create-recovery-section

Replaying the same successful request returns the original result. Reusing the key with different input returns an explicit conflict. Failed validation should not become a permanently cached result that blocks a corrected retry.

Separate capability from intent

An agent prompt may say “do not delete,” but the server should not issue delete authority to a workflow that only reads.

Useful scope boundaries include:

documents:read
documents:write
documents:create
documents:delete
sharing:manage
knowledge_bases:admin

Begin with read-only tokens, short lifetimes, and the smallest workspace boundary. Store token hashes, support revocation, and rate-limit write bursts separately from reads.

The MCP tools specification recommends human visibility and the ability to deny tool invocations. Tool annotations can describe read-only or destructive behavior, but enforcement belongs in authentication and authorization, not labels alone.

Return errors an agent can act on

An HTML error page or ambiguous 400 invites guesses. Return stable codes and recovery data:

{
  "error": {
    "code": "version_conflict",
    "message": "Document changed after it was read.",
    "current_version": "sha256:def789",
    "request_id": "req_01K0…"
  }
}

Distinguish at least:

missing precondition;
stale version;
missing scope;
unknown or deleted block;
invalid document structure;
rate limit with retry guidance;
idempotency-key conflict;
incomplete or stale search cursor.

The model may still choose poorly. It should not need to infer the state transition from prose.

Preserve provenance and recovery

Every successful mutation should record actor, token or agent identity, request ID, target blocks, source version, resulting version, timestamp, and origin channel. W3C's PROV overview provides a general model for describing entities, activities, and agents; a document API does not need the full standard to benefit from the same provenance questions.

Snapshots should be taken before consequential writes or at a bounded cadence. Rollback should create a new version rather than erase the history that explains why recovery happened.

Test the hostile cases

A happy-path integration test proves almost nothing. The acceptance suite should include:

two writers using the same initial version;
a block moved between read and write;
a duplicate request after a simulated timeout;
failure in the middle of a five-operation batch;
a read-only token attempting a write;
a write token attempting to manage sharing;
malformed rich-text nodes and duplicate block IDs;
rollback after a valid but unwanted edit;
a search cursor used after the index changes;
1. a retry storm hitting per-document rate limits.

The API is safe only when each failure has a deterministic, observable result.

FAQ

Can an API prevent an agent from writing incorrect information?

Not completely. Structural controls prevent silent corruption and limit blast radius. Factual quality still requires source evidence, review rules, and human judgment for consequential content.

Why not use last-write-wins for simplicity?

Because it makes a successful HTTP response indistinguishable from silent data loss. Explicit conflicts cost an extra read but preserve both actors' work.

Are block IDs enough to make writes safe?

No. They identify targets. Version preconditions, authorization, atomicity, idempotency, validation, audit logs, and recovery address different failure modes.

Should every tool call require human approval?

Not necessarily. Read-only, low-risk operations can run autonomously within a narrow scope. Publication, deletion, permission changes, and ambiguous conflict resolution deserve explicit review.

Bottom line

An unbreakable document API does not promise perfect agent judgment. It makes dangerous state transitions narrow, conditional, atomic, attributable, and reversible. When every stale write fails visibly and every successful edit has a durable address and history, agents can participate without turning collaboration into data-loss roulette.

Originally published on Doco.

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

Why I Moved My Agent Knowledge Base Off Local Markdown

Harry Smart — Tue, 01 Sep 2026 01:32:13 +0000

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:

the agent reads policy.md;
I edit and save policy.md;
the agent writes a complete replacement based on its older read;
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:

Classify the vault. Personal scratch notes stayed local; shared operational knowledge became the migration target.
Import without deleting. The original Markdown remained a rollback source while headings, links, tables, and attachments were checked.
Choose canonical documents. Duplicate policies were resolved before automation could cite them.
Start agents read-only. Search and citations were verified against the browser.
Enable one bounded write. A reversible block update tested identity and version conflicts.
Test export. The exit path was verified before declaring the online workspace authoritative.
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.

Your AI Agent Does Not Need RAG. It Needs a Readable Knowledge Base.

Harry Smart — Sun, 30 Aug 2026 08:51:54 +0000

An AI agent does not automatically need a custom RAG pipeline to use organizational knowledge. If the corpus is maintained, searchable, structurally readable, citable, and available through bounded tools, direct retrieval can be the simpler system. Use RAG when ranking and synthesizing across a large or heterogeneous corpus is genuinely the problem.

Doco series · Article 12 · Architecture opinion

“We need the agent to answer from our documents” often becomes “we need RAG” before anyone writes down the actual job.

That jump confuses a technique with a requirement. Retrieval-augmented generation is a valuable family of architectures. The original RAG paper by Lewis et al. combines a generator's parametric memory with retrieved non-parametric memory for knowledge-intensive tasks. It is especially relevant when the system must rank evidence from a large corpus and generate an answer from it.

But many workplace agents are not open-domain question-answering systems. They need to find a policy, inspect the relevant section, cite it, and sometimes update one paragraph. For that workflow, the first problem is often not model training, embeddings, or chunk orchestration. It is that the knowledge base is difficult for software to read safely.

Start with the job, not the acronym

Consider four requests:

“What is the current refund window? Show me the policy.”
“Update the on-call owner in the release checklist.”
“Compare every customer interview about onboarding confusion.”
“Answer arbitrary questions across ten million mixed-format documents.”

The first request needs search, a canonical source, and a citation. The second needs structured mutation and concurrency protection. The third may benefit from ranking, clustering, or semantic retrieval. The fourth is a strong candidate for a serious retrieval pipeline.

Calling all four “RAG” hides the differences that determine the architecture.

What a readable knowledge base exposes

Readable does not mean “the model can receive a giant Markdown export.” It means the system provides a deliberate set of operations:

Browse: list knowledge bases, folders, documents, and outlines.
Search: find relevant blocks with paths and surrounding context.
Read: request Markdown, plain text, or lossless structured content.
Budget: limit output and continue from an explicit cursor.
Cite: return a stable document and block address.
Check freshness: identify the source and index versions.
Edit safely: patch a bounded unit against the version that was read.

These operations let the agent progressively disclose context. It can inspect an outline before loading a section, and search before reading a whole document. The result is not magical retrieval. It is a knowledge interface whose behavior can be tested.

Doco is the system I am building, so this is a first-party architecture argument. Doco currently uses structured full-text search rather than claiming universal semantic search. SQLite's official FTS5 documentation describes a full-text search virtual table with phrase, prefix, NEAR, and boolean query support. That kind of retrieval is often enough for known policies, identifiers, names, and operational terms.

Chunking is not neutral

A typical RAG pipeline copies source documents, divides them into chunks, embeds those chunks, and builds a retrieval index. Each step introduces a projection that can drift from the source:

a heading may be separated from the paragraph it qualifies;
a table row may lose its headers;
a chunk ID may change after a small source edit;
the index may lag behind the document;
a generated answer may cite a chunk that has no durable user-facing address.

Those are solvable engineering problems. They are still problems. If the source system already has stable blocks, heading paths, versions, and search, preserve those semantics before inventing another identity layer.

Direct retrieval is not “stuff everything into context”

The alternative to RAG is not a 200,000-token dump. A tool-using agent can follow a staged loop:

list → inspect outline → search → read relevant blocks → verify source → answer

The Model Context Protocol separates resources and tools so a server can expose contextual data and executable operations through a negotiated interface; see the MCP server concepts. That makes direct, structured retrieval portable across agent clients without requiring the knowledge base to pretend it is a chat model.

The agent should also know when the result is incomplete. “No match in the first page” must not become “the knowledge base contains no answer.” Search cursors, completeness flags, and index freshness are mundane metadata with large reliability consequences.

When RAG is the right choice

Use RAG—or another dedicated retrieval architecture—when one or more of these conditions dominate:

the corpus is too large for deterministic browsing and lexical search alone;
users ask broad natural-language questions with weak keyword overlap;
evidence comes from heterogeneous external sources without shared structure;
ranking quality is a core product capability worth evaluating continuously;
the system must synthesize several passages for every answer;
you can operate ingestion, deduplication, access control, freshness, and retrieval evaluation as real production systems.

Even then, RAG does not replace a readable source of truth. It becomes a projection over that source. Every retrieved passage should retain enough provenance to reach the authoritative document.

When direct knowledge tools are enough

A simpler tool layer is often sufficient when:

the corpus is a bounded team workspace;
documents have useful titles, headings, and stable structure;
queries contain operational vocabulary found in the source;
the agent must cite or edit the exact source;
freshness matters more than fuzzy recall;
the team values debuggable behavior over opaque ranking.

For example, an incident assistant looking up “payments rollback timeout” may perform better with full-text search over current runbooks than with a complex semantic stack that was indexed yesterday. The important comparison is empirical: measure whether the correct source block is found, whether its version is current, and whether the answer cites it.

The architecture can grow incrementally

Starting with a readable knowledge base does not prevent semantic retrieval later. It creates a better foundation for it.

Make canonical documents structurally accessible.
Add stable block IDs and source versions.
Implement deterministic search with complete, testable results.
Record real queries that deterministic retrieval misses.
Add semantic ranking where those failures justify it.
Keep citations bound to the canonical blocks, not only vector-store chunks.

This sequence turns RAG from a fashionable default into a targeted response to measured retrieval failures.

FAQ

Is this an argument against RAG?

No. RAG is useful for knowledge-intensive generation, especially across large or heterogeneous corpora. The argument is against treating it as the automatic first requirement for every agent that needs documents.

Is full-text search enough for every knowledge base?

No. It can miss paraphrases and concepts that share little vocabulary. It is strong for names, identifiers, policies, and operational phrases. Evaluate it against real queries before adding or rejecting semantic retrieval.

Can an agent use both direct tools and RAG?

Yes. A semantic retriever can identify candidate blocks, while direct tools fetch current canonical content, versions, and surrounding structure. The two layers should not create competing sources of truth.

What should I measure before building RAG?

Measure source-block recall, citation correctness, freshness, incomplete-search handling, latency, and the share of real queries that simpler retrieval cannot answer. Those results reveal whether the bottleneck is retrieval, document quality, or workflow design.

Bottom line

Your agent needs a dependable way to find, read, cite, and sometimes update knowledge. RAG may be part of that system, but it is not the definition of it. Build a readable source of truth first; add specialized retrieval when evidence shows that you need it.

Originally published on Doco.

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

Give Claude Code a Knowledge Base It Can Actually Edit

Harry Smart — Sun, 30 Aug 2026 08:51:52 +0000

Give Claude Code an editable knowledge base by connecting a narrowly scoped MCP server that exposes structured search, versioned reads, and block-level writes. Start read-only, verify citations, then grant write access only after stale writes fail safely and every change remains visible to humans.

Doco series · Article 11 · Claude Code tutorial

Claude Code can already read files in a repository. That is enough for source code and temporary project notes. It is not enough when the source of truth is a living team handbook, product specification, or research library that people are editing in a browser at the same time.

The missing piece is not “more context.” It is a reliable boundary between Claude Code and maintained knowledge.

What “actually edit” means

An agent can technically edit a knowledge base if it can overwrite a file or call a generic update endpoint. A useful editing contract is stricter:

search should return evidence, not only generated answers;
a paragraph should keep the same address when it moves;
a read should identify the document version it observed;
a write based on an old version should fail visibly;
a small change should not require replacing the entire document;
a person watching the document should see the same state;
permissions should separate reading from writing.

Claude Code uses the Model Context Protocol to connect to external tools and data sources. Anthropic recommends HTTP for remote services and stdio for local processes. MCP provides the connection; the quality of the knowledge contract still depends on the server behind it.

Step 1: connect Doco in read-only mode

Doco is the product I am building, so treat the recommendation here as a first-party tutorial rather than an independent comparison. It is MIT licensed, and its relevant distinction is that browser users and API clients operate on the same collaborative documents.

For the hosted MCP endpoint, create a Doco token with read scopes only, then add it to Claude Code:

claude mcp add --transport http doco https://api.doco.page/mcp \
  --header "Authorization: Bearer YOUR_DOCO_TOKEN"

For a local stdio connection:

claude mcp add doco -- npx -y --package doco-agent-cli doco mcp

Keep the token outside committed configuration. Claude Code supports environment-variable expansion in project-scoped .mcp.json files, so a shared configuration can reference a local secret without storing it in Git.

Run claude mcp list, then open /mcp inside Claude Code. Confirm that the Doco server is connected and inspect the tools before asking the model to use them. The official Claude Code documentation also warns that servers which fetch external content can expose clients to prompt injection; knowledge-base text is data, not trusted instruction.

Step 2: prove retrieval before enabling writes

Use a question whose answer you already know:

Search Doco for the release rollback procedure. Return the document title,
heading path, stable block ID, and the exact evidence you relied on.
Do not modify anything.

The goal is not a polished summary. You are checking the retrieval contract:

Did Claude search the intended knowledge base?
Did it land on a relevant block rather than dump a whole document?
Can you open the cited document and verify the evidence?
Does the result disclose incomplete or stale search state?

This matters because a confident answer without an address is hard to audit. A useful knowledge tool should let the agent browse structure, search to a block, and read enough surrounding context to interpret it.

Step 3: perform one bounded edit

After read-only retrieval is dependable, create a token with the minimum write scope needed for the test. Choose a disposable document or a clearly reversible paragraph.

Ask Claude to follow an explicit read-edit-verify loop:

Open the document “Release checklist.” Read the block under “Rollback owner.”
Change only that block to add the on-call alias. Preserve the rest of the
document. If the version changed after your read, stop and show the conflict.
Then read the block again and report its stable ID and resulting version.

In Doco, reads expose a version fingerprint and protected writes use an If-Match-style precondition. That follows the lost-update protection described by RFC 9110: a state-changing request proceeds only when the selected representation still matches the condition supplied by the caller.

The version check is the important part. Without it, an agent can read version A, a teammate can create version B, and the agent can silently write an update based on A over B.

Step 4: watch the same edit in the browser

Open the target document before running the edit. The changed block should update in the collaborative editor because the API and browser share the same Yjs document state. Yjs describes shared editing as peers exchanging document updates that merge without a central ordering assumption; see its collaborative editor guide.

This check catches a common integration failure: the agent updates a shadow database or exported file while the human-facing workspace continues to show something else.

Step 5: test the failure path on purpose

A safe demo must include a conflict, not only a successful write.

Have Claude read a block and retain its version.
Change the same document in the browser.
Ask Claude to submit the original planned write.
Confirm that the server rejects the stale precondition.
Let Claude reread, explain the difference, and propose a new edit.

Do not automatically retry semantic conflicts. A retry is safe only after the caller has incorporated the newer state. “Last writer wins” is convenient until the last writer is an unattended agent.

A production-ready prompt pattern

The prompt below is deliberately procedural:

Search the Doco knowledge base for the current API deprecation policy.
Use source blocks, not generated summaries, as authority.
If you find conflicting policies, cite both and stop.
Otherwise update only the “Timeline” block in the canonical policy document.
Do not write without a version precondition. If the version is stale, do not
retry automatically. Report the document URL, changed block ID, and new version.

The prompt does not create safety by itself. It tells Claude how to use safety properties enforced by the server.

Permission and review checklist

Begin with documents:read; do not issue a broad write token for exploration.
Scope the token to the smallest knowledge base and lifetime available.
Review the server's tools before approving them. The MCP specification says tools are model-controlled and recommends a human in the loop who can deny invocations; see the MCP tools specification.
Require explicit confirmation for publication, permission changes, deletion, and other consequential actions.
Preserve an audit record containing the actor, target block, source version, and result.
Revoke test tokens when the integration is no longer in use.

FAQ

Can Claude Code edit a normal Markdown knowledge base?

Yes. It can edit files it is allowed to access. That is appropriate when the file is the source of truth and Git-style review is the intended collaboration model. A shared live knowledge base needs additional identity, concurrency, and permission semantics.

Do I need MCP to connect Claude Code to knowledge?

No. A CLI or direct API can work. MCP is useful when you want discoverable tools, resources, authentication, and a reusable connection inside Claude Code.

Should I give Claude Code a write token immediately?

No. Prove search, evidence, and citations with a read-only token first. Add narrow write scope for a reversible test, then verify both a successful update and a stale-write rejection.

What makes a block-level edit safer than replacing a document?

It limits the mutation surface and gives the changed paragraph a durable address. Document-level version protection is still required because other blocks may have changed since the agent read the document.

Bottom line

Connecting Claude Code is the easy part. The real acceptance test is whether it can find evidence, edit one stable block, lose a race safely, and show the same result to a human in the browser. If those properties hold, the knowledge base is not merely readable by an agent—it is maintainable by one.

Originally published on Doco.

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

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

Designing a Document API That AI Agents Cannot Break

Define “break” before defining endpoints

Give every editable block a stable identity

Make every write conditional on what the agent read

Keep edits narrow but version the whole document

Make batches atomic

Design retries before production traffic does it for you

Separate capability from intent

Return errors an agent can act on

Preserve provenance and recovery

Test the hostile cases

FAQ

Can an API prevent an agent from writing incorrect information?

Why not use last-write-wins for simplicity?

Are block IDs enough to make writes safe?

Should every tool call require human approval?

Bottom line

Why I Moved My Agent Knowledge Base Off Local Markdown

The first warning was copy ambiguity

The second warning was paragraph identity

The third warning was the read-write race

The fourth warning was permissions

What I kept from Markdown

A migration path that did not require a big bang

When I would stay with local Markdown

FAQ

Did you stop using Markdown?

Is Git a bad collaboration system for documents?

Does moving online sacrifice ownership?

Should every personal note move to an online knowledge base?

Bottom line

Your AI Agent Does Not Need RAG. It Needs a Readable Knowledge Base.

Start with the job, not the acronym

What a readable knowledge base exposes

Chunking is not neutral

Direct retrieval is not “stuff everything into context”

When RAG is the right choice

When direct knowledge tools are enough

The architecture can grow incrementally

FAQ

Is this an argument against RAG?

Is full-text search enough for every knowledge base?

Can an agent use both direct tools and RAG?

What should I measure before building RAG?

Bottom line

Give Claude Code a Knowledge Base It Can Actually Edit

What “actually edit” means

Step 1: connect Doco in read-only mode

Step 2: prove retrieval before enabling writes

Step 3: perform one bounded edit

Step 4: watch the same edit in the browser

Step 5: test the failure path on purpose

A production-ready prompt pattern

Permission and review checklist

FAQ

Can Claude Code edit a normal Markdown knowledge base?

Do I need MCP to connect Claude Code to knowledge?

Should I give Claude Code a write token immediately?

What makes a block-level edit safer than replacing a document?

Bottom line

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