Architecture

For maintainers and agents: the system's design in one page of principles and module boundaries, with the decisions, protocol, lessons, OKF alignment, world routing, and the realtime layer in six topic files linked below.

Core Principle: The Agent as the Librarian

The server is a bookshelf. It holds documents and hands them back when asked. That's it. The agent is the librarian. It knows where things are, builds indexes, discovers content across servers, routes around failures, and helps you find what you need.

This is a strict requirement, not a suggestion. The server and protocol must stay dumb and fast. All intelligence (federation, discovery, indexing, routing, caching strategies) lives in the client layer (MCP tools, agents, CLI). When considering where to put new functionality, the answer is almost always "in the agent/client, not the server."

Federation is the proof: zero server changes, two MCP tools, all intelligence at the edge. The server doesn't even know federation exists.

The edge is a package boundary, not a process boundary (ADR 0032). The knowledge server process also runs the broker: its MCP gateways and its bearer listener gate (ADR 0033) verify who the caller is and decide what that identity may do. The store handler still knows no user identity: it serves a request under a capability token or under a grant (an audit label and a path scope) the gate put on the request context, and never sees the bearer behind it.

Module Boundaries

protocol/: Wire format types, parsing, serialization. No network code. The foundation everything else depends on.
server/: QUIC server. Accepts Mark Protocol requests over QUIC streams, routes to handlers. Depends on protocol only.
client/: CLI, TUI (Bubble Tea), and MCP server. All three share the same protocol client. Depends on protocol. client/memory/ holds the memory model (journal, hubs, write gates, promote, curate, doctor, the graph), a directory of the module rather than a module of its own (ADR 0043).
knowledge/: demarkus-knowledge, the knowledge server runtime and the broker (OAuth, the MCP gateways, the bearer gate) in one binary. Composes server and client; nothing imports it.
tools/: Admin CLIs like demarkus-token and the plugin binary.

The target layer of every package, wherever it lives, is in layer-map.txt; tools/layercheck fails an import that points up (Memory and knowledge layering).

Topics

The design in six parts, each in one fetch:

Key design decisions: frontmatter as a map, the versioned store, capability auth, read auth for private networks, path traversal defense, status as text, size limits, the markdown-only contract
Verb set and wire format: the complete verb set, the wire format, and why transport is QUIC by design
WATCH and the change hub: how a commit becomes a hint on a watcher's stream on both servers, cursors and resync, backpressure, the performance profile and its known limits
What I have internalized: audit logging with token labels, content-addressed fetch, agent-driven hash discovery, the LOOKUP catalog
Open Knowledge Format compatibility: how the store's metadata aligns with OKF
SNI routing in plain English: how one knowledge server hosts many worlds on one port, the four names that look alike, who sets what in the cluster, failure signatures

ADR 0002: OKF metadata alignment: decision behind the OKF frontmatter model described here
ADR 0003: OKF type default on publish: decision behind the default type on write
ADR 0025: WATCH verb: decision behind the realtime layer
ADR 0032: the broker in the knowledge server process: where the edge sits now
ADR 0033: identity bearers on the mark front door: identity on the wire, the handler still identity blind
ADR 0043: the memory model in client/memory/: where the model lives and why not a module
Read auth plan: plan that shipped read auth for private networks
Content addressing plan: plan that shipped content-addressed fetch and hash discovery
Realtime demarkus: the plan behind WATCH, replica hints, and the levels still to build

Architecture

Core Principle: The Agent as the Librarian

Federation is the proof: zero server changes, two MCP tools, all intelligence at the edge. The server doesn't even know federation exists.

Module Boundaries

protocol/: Wire format types, parsing, serialization. No network code. The foundation everything else depends on.
server/: QUIC server. Accepts Mark Protocol requests over QUIC streams, routes to handlers. Depends on protocol only.
client/: CLI, TUI (Bubble Tea), and MCP server. All three share the same protocol client. Depends on protocol. client/memory/ holds the memory model (journal, hubs, write gates, promote, curate, doctor, the graph), a directory of the module rather than a module of its own (ADR 0043).
knowledge/: demarkus-knowledge, the knowledge server runtime and the broker (OAuth, the MCP gateways, the bearer gate) in one binary. Composes server and client; nothing imports it.
tools/: Admin CLIs like demarkus-token and the plugin binary.

The target layer of every package, wherever it lives, is in layer-map.txt; tools/layercheck fails an import that points up (Memory and knowledge layering).

Topics

The design in six parts, each in one fetch:

Key design decisions: frontmatter as a map, the versioned store, capability auth, read auth for private networks, path traversal defense, status as text, size limits, the markdown-only contract
Verb set and wire format: the complete verb set, the wire format, and why transport is QUIC by design
WATCH and the change hub: how a commit becomes a hint on a watcher's stream on both servers, cursors and resync, backpressure, the performance profile and its known limits
What I have internalized: audit logging with token labels, content-addressed fetch, agent-driven hash discovery, the LOOKUP catalog
Open Knowledge Format compatibility: how the store's metadata aligns with OKF
SNI routing in plain English: how one knowledge server hosts many worlds on one port, the four names that look alike, who sets what in the cluster, failure signatures

ADR 0002: OKF metadata alignment: decision behind the OKF frontmatter model described here
ADR 0003: OKF type default on publish: decision behind the default type on write
ADR 0025: WATCH verb: decision behind the realtime layer
ADR 0032: the broker in the knowledge server process: where the edge sits now
ADR 0033: identity bearers on the mark front door: identity on the wire, the handler still identity blind
ADR 0043: the memory model in client/memory/: where the model lives and why not a module
Read auth plan: plan that shipped read auth for private networks
Content addressing plan: plan that shipped content-addressed fetch and hash discovery
Realtime demarkus: the plan behind WATCH, replica hints, and the levels still to build

Graph: graph

Architecture

Core Principle: The Agent as the Librarian

Module Boundaries

Topics

Related documents