Commonfold
A private knowledge system where capture is reviewed before write, answers retain source receipts, and realtime collaboration never replaces recoverable Markdown.01
One note, three accountable paths.
Follow a synthetic note through the implemented boundaries that review what enters the archive, expose what informed an answer, and keep collaboration secondary to a recoverable Markdown record.
The model proposes. The person decides what becomes structure.
The planner may capture, skip, or ask; a capture is still only a draft. New types, folders, updates, tags, and unresolved wikilinks stay visible until review.
agent/ingest.ts · ingest/review.tsRemember that every published image needs a rights status.one field · conversation context available
- Operation
- append to existing note
- Type
reference· existing vocabulary- Folder
Publishing· existing path- Markdown addition
- Every published image needs a [[Rights status]].
- Planner outcomes
- capture · skip · ask
- Write operations
- create · update
- Concurrency guard
- target updated-at checkpoint
Implementation trace verified against the current Commonfold schema, ingest planner and review types, keyword and vector retrieval, answer grounding, collaborative editor, version restoration, and vault import/export. Demonstration content is synthetic; no private archive was queried.
Proposition
Commonfold is a private knowledge system built around one entry point. A thought can become a reviewed capture; a question can become a source-linked answer. Neither path hides the records or decisions underneath it.
Architecture
The current product uses Next.js 16 and React 19, Neon Postgres with pgvector and Drizzle, Claude for ingest planning and answers, OpenAI embeddings for semantic retrieval, Clerk identity, Liveblocks and Yjs for collaborative state, and TipTap with a Markdown source mode. Private content is scoped directly, or through its owning note or session, to an active space.
A single notes table stores Markdown, folder, metadata, and a type drawn from the space’s vocabulary. Wikilinks are extracted into queryable rows; 1,536-dimension chunks feed an HNSW cosine index. Keyword and semantic results are merged before the answer model sees them, and every returned source retains a route back to its note, conversation, or thread.
Load-bearing decisions
- Every durable knowledge object has a note representation; adjacent tables handle identities, membership, messages, and high-mutation state.
- Capture can return skip, ask, or a create/update proposal; new types, folders, and unresolved entities remain reviewable before persistence.
- Entity resolution is a user decision: create a typed entity, link an existing note, or keep the phrase as text.
- Postgres is canonical. Yjs carries concurrent editor state but transient empty room state is prevented from overwriting a populated server copy.
- Version checkpoints attribute changes to a user, AI agent, or system operation and retain the instruction behind an AI-authored revision.
- Export reconstructs folders, frontmatter, tags, and wikilinks as a round-trippable Obsidian-compatible Markdown vault.
Privacy boundary
The public site describes the system, not the contents of a private archive. It never queries a Commonfold vault or uses private notes as evidence.
Reflection
The hard part is not generating an answer. It is keeping capture reversible, retrieval attributable, collaborative edits recoverable, and the archive useful outside the product that created it. Those constraints shape the database, review interface, answer prompt, version history, and export format together.
Design and implementation
- Visual decision
- A single synthetic note moves through review, retrieval, and durable-state views. The instrument exposes the implemented contracts instead of imitating the private application or turning architecture into decorative boxes.
- Access decision
- The three lifecycle views use an accessible tab pattern with arrow-key navigation and breakpoint-aware orientation. Every path has a complete text reading order; motion only reinforces state transfer.
- Delivery constraint
- The example is authored from repository schemas and services, runs as static HTML, CSS, and a small tab controller, and makes no request to the authenticated product. No private note, source row, room, or identity is loaded.