Cartographer
Cartographer's Meridian server lets AI agents safely read, write, and maintain a shared git-backed knowledge base through MCP, with guardrails, search, graph navigation, and maintenance tools.
Create, read, update, move, delete, expand, supersede, batch-write, and history-inspect concepts with optimistic concurrency and structured findings.
Manage KB-root artifacts (skills, agents, hooks, MCP configs, instructions, templates, paths, glossary) and per-concept non-Markdown assets with sha256
if_matchprotection.Organize knowledge into Maps/Journals; manage curated indexes, templates, ontology, lint contracts, logs, snapshots, and source-ledger registrations.
Search concepts and glossary aliases; inspect graph neighbors/context, link suggestions, overviews, and changes since a time.
Validate/lint the KB, check gates, review/repair drift, list open work, and monitor KB health/usage.
Resolve git rebase conflicts, append log entries, and snapshot the KB.
Enables optional hybrid semantic search using Ollama embeddings, enriching keyword search with semantic relevance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cartographer Create a concept for 'Distributed Tracing' and link it to the observability map."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Why
AI agents start every session from zero, and on a team every colleague's agent starts from its own zero: what one learns stays on that person's machine, in that client. The usual fixes each solve a third of the problem:
RAG retrieves, but nothing accumulates — the agent never gets to write down what it learned.
A folder of Markdown the agent edits freely ends in broken links, lost history and silent corruption.
Skills, subagents and instructions get hand-copied into
.claude/,.codex/,.kiro/… and drift apart on every machine.
Cartographer puts all three in one place: your agents read and grow a knowledge base only through MCP tools, behind a server that enforces the rules, and the same knowledge base carries how your agents are set up.
Related MCP server: llm-wiki-mcp
Try it now
Open the static Atlas demo: a finished, read-only knowledge base on astronomy, with nothing to install. To give your agents a knowledge base of their own, see the Quick start.
The four components
One binary, deployed as four components that you pick from:
Component | What it is | Command | Deploy it when |
Meridian | The server: the only writer of a KB, MCP over HTTP (or stdio for one local client) |
| Always: it holds the KBs |
Surveyor | A headless maintenance agent for one perimeter of KBs |
| You want the wiki kept in order without a person asking |
Atlas | The read-only web UI, served by Meridian | none (a switch of Meridian) | You want to see the graph, the changes and the findings |
Compass | The client next to the agent: configures every agent client, syncs, runs the local bridge, hosts client plugins |
| On every machine where an agent runs |
Three rules hold them together: components talk only through documented interfaces; each does only its
job; you deploy only what you need. Details: docs/deployment.md.
What you get
🧠 Memory that compounds (Meridian). A wiki the agent builds over time (Karpathy's LLM Wiki pattern): plain Markdown + YAML in a git repository you own, readable in Obsidian or any editor. No lock-in.
🛡️ Guardrails, not good intentions (Meridian). Agents write only through MCP tools, and Meridian is the only writer of a KB: schema and link checks, lint, optimistic concurrency, one commit per write, a signed audit log. The agent cannot leave the KB broken.
👥 Built for teams (Meridian). Several KBs behind one server, per-KB and per-map access with bearer-token roles, git as the sync layer, conflicts turned into a guided workflow, SOPS-encrypted secrets.
🧩 One KB configures every agent (Compass). Skills, subagents, hooks and instructions live in the KB and reach each agent client in its own format, translated, not copied. Edit once, every machine converges. What each client gets:
docs/sync.md.🗺️ See it all (Atlas). A read-only web UI in the same binary: a living 3D graph, search, what the agents changed, what the KB ships to them, and what needs fixing.
🔭 Keeps the wiki in order while nobody is looking (Surveyor). Its tasks ingest from feeds and polled sources, repair and review the KB and write syntheses, through the same MCP tools, with its own model budgets. Recipes:
docs/surveyor-recipes.md.
🔌 Extend it with plugins. A plugin is a git repository or a folder that extends every component: clients, skills, subagents, hooks, commands and script tools on Compass; roles and presets on Meridian; recipes and connectors on the Surveyor; branding, views and apps in the Atlas. A client Cartographer does not know yet (a fork, an in-house build) is one plugin away. It is installed with one command, pinned to a commit and enabled only after you approve what it does:
docs/plugins.md.
Install and quick start
# macOS (Homebrew)
brew install beppetemp/tap/cartographer
# Windows (PowerShell; no administrator rights)
irm https://raw.githubusercontent.com/BeppeTemp/cartographer/main/install.ps1 | iex
# 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@latestPre-1.0: breaking changes bump the minor version and are called out in the changelog.
Windows runs natively; WSL is covered in docs/deployment.md.
Then, with git and an empty git repository you own (GitHub, Gitea, any host) to hold your first KB:
cartographer setup # server, first KB and your agents, in one guided stepsetup shows its plan before touching anything, then installs the local service, creates the KB,
connects every agent client it detects and verifies the result. Everything it writes is listed, and
removable, in docs/getting-started.md.
Restart your agent sessions and ask for something worth keeping:
Explore this repository and write a concept page about its architecture in the wiki.
Then open the Atlas (by default http://127.0.0.1:39273/ui/) and watch the page appear. Next session,
ask something related: the agent finds what it wrote and builds on it.
Your KB stays your git repository: Meridian, the only writer, pushes to the remote you gave it.
Cartographer calls no model itself (only the Surveyor does, if you run one), and on loopback no token
is needed; a shared server uses bearer tokens (docs/transport-auth.md).
Prefer to let your agent install it? Paste this:
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>`If you are an agent asked to install Cartographer: follow that runbook, not the Quick start.
Documentation
Browsable at beppetemp.github.io/cartographer; the
map is docs/index.md.
Getting started — from zero to a working wiki
Overview — vision, principles, architecture
MCP tools — the full tool API
Deployment — components, deployment scenarios, configuration, backup
Surveyor recipes and connectors — feed the wiki from your sources
Sync — how artifacts reach each agent client
Plugins — add clients, commands and MCP tools, approved per version
Contributing
Bugs and ideas go to issues; a
question starts from the FAQ. PRs are welcome: CONTRIBUTING.md
covers building, testing and the PR flow. Cartographer is a personal project maintained on a best-effort basis.
Security reports: SECURITY.md.
License
Apache License 2.0 — see LICENSE.
Available Tools
45 toolsartifact_deleteA
Deletes a KB-root artifact file (skills//, agents/.md, hooks/, mcp/.json, instructions.md, templates/.md, paths.yaml, glossary.yaml), and its now-empty containing artifact directory for skills/hooks. if_match (sha256 of the current content, from artifact_read/artifact_list) is required.
Inputs: path (required), if_match (required), reason.
artifact_readBRead-only
Reads a KB-root artifact (skills/, agents/, hooks/, mcp/, instructions.md, templates/.md, paths.yaml, glossary.yaml). Returns content and sha256, the if_match for artifact_write/artifact_delete (present only if the KB sets allow_artifact_write).
Inputs: path (required), encoding.
artifact_writeA
Creates or updates a KB-root artifact file (skills//, agents/.md, hooks/, mcp/.json, instructions.md, templates/.md, paths.yaml, glossary.yaml). On an existing file, if_match is required (sha256 of the current content, from artifact_read/artifact_list) — fails with stale_write if it's missing or doesn't match. On a new file, omit if_match — fails with already_exists if the file is actually already there. Validates structured artifacts, including template frontmatter and variables the paths.yaml schema (paths:/repos: key -> {description, default: ~/…, remote}) and the glossary.yaml schema (terms: list of {canonical, aliases: [..], forbidden: [..]}), before writing.
Inputs: path (required), content (required), reason, encoding, +2 more.
asset_deleteA
Permanently deletes a non-Markdown asset from an expanded concept. if_match is mandatory and must be the current raw-byte sha256 returned by asset_read or asset_list.
Inputs: path (required), if_match (required), concept_id (required), reason.
asset_listARead-only
Lists the non-Markdown assets of an expanded concept: path, size, sha256, executable. A file over 10 MiB shows oversized: true (deletable only).
Inputs: concept_id (required).
asset_readBRead-only
Reads a non-Markdown asset of an expanded concept: content, encoding, sha256 (the if_match to change or delete it), size, executable mode.
Inputs: path (required), concept_id (required), encoding.
asset_writeA
Creates or updates a non-Markdown asset of an expanded concept (max 10 MiB). New: omit if_match; overwrite: if_match = current sha256. Content is text or base64. executable: omit to keep the mode (new files are non-executable).
Inputs: path (required), content (required), concept_id (required), reason, +3 more.
atlas_overviewARead-only
Root index.md plus the Maps and Journals with concept counts. structure: true adds the most central concepts and link-graph communities: where to start reading.
Inputs: structure.
changes_sinceARead-only
Concept changes from git history since a timestamp or duration: each concept's newest change, authors, agent clients, operations and reasons. links: true also reports links added/removed and pages that became or stopped being orphans.
Inputs: limit, links, since.
concept_batchA
All-or-nothing write/patch of distinct concepts: one commit and log entry; a failure leaves the KB untouched. At most 50 operations and 512 KiB of decoded content per call (a patch counts its edits). Each operation is 'write' (frontmatter, body, if_match optional = create-only) or 'patch' (if_match required; the concept_patch fields). A creating 'write' may set index_entry to add a curated index entry. Not covered: delete, move, expand, assets, other index edits. Returns id, content_hash and findings per operation.
Inputs: operations (required), reason.
concept_deleteA
Permanently removes a concept (git commit). Refuses with inbound_links (listing the linkers) unless force=true; links are never rewritten. To keep the page use supersede; to rename, concept_move. An expanded concept that owns assets also needs force=true.
Inputs: id (required), force, reason, if_match.
concept_expandB
Turns .md into a directory / whose index.md keeps the same ID, so the concept can hold satellites /; links keep working. id needs exactly two segments (map/concept). No inverse.
Inputs: id (required), reason.
concept_historyARead-only
Commits that changed a concept, newest first, following renames: {sha, at, author, subject, reason?, path}; truncated if more exist. A sha passed as rev to concept_read shows the concept then. No git history: no revisions.
Inputs: id (required), limit.
concept_listARead-only
Exhaustive inventory (id, title, type, status; fields adds keys) under a scope prefix, sorted by id; empty = whole KB. where and timestamp filters apply before limit. For curated navigation use index_get.
Inputs: limit, scope, where, fields, +2 more.
concept_moveA
Moves concepts to new IDs in one commit: one source_id/target_id pair or a moves array (exclusive). All entries are validated first (source exists, target free, no traversal or duplicate source); an invalid one aborts the batch. Unless rewrite_links=false, inbound links KB-wide are rewritten. Works across maps and services/. An expanded concept moves with assets and satellites. A mid-batch filesystem failure names both IDs, no rollback. Returns findings on moved concepts and their linkers.
Inputs: moves, reason, source_id, target_id, +1 more.
concept_newB
Creates a concept from a KB template (template_list) and records it as its shape. Refuses an existing id. index_entry adds it to the map's curated index. Returns findings.
Inputs: id (required), template (required), vars, reason, +1 more.
concept_patchA
Edit-style patch of a concept body: old_string/new_string/replace_all, or an edits array applied atomically in order. if_match required (stale_write). frontmatter is shallow-merged and may be the only change; frontmatter_append/frontmatter_remove add or drop list items (idempotent). Returns content_hash, findings. Many concepts: concept_batch, up to 50 operations in one commit.
Inputs: id (required), if_match (required), edits, unset, +7 more.
concept_readARead-only
Reads a concept: content_hash, frontmatter (parsed) and _raw, body. with_content: true returns content (exact bytes) instead of body. section returns one section; outline: true only the headings; match greps body lines (with context).
Inputs: id (required), rev, full, match, +4 more.
concept_writeA
Creates or updates a concept from frontmatter (YAML map, type required) and a markdown body. if_match (content hash) gives optimistic concurrency: stale_write if changed. Returns content_hash and structural findings too (links, orphan, index): fix them.
Inputs: id (required), body (required), frontmatter (required), reason, +1 more.
conflicts_listARead-only
Lists open git rebase conflicts: concept, local/remote SHAs, branch, files. Resolve with git_conflict_resolve (kb-conflict-resolve skill).
Inputs: no named parameters.
gate_checkARead-only
Local gate: validate + lint + commit_gate. Use at session end over the IDs you wrote, or before fast-forwarding to main. changed_ids alone lints just those (no whole-KB structure checks); empty changed_ids: whole KB, no commit gate; scope: a path prefix. severity_min sets the lint floor (default warning); pass ignores it.
Inputs: changed_ids (required), scope, severity_min, scope_neighbors.
git_conflict_resolveA
Resolves a git conflict. strategy: ours (local), theirs (remote), edit (reconciled body), union (log.md only). Once every open conflict (conflicts_list) is resolved, Cartographer merges, commits, pushes and clears the degraded markers.
Inputs: strategy (required), concept_id (required), body.
graph_contextCRead-only
Concepts most related to a question or set of concepts, following links both ways, with hop count and the concept each was reached through.
Inputs: ids, limit, query.
graph_neighborsARead-only
Graph neighbors up to depth hops (default 1): out = linked from the concept, in = linking to it, both = either.
Inputs: id (required), depth, direction.
index_getARead-only
Reads a folder's index.md (root if empty). with_hash: {path, content, content_hash} (if_match for index_patch). Over 60 KB: outline, unless full or with_hash; outline: true forces it.
Inputs: full, path, outline, with_hash.
index_patchA
Like concept_patch, for the root or a Map/Journal curated index.md (same edit forms; if_match required, from index_get with_hash). An expanded concept's own index.md is refused (expanded_index): use concept_patch. Returns path, content_hash, replacements, findings.
Inputs: if_match (required), path, edits, reason, +3 more.
kb_repairA
Applies the mechanical fix a lint finding carries (fix) for one check, KB-wide in one commit. dry_run defaults to true (plan only). Concepts changed since listing are skipped. Judgement fixes: kb-doctor skill.
Inputs: check (required), limit, scope, reason, +1 more.
kb_reviewCRead-only
Ranked kb-doctor work list: items {kind, concepts, evidence, suggested_action}. Dismiss: lint_ignore: [kind] on a named concept.
Inputs: kind, limit, scope, offset.
kb_statusCRead-only
KB health in one call: concept counts (by type, status), stale concepts, open contradictions and gaps, git replication state, capabilities (each per-KB gate, its state and controlling key), source-ledger counts, frequent search misses, versions, and conformance: {findings by severity, fixable, last_doctor, doctor_suggested}, the drift from the current standard. When doctor_suggested is true, follow the kb-doctor skill. usage: which skills and agents the clients actually load (never used, stale, active), from their reports. Read-only.
Inputs: no named parameters.
link_suggestBRead-only
Existing concepts this one probably should link to: at least two shared neighbours, not yet linked, hub evidence discounted; for an unlinked concept, title matches.
Inputs: id (required), limit.
lintCRead-only
Deterministic checks. check, severity_min, limit (max 200), offset filter and page. Counts ignore them.
Inputs: check, limit, scope, offset, +2 more.
log_appendA
Appends an entry to the root log.md (newest first). With path, the entry is prefixed '[] ' in the root log (no per-directory log); read back with log_tail(path).
Inputs: entry (required), path, reason.
log_tailARead-only
Last n entries (default 20) for path; empty = root log. A path filters root-log entries prefixed '[] ' (plus any pre-existing /log.md).
Inputs: n, path.
map_createC
Creates a Map or Journal (kind: journal) with _map.md, index.md, log.md. ontology_mode: strict (enforces concept_types) or flexible. templates (slugs) make every page follow one. Contract options are lint only, not a write gate.
Inputs: name (required), title (required), kind, reason, +11 more.
map_deleteA
Deletes a Map or Journal only if empty (just the scaffold _map.md, index.md, log.md). Otherwise nothing changes and the error lists the concepts: concept_move them first.
Inputs: map (required), reason.
map_listBRead-only
Lists Maps and Journals with kind, ontology_mode, concept_types and expanded-concept count.
Inputs: no named parameters.
map_updateC
Changes a map's title or lint contract: given keys are replaced whole, an empty list, "", false or {} removes one. stale_after 0 = off, -1 = default.
Inputs: map (required), index, title, reason, +31 more.
searchBRead-only
Keyword search over concepts (SQLite FTS5, substring matching); returns IDs ranked by relevance. Glossary aliases are searched too (expanded_to).
Inputs: query (required), limit, scope, record_miss, +1 more.
snapshotC
Logs a KB snapshot entry and, with git auto-commit enabled, a git commit.
Inputs: reason, message.
source_listARead-only
Source ledger (Source concepts), oldest first: {id, title, source_kind, ingest_status, timestamp?, cited_by (count), cited_by_ids (concepts citing it in provenance)}. status defaults to pending ('*' = all). Read-only.
Inputs: limit, scope, status.
source_registerA
Records a primary source BEFORE ingesting it: a Source concept in a journal (default 'sources', map_create kind journal). Dedupes by sha256, else locator: a duplicate returns {id, duplicate: true, ingest_status}, writes nothing, adding locator_mismatch + existing_locator if the locator differs. Never fetches; body is your distillation. Cite its ID in provenance, then concept_patch ingest_status.
Inputs: title (required), source_kind (required), map, body, +5 more.
supersedeB
Marks a concept as superseded by another: sets status=superseded and records the successor. Returns findings on it.
Inputs: source_id (required), target_id (required), reason.
template_listARead-only
Lists KB-only concept templates: slug, type, title, variables. Read a template body with artifact_read.
Inputs: no named parameters.
validateCRead-only
Validates frontmatter, reserved files and strict ontology; returns the errors.
Inputs: scope.
work_listBRead-only
Open work: concepts in an open status for their map, and unchecked - [ ] items in any concept, with section and line. where as in concept_list; fields and order_by name frontmatter keys. Read-only: change work with concept_patch.
Inputs: limit, scope, stale, where, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 45 tools
Most tools have clearly distinct scopes (concept vs artifact vs asset vs map vs index), but the health/validation cluster (validate, lint, gate_check, kb_repair, kb_review, kb_status) and multiple write/patch variants (concept_write, concept_patch, concept_batch, concept_new) create some potential for misselection. Descriptions clarify boundaries, so ambiguity is limited but not absent.
Nearly all tools use consistent snake_case with an entity_action pattern (artifact_read, concept_write, map_create), but a few deviate as single verbs (validate, search, supersede, lint, snapshot) or noun_noun (atlas_overview, changes_since). The convention is still predictable and readable throughout.
45 tools is far above the typical 3-15 range and exceeds the 25+ threshold for 'too many'. The KB domain is broad, but the surface is heavy and could overwhelm an agent; many tools could be consolidated or grouped without losing capability.
Core CRUD and lifecycle for concepts, maps, artifacts, assets, index, logs, sources, and graph are well covered. Minor gaps exist (no inverse for concept_expand, no explicit map_read, no asset_move, no index_create), but agents can work around them using existing tools.
Maintenance
Related MCP Connectors
Shared project wiki for AI agents: read and write pages, next actions, and activity logs over MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted markdown project wikis your team's AI assistants read, search, and update over MCP.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for persistent, compounding markdown wikis maintained by LLMs. Enables incremental knowledge base building with interlinked pages, search, and raw source management.34 npm1MIT
- AlicenseBqualityCmaintenanceAn MCP server that provides AI agents with a governed wiki requiring human approval before any formal page update, combining structured knowledge management with safe, auditable writes.14MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that gives AI coding agents a git-backed markdown wiki to read and update, enabling search, read, write, verify, ingest, promote, and lint operations on versioned knowledge documents with schema validation, staleness tracking, and contradiction detection.4MIT
- AlicenseNot gradedqualityAmaintenanceAn MCP server that enables verified agents to retrieve from, propose changes to, and share capabilities around a human-owned Markdown/Git knowledge base, ensuring curation, exact-byte approval, and Git-based promotion.MIT