The Universe Pattern

A composition pattern for organizing demarkus servers into a knowledge network. Names the three roles a server can play and how they connect. The protocol does not enforce these roles — they are deployment conventions that emerge from running many simple servers together.

For the long-form narrative of why this matters, see the blog post: Creating an automated knowledge universe.

The Three Roles

World

A team's server. Holds the team's decisions, design docs, ADRs, runbooks. Owned by the team, written to by their agents and humans. Other worlds can read it (or not, depending on read-auth).

Hub

An indexing server. A hub agent crawls connected worlds, builds document graphs, and publishes cross-references back to the hub as ordinary documents. Hubs are not special protocol features — they are demarkus servers whose content happens to be indexes (mark_graph_publish / mark_index outputs).

Soul

A developer-local server. Acts as persistent agent memory across sessions and as a scratch pad before content is ready to publish to a world. The demarkus project's own mark://soul.demarkus.io is the canonical example.

How They Compose

        ┌─────────┐
        │   Hub   │  ← indexes worlds, publishes cross-references
        └────┬────┘
             │ crawl
   ┌─────────┼─────────┐
   ▼         ▼         ▼
┌──────┐ ┌──────┐ ┌──────┐
│World │ │World │ │World │  ← team servers
│  A   │ │  B   │ │  C   │
└──┬───┘ └──┬───┘ └──┬───┘
   │        │        │  publish when ready
┌──┴──┐  ┌──┴──┐  ┌──┴──┐
│Soul │  │Soul │  │Soul │  ← per-developer memory
└─────┘  └─────┘  └─────┘

Worlds can also link directly to each other via mark:// URIs. The hub adds a discovery layer; it is not a routing requirement.

Why It Works

One protocol everywhere. Souls, worlds, and hubs all run the same demarkus-server binary. An agent that masters the six verbs operates anywhere on the network.
Cheap to run. A single binary with no database. Spinning up "one more server" has near-zero operational cost, which is what makes per-team and per-developer servers practical.
No coordination. Hub indexing happens in the background. Souls accumulate locally. Worlds publish independently. By the time an agent needs cross-team context, the hub already has it.
Capability-based isolation. Read-auth on worlds keeps private content private without requiring a separate "private demarkus." Same protocol, different tokens.

Where This Shows Up in the Codebase

The pattern is the reason several features exist:

Federation / content-addressing (/plans/federation.md, /plans/content-addressing.md) — agents discover and fetch by hash across servers, which is what makes hub-mediated discovery possible
Persistent graph (/plans/persistent-graph.md) — local cache of crawled worlds, the hub's working memory
Read auth (/plans/read-auth.md) — per-path token enforcement so worlds can mix public and private content

The protocol stays minimal; the universe pattern is what those minimal pieces compose into.

Architecture — internal system design (modules, wire format, store)
Ecosystem — third-party clients and plugins that participate in the network
Roadmap — what's shipped and what's next