# 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](https://demarkus.io/blog/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.

## Related

- [Architecture](/architecture.md): internal system design (modules, wire format, store)
- [Ecosystem](/ecosystem.md): third-party clients and plugins that participate in the network
- [Roadmap](/roadmap.md): what's shipped and what's next

## Related documents

- [Federation](/plans/federation.md): cross-server discovery the pattern depends on
- [Content addressing](/plans/content-addressing.md): fetch by hash across servers
- [Persistent graph](/plans/persistent-graph.md): the hub's crawled working memory
- [Read auth](/plans/read-auth.md): per-path tokens that keep worlds mixed public and private