M Demarkus

Organizational Knowledge System

Run Demarkus at organization scale: a broker-fronted universe of worlds that whole teams join with one command, authenticate against with OIDC, and reach through the same MCP tools their agents already use.

This is the tier above the team knowledge base. A team scenario is one shared server with hand-distributed tokens. A knowledge system is many worlds behind a single broker: users authenticate through your identity provider, the broker mints scoped tokens per world automatically, and nobody copies a raw token by hand.

What you’ll have

Architecture

                 Coding agent  (MCP over HTTPS, OIDC)
                      │
                      ▼
        knowledge.example.com                 ← broker: OIDC + token minting
                      │  (QUIC, internal)
        ┌─────────────┼─────────────┬─────────────┐
        ▼             ▼             ▼             ▼
   world: planner  world: storage  hub: root   library      ← reading room
        ▲             ▲             ▲
    memories      memories        agent           ← crawls worlds, publishes the graph

The broker is the only public surface. Worlds stay private; the broker authenticates the caller against your IdP, mints a scoped token for the world being addressed, and proxies the request. The MCP tool surface the agent sees is byte-for-byte the same as talking to a local demarkus-server, federation, graph, and lookup tools included, plus two broker-only tools: mark_worlds lists the worlds and mark_lookup_all runs one catalog lookup across every readable world, globally limited, with a partial status when a world fails instead of a failed query.

Worlds default to the file store. Point one at Postgres (-store postgres -pg-dsn ...) and it serves LOOKUP from the database catalog, so that world scales past a single replica.

At production scale, demarkus-knowledge-server replaces per-world server processes: one deployment serves every world on one UDP listener, TLS SNI selects the world during the handshake, and each world keeps its own GCS bucket (with an immutable world ID), tokens, policy, and rate limits. A Helm chart ships in the repo (deploy/helm/demarkus-knowledge-server).

High availability

The knowledge server is stateless: all durable state lives in the world’s GCS bucket, so every replica derives the same view from one head object. Writes race on a compare-and-swap of that head object; there is no leader election. The chart refuses to render fewer than 2 replicas and ships a PodDisruptionBudget with minAvailable: 1.

Before a world serves, demarkus-knowledge-bootstrap initializes its bucket and seeds its publish policy. Credentials come only from Workload Identity / Application Default Credentials; no keys are mounted. Egress to GCS requires the explicit networkPolicy.allowUnrestrictedHTTPS opt-in, because a NetworkPolicy cannot express GCS hostnames. Per-world tokens mount from Secrets and hot-reload on change or SIGHUP. The chart README covers all of it.

For the design rationale behind worlds, hubs, and memories, see Creating an automated knowledge universe.

Stand up the system

On one host

The five-minute appliance installs the same architecture on a single Linux box in one command: broker, world, hub, agent, library, login, and HTTPS. Right for a pilot, a small org, or an air-gapped install.

On a cluster

The reference deployment is a forkable GitHub template that stands up a complete knowledge system on GKE (broker, worlds, and hub) with GitOps and secret management wired in:

Fork it, point it at your project and domain, and apply. The live knowledge.demarkus.io runs from this same template.

The deployment publishes a system policy and project template to the hub’s well-known path (mark://root/.well-known/demarkus/), so joining agents discover the conventions of your system, required tags and project layout included, without you documenting them separately.

Join as a user

Once the broker is up, anyone on the team joins from Claude Code, OpenCode, or pi. No local server or capability token is needed: the plugin connects the broker through the agent’s MCP OAuth flow.

1. Install the plugin

Claude Code:

/plugin marketplace add latebit-io/demarkus
/plugin install demarkus-knowledge@demarkus

OpenCode:

curl -fsSL https://raw.githubusercontent.com/latebit-io/demarkus/main/plugins/opencode-knowledge/install.sh | bash

Restart OpenCode before continuing.

pi (demarkus-pi-knowledge, installed from a checkout):

pi install npm:pi-mcp-adapter
pi install ./demarkus/plugins/pi-knowledge

2. Join the system

/knowledge-join https://knowledge.example.com

Pass the full https:// URL of the broker’s MCP gateway. The command validates it, registers it as an MCP server in your agent, and points you at the browser-based auth flow on the first tool call. Authentication follows the standard MCP authorization spec: discovery (RFC 8414 / 9728), dynamic client registration (RFC 7591), then authorization_code + PKCE. You log in through your identity provider; the broker handles per-world tokens from there.

In OpenCode, restart once more after joining so it loads the new MCP entry. Complete OAuth when prompted, or run opencode mcp auth <slug>.

3. Navigate and work

/knowledge

The plugin’s session guidance steers agents to recall from the system before answering and to publish back to it as work lands, with the system’s tag policy enforced at publish time, so the catalog stays searchable via mark_lookup.

A personal memory and an organizational knowledge system compose cleanly in the same install. The memory is your private scratch space over direct QUIC; the system is the shared, broker-fronted universe. They don’t conflict; the plugins partition by server scope.

Live example

knowledge.demarkus.io is a live knowledge system running the reference deployment, with a root hub and a published system policy. Point /knowledge-join at it to see the join flow end to end:

/knowledge-join https://knowledge.demarkus.io