Skip to main content
Glama

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)

cartographer serve

Always: it holds the KBs

Surveyor

A headless maintenance agent for one perimeter of KBs

cartographer surveyor

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

cartographer connect, sync

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@latest

Pre-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 step

setup 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.

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 tools
artifact_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_readB
Read-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_listA
Read-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_readB
Read-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_overviewA
Read-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_sinceA
Read-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_historyA
Read-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_listA
Read-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_readA
Read-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_listA
Read-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_checkA
Read-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_contextC
Read-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_neighborsA
Read-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_getA
Read-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_reviewC
Read-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_statusC
Read-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.

lintC
Read-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_tailA
Read-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_listB
Read-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.

snapshotC

Logs a KB snapshot entry and, with git auto-commit enabled, a git commit.

Inputs: reason, message.

source_listA
Read-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_listA
Read-only

Lists KB-only concept templates: slug, type, title, variables. Read a template body with artifact_read.

Inputs: no named parameters.

validateC
Read-only

Validates frontmatter, reserved files and strict ontology; returns the errors.

Inputs: scope.

work_listB
Read-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

    B3.1/5.0

    Scored across 45 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for persistent, compounding markdown wikis maintained by LLMs. Enables incremental knowledge base building with interlinked pages, search, and raw source management.
      34 npm
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      An 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.
      14
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      4
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      An 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