# 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

| Release | Theme | Contents |
|---|---|---|
| 1.0 | Freeze and finish | The [1.0 plan](/plans/v1.md) as written: one vocabulary, reduced surface, protocol final. Pull in ALPN `mark/1` only, since it satisfies fortification 1 and makes everything after it additive. The QUIC measurement baseline runs on the `benchmarks` branch in parallel; it adds no feature. |
| 1.1 | Live | SDK extraction, WATCH, replica push, the QUIC broker with fan-out, 0-RTT and UDP 443. |
| 1.2 | Reactive | Dependency subscriptions, derived documents that know they are stale, watchable beliefs, `client/live` in every surface, the HTTPS broker reduced to an adapter. |
| Later | Open | Verifiable federation across organizations, the pure-QUIC profile as a default, the adapter phase-out, level 3 collaboration as a separate room service. |

## Tensions to settle

- **Feature freeze and the new plans.** The 1.0 plan freezes features until 1.0 ships, and the realtime, QUIC, and SDK plans are features. Either they wait for 1.0, or the freeze is lifted on purpose and 1.0 is redefined.
- **Lockstep versions and the SDK.** 1.0 ships every module at one version; the SDK plan gives it its own semver in its own repo. Pick one.
- **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; 1.0 decisions D2 and D3 are where cutting happens.
- **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
- [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