# 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](/thoughts.md#on-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](/plans/durable-core.md) 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](/plans/quic-first.md), [Realtime demarkus](/plans/watch-agent-messaging.md), [demarkus-sdk](/plans/demarkus-sdk.md).

## Order of work

The 1.0 feature freeze was lifted on 2026-09-25 ([1.0 plan](/plans/v1.md#feature-freeze-lifted)). 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](/adr/0026-client-sdk-mit-server-never-imports.md) (SDK phase 0), realtime PR 1 (client error classification) and PR 2 ([ADR 0025](/adr/0025-watch-verb.md), SPEC §6.8, the WATCH codec) are on branches awaiting review.

## Tensions to settle

- **When the protocol freezes.** Settled 2026-09-27 in [ADR 0025](/adr/0025-watch-verb.md), 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](/adr/0026-client-sdk-mit-server-never-imports.md), 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, Obsidian. 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.

## Related documents

- [Fortify the durable core](/plans/durable-core.md): what must outlive every product
- [demarkus 1.0](/plans/v1.md): the definition of 1.0 and its decisions
- [Ecosystem optimization](/plans/ecosystem-optimization.md): budgets that still govern exposed surface
- [Realtime demarkus](/plans/watch-agent-messaging.md): WATCH, replica push, delivery paths, live views
- [Lean into QUIC](/plans/quic-first.md): transport review, QUIC broker, fan-out design, broker convergence
- [demarkus-sdk](/plans/demarkus-sdk.md): the client SDK
- [The Universe Pattern](/universe.md): souls, worlds, and hubs
- [Thoughts](/thoughts.md): the reflections this vision grows from