Skip to content

Cartographer — architecture

What it is

Cartographer is a general-purpose agentic wiki: an MCP server that lets agents build and maintain Git-versioned knowledge bases without writing their files directly.

It combines two ideas:

  • Karpathy's LLM Wiki pattern: useful knowledge compounds in a persistent, linked wiki instead of disappearing with a chat session.
  • Google's Open Knowledge Format (OKF): concepts are portable Markdown files with YAML frontmatter, identified by their path.

The filesystem and git history are the source of truth. Search databases and in-memory graphs are derived state and can be rebuilt.

Runtime shapes

The same binary supports two transports and a third role, the worker:

Shape Command Intended use
Local stdio cartographer serve --kb <path> One local client connected to one KB
HTTP server cartographer serve --config <file> One or more KBs, remote clients, optional static bearer authorization
Worker cartographer worker --config <file> A background process for one perimeter of KBs, with its own model profiles and budgets; never started by serve (§The worker in deployment.md)

HTTP can be run as a native user service, a container or a Kubernetes workload. These are deployment choices, not separate product profiles: the KB model and MCP tools are the same.

Principles

  1. The agent uses MCP tools; the server owns filesystem writes and validation.
  2. Concept paths are stable identities.
  3. Markdown and git remain portable and inspectable without Cartographer.
  4. Unknown frontmatter and types are tolerated unless a documented invariant requires otherwise.
  5. Search and indexes are disposable projections of the files.
  6. Writes use optimistic concurrency and one git commit per logical operation.
  7. One server process is the writer for a mounted working copy.
  8. Domain structure and concept types belong to the KB, not the application.
  9. Secrets remain encrypted at rest and are resolved only when explicitly requested.

Components

flowchart TB
    A["Agents: Claude Code, Codex, Kiro, OpenCode, Antigravity, Crush, Copilot CLI"]
    C["Cartographer client: connect / status / sync"]
    B["Browser: the read-only Atlas at /ui/"]

    subgraph S["Cartographer server"]
        T["stdio or HTTP + optional static bearer auth"]
        M["MCP tools"]
        W["Embedded Atlas UI + /api/ui/v1 (read-only)"]
        V["OKF validation + write serialization"]
        I["Derived search indexes"]
        G["git commit + optional remote sync"]
    end

    subgraph K["Knowledge Base (one git repository)"]
        D["data/ — Maps, Journals and concepts"]
        P["skills/ agents/ hooks/ mcp/ instructions"]
        X["services/ + encrypted secrets"]
    end

    A -->|MCP| T --> M
    C -->|HTTP MCP| T
    B -->|HTTP JSON| T --> W
    M --> V --> K
    M --> I
    V --> G

internal/worker is a library, not yet a component of the binary: the model client (Anthropic Messages and OpenAI-compatible chat completions over net/http, token usage reported per call) that a worker, a headless MCP client of the public contract, will drive with its own tool loop (D9, #1257). The allowlist (allow.go: a hard deny set plus an explicit default list, enforced on what is offered and on every call) and the bounded loop (loop.go: step and token caps, tool errors fed back to the model, transport errors abort) run on top of it; workertest holds the scripted model and tool doubles.

Where to continue