Cartographer

MCP governance server in Go for the Agentic Wiki — knowledge that composes, not that you query.

[!WARNING] Beta software. Cartographer is pre-1.0: the MCP tool surface, CLI and configuration may change between minor releases without a deprecation period. Breaking changes bump the minor version (0.x semantics) and are called out in the changelog. Expect rough edges — bug reports are very welcome.

LLM agents forget everything between sessions, and stateless RAG only bolts retrieval onto that amnesia. The alternative is a knowledge base the agent itself builds and maintains over time — but letting an agent loose on a folder of files ends in broken links, lost history, and silent corruption. Cartographer is the governance layer that makes the pattern safe: the agent works the wiki exclusively through MCP tools, and the server enforces every invariant — validation, linking, immutability gates, one git commit per write.

_{The embedded Atlas on a generated demo KB (web/scripts/demo-kb.mjs): a selected concept in light, the overview in dark.}

What is it

Cartographer implements the Agentic Wiki: a persistent knowledge base of interlinked Markdown files that an LLM agent grows and curates by talking to the server over the MCP protocol. The agent never touches the files directly.

The wiki is grounded in Karpathy's "LLM Wiki" pattern (operating model: knowledge accretes over time, it is not stateless RAG) on top of the OKF substrate (Open Knowledge Format v0.1 by Google Cloud) — each KB is a folder of .md files with YAML frontmatter, self-contained and version-controlled with git. Zero lock-in: the wiki is readable by any tool, including Obsidian and any text editor.

One binary, two transports — deployment choices, not separate products: the KB model and the MCP tools are the same on both.

• Local stdio — one client, one KB, no network. The simplest way to run the pattern.
• HTTP server — one or more KBs behind bearer-token auth, as a native user service, a container or a Kubernetes workload. It hands each client the artifacts its KBs define, and lets a team share some KBs while keeping others private.

Two consequences are worth stating on their own, because they are what most of the design is for: the KB configures the agents that read it across every client you use, and it does that for a whole team rather than a single laptop.

Quick start

You need git and an empty git repository you own (GitHub, Gitea, any git host) to be your first KB's remote: a KB is a git repository, and that remote is what makes it durable and syncable. sops in PATH is needed only if the KB will hold encrypted values.

brew install beppetemp/tap/cartographer   # macOS; Windows, Linux and source installs — see Install
cartographer setup                        # server, first KB and agents, in one guided step

setup asks for the remote, shows its plan, and only then runs it: it installs the native service, creates the KB in an empty repository or mounts the one a repository already holds, connects every detected agent client and verifies the server. It checks git and the remote's credentials before changing anything, and a re-run skips what is already done. Unattended: cartographer setup --remote <url> --agents claude --yes. Each step is also its own command (service install, kb create/kb clone, connect) — see docs/configurator.md. Agent sessions that were already open need a restart to see the new MCP server.

Once connected:

cartographer status    # drift check and client/server version check; exit 0 in-sync / 1 drift / 2 error
cartographer sync      # re-apply after drift
cartographer doctor    # read-only diagnosis of the client configuration: residues, drift, missing triggers
cartographer reconnect # rebuild a client configuration from scratch, preserving every setting

The step-by-step walkthrough is docs/getting-started.md. For a single KB over stdio with no service (typically development) or a hand-configured HTTP server, see serve in docs/deployment.md.

Installing Cartographer with an agent

The Quick start assumes an interactive operator who answers the prompts and diagnoses a failure as it happens.

If you are an agent and the user has asked you to install Cartographer: fetch https://raw.githubusercontent.com/BeppeTemp/cartographer/main/docs/agent-install.md and follow it command by command. Do not install from the Quick start above: the runbook asks for the KB remote up front, verifies the install and ends with the session restart you cannot perform yourself.

For a human driving an agent, this is the prompt to paste:

Set up Cartographer on this machine by following
https://raw.githubusercontent.com/BeppeTemp/cartographer/main/docs/agent-install.md
My first knowledge base is at: `<git remote URL>`

One KB, every agent

A knowledge base is not only what an agent reads — it is also how that agent is set up to work. Cartographer treats skills, subagents, hooks and standing instructions as content of the KB, and materializes them into each client's native format.

The manual alternative is what most setups do today: the same skill hand-copied into .claude/skills/, .opencode/skills/ and .codex/skills/, each drifting on its own, each config file edited by hand for every MCP endpoint. Change one thing and you change it in six places, on every machine, forever.

cartographer connect        # detects installed clients and configures all of them

That single command writes, per client and in the format that client expects:

Subagents and hooks are translated, not copied: the same KB artifact becomes a Markdown agent for Claude Code, a TOML one for Codex, Antigravity-native Markdown, and a generated JavaScript plugin where a hook has no declarative equivalent.

Every — is an unsupported cell declared for a stated reason, never a silent omission — and a cell missing from the table fails a test:

• kiro — the shipped client has no hook mechanism that actually fires (verified empirically; details in docs/interoperability.md §Kiro hooks), so its re-sync trigger is the scheduled timer. Subagents work: ~/.kiro/agents/<name>.json is discovered globally and the built-in agent delegates to it by description.
• hermes — its MCP endpoints and its always-on instruction slot are rendered by its own Ansible role and recreated on the next playbook run, and it has no subagent directory and no hook engine. Skills are delivered, not installed: they land in an inbox with a generated SOURCE.md and the agent's own curator adopts them, because overwriting what that curator owns would destroy its learning.

Where there is no session hook, the scheduled trigger takes over (cartographer service sync-timer install): opt-in, explicit, and never installed as a side effect of connecting.

What keeps it true after the first run: