GitHub as Source of Truth, CRDT as Working Memory

2026-02-25·https://github.com/emotion-machine-org/with-md/tree/main

repomarkdowncollaborationaiagentstypescriptnextjsconvexyjsvaultmemoryagent-loops

Pattern maps directly to Vault-first agent loops: keep Git-tracked Markdown canonical while using CRDT state as transient multi-agent working memory.

with.md (repo) is a Markdown collaboration system that keeps files in GitHub and treats that repo state as canonical. The app stack—Next.js, Convex, and Hocuspocus over Yjs—is familiar, but the framing is the useful part: real-time collaboration without creating a proprietary document format.

The clever move is the explicit split between durable content and live session state. Raw .md stays portable in Git, while binary Yjs snapshots preserve cursor/undo collaboration context. They also add defensive rails: TipTap syntax gating when round-tripping could corrupt content, oversized-doc fallback to source mode, content-loss shrink guards, and multi-strategy anchor recovery for comments. That’s a pragmatic “don’t lose user data” posture instead of editor magic.

For joelclaw this is relevant to Vault workflows and multi-agent editing patterns: Git-native artifacts plus CRDT-native collaboration is a clean model for notes, playbooks, and generated drafts. It lines up with the operating model behind /system and event traces in /system/events: durable source, observable transient execution.

Key Ideas

GitHub can be the canonical datastore for collaborative docs if local-first sync is handled by CRDT state (Yjs).
Dual persistence (raw Markdown + binary Yjs) separates portability from collaboration ergonomics.
TipTap mode gating based on unsupported syntax is a strong anti-corruption pattern for rich-text editors.
Comment anchors that combine text quotes, context windows, heading paths, and line fallback are more resilient than naive offsets.
Size limits and shrink guards are practical safety valves for agent-assisted or multi-user editing systems.

Key Ideas

Links