Doco Popular Science Series · Part 2
For many people, the journey of knowledge management begins with the same action: installing Obsidian, creating a few folders, and writing the first Markdown note.
Six months later, the library contains hundreds of .md files, tags nested within tags, bidirectional links connecting to bidirectional links, and a sense of solid accomplishment.
Until one day, three small issues occurred in succession:
Wanting to look up a conclusion you wrote while on the subway, you pull out your phone and realize the library is on your PC's hard drive;
Switching to a new computer and wanting to continue using this library—the official sync works, but it's file-based sync, not real-time, and simultaneous edits on two devices can create conflicting copies;
Wanting an Agent to help search and organize this library, but it's sitting in a folder on another computer
None of these issues are major on their own, but they point to the same problem: a local Markdown knowledge base is ultimately "your computer's knowledge base"—device-dependent, file-based, and the only interfaces the filesystem provides to humans and Agents are grep and head.
This piece aims to seriously discuss: if the goal of maintaining a knowledge base isn't just taking notes, but enabling you and your Agent to search, modify, and reference it together—then why a cloud-hosted, text-block-based knowledge base managed centrally is a more suitable foundation.
First, let's clarify: notes are written for yourself, but a knowledge base is built for "yourself and your Agent" to use
Notes are primarily written for your future self. As long as you can find them, a slightly messy structure is fine—plain text, fully controllable, offline-accessible, with a thriving plugin ecosystem. Obsidian has polished the experience well.
Knowledge bases are different. The value of a knowledge base occurs at the moment it is used by someone "outside of itself." And right now, that user is often not a colleague, but an Agent:
When an Agent answers questions, it cites from it and provides sources;
When an Agent executes tasks, it relies on it and keeps up with its updates;
An Agent helps maintain it, supplementing conclusions and cleaning up outdated content.
Of course, knowledge bases will be used by more people in the future, but before that step arrives, the first real collaboration is between you and the Agent. When the user changes, the requirements change. The difficulties of local Markdown emerge one by one right here.
Difficulty 1: Knowledge is locked inside a single device
A knowledge base shouldn't depend on any single device, but local Markdown libraries happen to live on one hard drive. To work across devices, you first need to solve synchronization:
Using official sync (like Obsidian Sync) or cloud storage—workable, but sync is file-based: not timely enough, if two devices edit simultaneously, you get two conflicting copies that need manual merging;
Using git push/pull—a good habit for engineers, but still file-based, even more cumbersome than sync;
Exporting as a file and sending it out—the moment it's sent, it stops updating, and what the recipient gets is the old version from then on.
Mobile phones are more like second-class citizens: mobile editors can open files, but they only open "that synced file," which has little to do with the structure and search of the entire library.
When knowledge is tied to a single device, usage is limited to that device. A more natural form would be the reverse: the library is managed centrally in the cloud, and devices are just windows.
Challenge 2: The unit of management is the file, not knowledge
The unit managed by a file system is the file. But the unit of knowledge is rarely exactly "one file":
The conclusion you want to cite is a paragraph in a document;
The content the Agent wants to modify is a sentence in a section;
What actually becomes outdated is often a single number, not the entire document.
Under the file unit, all paragraph-level operations degrade to file-level operations:
To modify a single sentence, the Agent has to read the entire file back and write it back;
To cite a passage, you can only say "in that file";
Files have paths, but paragraphs have no addresses—once the content is rewritten, no one knows if it's still the original passage.
In local Markdown, knowledge has no stable address at the paragraph level. Without addresses, citations are unreliable, and the Agent cannot precisely "modify only this paragraph"—it can't even verify "I clearly saw this sentence somewhere."
Challenge 3: What the file system can offer is only grep and head
When the knowledge base grows large, daily use condenses into a single action: search. When an Agent accesses a local repository, the search tools the file system can provide are basically just grep and head:
grep -rn "发布窗口" ~/notes # 哪些文件里出现了这个词
head -n 50 ~/notes/运维/发布.md # 读开头 50 行，猜猜内容grep is fast, but all it can answer is "these characters appear in these files." What the Agent truly needs after searching is a more complete set of answers:
命中的是哪篇文档？
它在哪个目录下面？
全篇结构是怎样？
对应的文本块在哪里？head is even more limited: it can only read the beginning of a file. To understand a long document, the Agent has no choice but to read the entire thing—this is how context gets burned.
Beyond search, there's also a missing layer of "map." An experienced colleague taking over new business would first look at the directory structure and document summaries to understand what's in the repository before deciding where to dive deeper; the same applies to Agents. But file systems have no summaries and no directory overviews, so the Agent can only flip through file by file—this is also why "the Agent flipping through the entire knowledge base" is becoming increasingly common.
What's lacking isn't computing power, but a knowledge-level capability built on top of the storage format: global search that drills down to paragraphs, summaries that provide a map, and directories that let the Agent see the structure before the content. These are capabilities the file system simply cannot natively provide.
Challenge 4: When you and the Agent modify the same passage simultaneously
Local files are inherently "one person at a time": whoever opens it modifies it. But once an Agent enters the repository, this assumption immediately fails—Agents don't rest, and you and the Agent maintaining the same repository simultaneously will become the norm.
At this point, the protection the file system can offer is practically none:
The Agent reads the entire file, modifies it, and writes it back—your changes made in between get silently overwritten;
The file system doesn't record "who modified which passage," and there's no rollback—by the time the problem is discovered, it's already too late to go back;
Even the best sync tools only generate two "conflicting copies," leaving it to you to manually merge them someday.
"Who modified which passage, and based on which version"—these two questions, the file system can never answer.
What does a knowledge base that lives online and is managed at the block level look like
Put knowledge into an online knowledge base, and the four difficulties above will be addressed one by one. Taking Doco as an example:
1. The library is in the cloud, devices are just windows. Knowledge lives on the web, managed centrally: you write halfway on your computer, open it on your phone to continue; switch to a new computer, log in and you're still there. Synchronization happens at the block level, arriving in milliseconds, with no conflicting copies to merge.
2. The unit of management is text blocks, not files. Each heading, paragraph, and list item is a block with a stable ID: addresses are independent of location, and references remain valid after dragging and rearranging; when an Agent modifies a single sentence, the impact is confined to that one block without affecting the entire document.
3. Search, summarization, and tables of contents are services built on blocks. Full-text search is server-side, with hits landing on blocks: which document, under which heading, what the surrounding context is—all accessible with one click from the results; summaries provide a map of the entire library and each document; tables of contents and outlines let Agents see the structure first, then read the content. What Agents get is no longer just grep + head, but the same search, summarization, and outlining capabilities as humans.
4. When you and an Agent write simultaneously, conflicts never happen silently. Reads carry version fingerprints, and writes with mismatched versions immediately report conflicts—never silently overwriting; modifications land on blocks, so the scope of impact is traceable, and if you make a mistake, version snapshots are available for rollback.
5. Agents are first-class citizens. MCP, CLI, and REST API share the same contract: Agents enter the library with tokens, operate within their permissions, and every write has a version basis—traceable and rollbackable.
The three old sayings from this series fit perfectly here:
Findable: search, summaries, and tables of contents replace 'searching the entire library,' eliminating the need to cram the whole knowledge base into context;
Explainable: answers can trace back to specific documents and specific blocks;
Unbreakable: version conflicts are explicitly surfaced, no silent overwrites allowed.
Local Markdown still has value
I need to be clear here: this is not an attack on Obsidian.
Speed is Local Markdown's greatest advantage: zero-latency local read/write, no network dependency, fully controllable, and plain text never expires. This makes it especially well-suited for one phase—drafting. When ideas first emerge and the structure isn't yet settled, you can jot them down freely in a local editor without worrying about structure or where to place them.
But once a draft takes shape and enters the iterative revision phase, it should be moved online:
Millisecond-level sync across devices: write halfway on your computer, open it on your phone to continue, always with just one up-to-date library;
Nothing gets lost, and there's no need to resolve merge conflicts—the cloud holds only one authoritative version, with no such thing as 'conflicting copies';
No need to worry about 'finished editing on the computer last night, but it didn't sync after shutting down'—the library in the cloud is always up-to-date, available whenever you open it.
This is especially crucial when collaborating with an Agent: any casual edits you make will be the latest changes the Agent reads on its next visit to the library; paragraphs the Agent has modified are visible to you whenever you open the document. You're always working from the same latest version.
Online solutions come with their own costs: dependency on network and services, requiring trust in the operator. Doco's answer is no lock-in: single-document and full-library ZIP exports in Markdown, plus Word and PDF export—all open. Your knowledge can be taken away in full at any time. Offline editing isn't affected either; the browser has local caching, and differences are automatically merged once connectivity is restored.
What's truly changing is Markdown's role: from 'storage format' to 'exchange format'.
Locally, Markdown is home for drafts; in an online knowledge base, Markdown is what knowledge looks like when it goes out and comes in—always portable, but the library itself grows in a structured, versioned, and addressable way.
How to choose? A simple decision line
Writing first drafts, jotting down inspiration → Local Markdown is fastest and most convenient;
When content enters the iterative revision phase, needs to be continued across devices, or needs to be handed to an Agent for retrieval, citation, and modification → Upload it online, let it grow in the cloud, managed by blocks.
The difference between notes and a knowledge base has never been about format, but about what stage the content is in: drafts stay local for speed; knowledge that needs iterative revision, cross-device access, or Agent read-write operations should grow in the cloud, managed by blocks.
Don't let knowledge get locked in one device or a pile of files; let it grow in the cloud, managed by blocks, so both you and the Agent can truly use it.