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.

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.

Cartographer offers two complementary profiles:

• Local Core — single agent, stdio transport, local git. Captures the value of the pattern with minimal complexity.
• Server — multi-KB, HTTP + token auth, optional semantic embeddings. For shared and remote deployments.

Key features

• 🔧 Full MCP tool suite — complete list in docs/control-plane.md
• 📖 Read & navigation — atlas_overview, index_get, concept_read, map_list, graph_neighbors (outbound links or backlinks) and concept_list (scoped frontmatter facets)
• 🔍 Search — keyword (pure-Go inverted index) plus optional hybrid semantic search via Ollama
• ✍️ Validated writes with optimistic concurrency (if_match / content-hash), including concept_new from KB-owned templates discovered through template_list, index_patch for curating root/Map/Journal index.md entries with the same bounded concept_patch semantics, and concept_batch for atomic multi-concept writes/patches across a large refactor (one commit, full rollback on any failure)
• 📎 Concept assets — read, write, list, and delete binary or text dossier files inside expanded concepts
• 🛡️ Governance — deterministic lint (broken link, stale claim, orphan, map contracts), commit_gate, gate_check, supersede, contradiction tracking
• 🧬 Transactional git — one commit per write operation; optional synchronization to a remote (fetch/pull-rebase before and push after every write) — git as a sync layer across multiple instances; agentic conflict handling (concepts flagged degraded + conflicts_list tool + guided skill)
• 🗂️ Multi-KB with ?kb=<name> routing; bearer-token auth with scopes / RBAC
• 🔐 Audit log — append-only with hash-chain and Ed25519 signature
• 🧩 Domain skills (SKILL.md / agentskills.io format) with provisioning and client↔server sync, including executable scripts and binary assets
• 🔑 Secrets via SOPS — JSON Pointer references, scoped resolution and safe rotation; plaintext values never stored
• ⚙️ Multi-provider configurator — generates MCP config for Claude Code, Codex CLI, Kiro, OpenCode
• 📦 OKF-compliant — each KB is an OKF bundle and a standalone git repo, zero lock-in (just git + Markdown)

Architecture

Cartographer separates a data plane from a control plane:

• Data plane — the KB itself: OKF Markdown files under data/, organized as atlas → map → concept (the KB, its thematic archives, the pages; journals are the chronological maps). Plain files + git: history, diff, backup, sharing for free.
• Control plane — the MCP tools the agent calls. The server applies every invariant (validation, gates, immutability) so the agent operates safely without direct filesystem access.

The interaction rests on the MCP + Skill + Hook triad: MCP carries data and capabilities, Skills carry procedural know-how loaded on demand, Hooks carry deterministic 0-token automation.

flowchart LR
    A["🤖 Agent (LLM)<br/><i>only via MCP — never touches files</i>"]
    S["Cartographer<br/>Go MCP server<br/><i>invariants enforced server-side</i>"]
    KB[("KB<br/>Markdown + git")]
    R[("remote git")]
    A -- "MCP tools" --> S
    S -- "bounded reads" --> A
    S -- "one commit<br/>per write" --> KB
    KB -. "sync in/out" .-> R

Install

# macOS (Homebrew)
brew install beppetemp/tap/cartographer

# Linux / macOS without Homebrew
curl -fsSL https://raw.githubusercontent.com/BeppeTemp/cartographer/main/install.sh | sh

# From source (Go 1.26+)
go install github.com/BeppeTemp/cartographer/cmd/cartographer@latest

Agent-driven install

Give an agent this prompt to install Cartographer, mount its first KB, connect itself, and verify the setup:

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>`

Quick start

The primary path is four commands: install the binary, run it as a native service, create your first KB, and connect an agent client to it.

brew install beppetemp/tap/cartographer   # or curl install.sh, or `go install` (see Install above)
cartographer service install              # generates config, installs and starts the service
cartographer kb create <name>             # scaffolds a KB in the service's data dir
cartographer connect                      # connects an agent client (Claude Code, OpenCode, Codex, Kiro)

cartographer kb create <name> prints how to get the server to pick up the new KB (cartographer service restart, or --restart to do it and wait for it automatically); service install itself hints at kb create if it starts with no KB mounted yet.

Upgrades of a native local install (brew upgrade or install.sh update) repair themselves: the new binary restarts the running service and re-synchronizes the configured providers in place — disconnect/connect is never an upgrade step. Only already-open agent sessions need restarting. See docs/deployment.md §Upgrades, schema migration, and repo growth.

connect with no flags in a TTY opens an interactive form (server URL, server name, token env var, auth) instead of the flag defaults; pass --no-input to force the non-interactive behavior. Once connected:

cartographer status   # drift check and client/server version check after upgrades; exit 0 in-sync / 1 drift / 2 error
cartographer sync     # re-apply after drift

For local stdio use (a single KB, no service, typically for development) or a manually-configured HTTP server, see serve --kb <path> --init in docs/deployment.md — the native-service path above covers everyday use.

Configuration

Full list with CLI flags and defaults → docs/deployment.md.

Building and testing

make build         # → bin/cartographer
make test          # Unit tests (go test ./...)
make smoke         # stdio smoke test
make smoke-http    # operator-level HTTP smoke test (creates temp KBs via curl)
make e2e           # deterministic HTTP/CLI end-to-end scenarios

The E2E suite drives the compiled binary through HTTP, CLI, filesystem and real temporary git remotes. It is deterministic, requires no model credentials and runs in CI. Full strategy → docs/testing.md.

Project structure

cmd/cartographer/   # single binary: server (serve), client (connect/status/sync/kb/service), TUI
internal/           # okf, kb, mcpserver, search, sqlindex, lint, gitx, audit, auth, embed,
                    # skill, sops, configurator, provisioning, agents, clientconfig, client
docs/               # full documentation (docs/index.md is the map)
test/               # deterministic HTTP smoke and cross-component E2E tests

Package-by-package map, with what each one owns → AGENTS.md §Code map (kept next to the contributor instructions so there is a single copy to keep true).

Documentation

Browsable at beppetemp.github.io/cartographer — same content as docs/, rendered.

The full index lives in docs/index.md. Main entry points:

• docs/overview.md — vision, guiding principles, architecture
• docs/data-plane.md — KB model, hierarchy, OKF
• docs/control-plane.md — Go server, MCP tool API
• docs/concurrency.md — single-writer, git sync, conflicts
• docs/deployment.md — topologies (local service / k8s / multi-server), backup, env vars

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md for the build/test loop, the PR flow (squash-merge, conventional titles, docs updated in the same PR), and how to find your way around the codebase. Cartographer is a personal project maintained on a best-effort basis: no response-time SLA. For security reports, see SECURITY.md.

License

Released under the Apache License 2.0. See LICENSE.