OpenKnowledge surfaced on Hacker News as an open-source, AI-first alternative to Obsidian and Notion — markdown-native editing, real-time collaboration, Git integration, and built-in hooks for Claude, Codex, and Cursor. Whether it becomes a mainstream tool is uncertain. The architecture choices are a useful snapshot of how teams design AI-native knowledge systems in 2026.
This article walks the technical stack — ProseMirror, yjs CRDTs, dual observers, Git-backed sync — and what those choices imply for builders shipping collaborative docs with agent integration.
Markdown as source of truth, rich text as editing surface
OpenKnowledge stores content as markdown files on disk — compatible with git workflows, static site generators, and portability. The editor uses ProseMirror for WYSIWYG editing, maintaining an abstract syntax tree (AST) that round-trips to markdown.
The split is deliberate. Plain markdown files are diff-friendly and tool-agnostic. ProseMirror gives non-technical users formatting without learning syntax. The cost is sync complexity: every keystroke mutates the AST, which must serialize back to markdown without corrupting structure.
Think of markdown as the archival format and ProseMirror as the lens you view it through — like reading sheet music while performing from a annotated score. Both must stay aligned.
CRDT sync with yjs
Real-time collaboration uses yjs, a conflict-free replicated data type (CRDT) library. Multiple clients edit concurrently; yjs merges changes without a central lock. Offline edits reconcile when connectivity returns.
CRDTs trade server simplicity for mathematical merge guarantees — unlike operational transform systems that require a single ordering authority. For docs tools, CRDTs fit local-first and peer-to-peer ambitions.
OpenKnowledge uses a dual-observer pattern: one observer tracks ProseMirror document changes into yjs; another propagates yjs updates back to ProseMirror. Keeping those observers consistent is where most bugs live — cursor jumps, duplicate paragraphs, lost formatting.
Collaborative editing bugs feel like data loss to users even when no bytes disappeared — CRDT wiring is product-critical infrastructure.
Git as collaboration layer
Beyond live CRDT sync, OpenKnowledge integrates Git for version history, branching metaphors, and async collaboration — commit, push, pull on a knowledge base the way developers do on code.
Combining CRDT live editing with Git async workflow is ambitious. CRDT handles milliseconds-scale conflicts; Git handles day-scale review and rollback. Teams that already live in git-backed docs (Obsidian vaults in repos, MDX content repos) get familiar semantics. Teams expecting pure Notion-style cloud-only may find Git friction surprising.
AI-native integration
The project advertises native integration with Claude, Codex, and Cursor — agents that read and write vault content through defined hooks rather than copy-paste into chat windows.
AI-native docs tools typically need:
- Stable file paths — agents reference documents predictably.
- AST or markdown export — models ingest text without editor binary formats.
- Permission boundaries — which folders an agent may write, parallel to sandbox patterns elsewhere.
- Diff visibility — human review before agent commits land on shared branches.
OpenKnowledge positions itself where note-taking, team wikis, and coding agents overlap — a crowded space, but the integration point is real: engineers want agents that edit the same markdown repo the site builds from.
| Layer | Choice | Trade-off |
|---|---|---|
| Storage | Markdown on disk | Portable; sync/schema hard |
| Editor | ProseMirror | Rich UX; AST sync complexity |
| Live collab | yjs CRDT | Offline-friendly; observer bugs |
| Async collab | Git | Familiar to devs; steep for others |
| AI | Agent hooks | Powerful; needs write governance |
What this means for builders
Pick one source of truth format early. Markdown-on-disk scales to git and static sites; proprietary JSON blocks portability.
Budget engineering for CRDT ↔ editor bridges. The hard part of collaborative editors is not yjs itself — it is keeping ProseMirror (or Slate, or Lexical) in bidirectional sync without cursor bugs.
Treat agent write access as a sandbox problem. Hooks into Claude or Cursor need path allow-lists and review flows, not full vault write by default.
Combine live and async sync deliberately. CRDT for presence editing, Git for review — document which mode users should expect when.
Evaluate AI-native claims on write governance. Reading docs into a chat is solved; safely writing back at team scale is not.
Conclusion
OpenKnowledge bundles patterns emerging across the stack: markdown portability, CRDT collaboration, git semantics, and agent hooks in one open-source package. The individual pieces are established; the integration is the product bet. For builders, the takeaway is architectural — AI-native knowledge tools are document systems first and chat wrappers second. Get sync, AST round-tripping, and write permissions right; model integration becomes a feature. Get them wrong; no model quality rescues the UX.