soul.demarkus.io:6309/vision.md/v5 draft reader meta

Vision: live, reactive knowledge

The north star for demarkus and the knowledge system: what the end state is, why it is new, how the pieces fit into three layers, and the order of work that gets there. Audience: Fritz and anyone deciding what demarkus builds next. Written 2026-09-25; the plans it links carry the detail.

The end state

Knowledge that knows when it is stale.

demarkus is the shared, live, versioned memory for people and agents. Every document has a stable address, an immutable history, and provenance. Documents link to each other with typed relations. When a document changes, everything that depends on it finds out within a latency budget: the agents that cited it, the summaries built from it, the caches holding it, and the people reading it.

The test for any proposal comes from Information Management as the core principle: does it make knowledge more linked, more findable, more durable? This vision adds a fourth word: more current.

What is new here

Each neighbor has part of it and none has all of it:

System Has Lacks
git History, content addressing Live changes, per-document network addresses, a catalog, agent-native access
Wikis and document tools Human editing, links A protocol, provenance per claim, agent-native access
Vector memory for agents Retrieval Auditability, provenance, human-readable storage
Message buses Live delivery Durable, addressable, versioned content

The combination demarkus offers is provenance plus live change plus typed links. That combination is what makes knowledge reactive.

Reactive knowledge

What becomes possible once changes propagate and links carry meaning:

  • Citations become subscriptions. A document or agent that links to or declares a rel-* relation to a source watches it. Superseding an ADR notifies everything that depends on it.
  • Derived documents track their sources, like a build system. Hubs, summaries, indexes, and graph.md record what they were built from; a change to a source marks them stale or rebuilds them. ADR 0013 (graph source freshness) and the generation package are early forms.
  • The organization's current beliefs can be queried and watched. superseded-by, valid-from and valid-until, and live LOOKUP over decisions answer "what do we believe now, and tell me when it changes."
  • Agents coordinate on the documents themselves. Mailboxes, claims by expected version, and handoffs leave a versioned, attributed record. The conversation is the record.
  • Trust crosses organizations. Client-verifiable history plus content addressing lets one organization rely on another's knowledge without trusting its server.

Three layers

Each layer has one rule. Nothing moves down a layer without an ADR.

Layer Rule Contents
Durable core Stays dumb. Stores, versions, catalogs, and announces changes as hints. Protocol and SPEC, stores, WATCH hints, replica commit hints, protocol version in ALPN
Live layer Changes propagate within a latency budget. QUIC, the QUIC broker with fan-out and content cache, the client SDK, 0-RTT, UDP 443
Reactive layer Links and provenance drive staleness, rebuilding, and coordination, at the edge. client/live, agents and skills, the HTTPS adapter, the library

The durable core test still governs the bottom layer: would this matter if every product on top were thrown away tomorrow? The live and reactive layers are products; they can be rebuilt, the core cannot.

Architecture at the end state

  • Worlds hold knowledge, fenced inside the network on 6309, and send hints only.
  • The QUIC broker on UDP 443 is the one broker that does the work: identity, tenancy, routing, fan-out, content cache, mark and h3 on one listener.
  • The HTTPS adapter on TCP 443 translates for clients that need TCP and HTTP: hosted MCP platforms, UDP-blocked enterprises, OAuth web login. It is deleted once those clients reach QUIC.
  • The client SDK is how every application, CLI, MCP bridge, and the library speak to demarkus.
  • Souls stay local, personal, and promote into the knowledge system.

Details: Lean into QUIC, Realtime demarkus, demarkus-sdk.

Order of work

The 1.0 feature freeze was lifted on 2026-09-25 (1.0 plan). The live layer proceeds alongside the 1.0 workstreams instead of after them.

Track Contents
1.0 stability The 1.0 plan's remaining workstreams: quality gate, one vocabulary, reduced surface, protocol final.
Live, now QUIC measurement baseline on the benchmarks branch; SDK extraction; WATCH and replica push; ALPN mark/1; then the QUIC broker with fan-out, 0-RTT, and UDP 443.
Reactive, next Dependency subscriptions, derived documents that know they are stale, watchable beliefs, client/live in every surface, the HTTPS broker reduced to an adapter.
Later Verifiable federation across organizations, the pure-QUIC profile as a default, the adapter phase-out, level 3 collaboration as a separate room service.

Within the live track the order is fixed by dependencies: SDK before the client side of WATCH, WATCH before the QUIC broker's fan-out, the auth-model ADR before the QUIC broker.

The live track started on 2026-09-27: ADR 0026 (SDK phase 0), realtime PR 1 (client error classification) and PR 2 (ADR 0025, SPEC §6.8, the WATCH codec) are on branch feat/live-track-front awaiting review.

Tensions to settle

  • When the protocol freezes. Settled 2026-09-27 in ADR 0025, proposed: protocol 1.0 freezes after WATCH and ALPN mark/1 land, so the spec is not frozen and extended in the same cycle.
  • Lockstep versions and the SDK. Settled 2026-09-27 in ADR 0026, proposed: the SDK has its own semver in its own repo, v0 until WATCH ships, v1 after; the lockstep (W2) covers the monorepo modules only, and core 1.0 pins an SDK v1.
  • Subscriptions and "no sessions". A watch looks like a session. It stays defensible only while events are hints, subscribers hold no durable server state, and overload degrades to resync. ADR 0025 says so.
  • Surface count. Knowledge broker, memory broker, QUIC broker, several plugins, the library, the TUI. Convergence on the QUIC broker helps; the ecosystem plan's budgets and default-surface rule still apply to everything the new plans expose.
  • Measurement may say no. If the QUIC baseline shows no gain on most hops, the live layer still ships, and a TLS on TCP binding for direct clients becomes the honest answer.

What this vision rules out

  • Full-text or semantic search in the server. It stays a sidecar that reads over LIST and FETCH.
  • Graphs as the primary store. Markdown is primary; graphs are derived.
  • Application features that cannot be expressed as documents and links: forms, sessions beyond watches, RPC endpoints.
  • Chat through the store. Documents are for durable coordination.
trail
  1. soul.demarkus.io:6309 v5