{
  "markdown": "```\n ██████╗ █████╗ ██████╗ ████████╗ ██████╗  ██████╗ ██████╗  █████╗ ██████╗ ██╗  ██╗███████╗██████╗\n██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔════╝ ██╔══██╗██╔══██╗██╔══██╗██║  ██║██╔════╝██╔══██╗\n██║     ███████║██████╔╝   ██║   ██║   ██║██║  ███╗██████╔╝███████║██████╔╝███████║█████╗  ██████╔╝\n██║     ██╔══██║██╔══██╗   ██║   ██║   ██║██║   ██║██╔══██╗██╔══██║██╔═══╝ ██╔══██║██╔══╝  ██╔══██╗\n╚██████╗██║  ██║██║  ██║   ██║   ╚██████╔╝╚██████╔╝██║  ██║██║  ██║██║     ██║  ██║███████╗██║  ██║\n ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝\n```\n\n> MCP governance server in **Go** for the *Agentic Wiki* — knowledge that **composes**, not that you query.\n\n[![CI](https://github.com/BeppeTemp/cartographer/actions/workflows/ci.yml/badge.svg)](https://github.com/BeppeTemp/cartographer/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/BeppeTemp/cartographer?include_prereleases)](https://github.com/BeppeTemp/cartographer/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/BeppeTemp/cartographer)](https://goreportcard.com/report/github.com/BeppeTemp/cartographer)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Go](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go)](https://go.dev/)\n[![MCP](https://img.shields.io/badge/protocol-MCP-7C3AED)]()\n\n> [!WARNING]\n> **Beta software.** Cartographer is pre-1.0: the MCP tool surface, CLI and\n> configuration may change between minor releases without a deprecation\n> period. Breaking changes bump the **minor** version (0.x semantics) and are\n> called out in the [changelog](CHANGELOG.md). Expect rough edges — bug\n> reports are very welcome.\n\nLLM agents forget everything between sessions, and stateless RAG only bolts retrieval onto that\namnesia. The alternative is a knowledge base the agent itself **builds and maintains over time** —\nbut letting an agent loose on a folder of files ends in broken links, lost history, and silent\ncorruption. **Cartographer** is the governance layer that makes the pattern safe: the agent works\nthe wiki exclusively through MCP tools, and the server enforces every invariant — validation,\nlinking, immutability gates, one git commit per write.\n\n![Demo](docs/assets/demo.gif)\n\n## What is it\n\n**Cartographer** implements the _Agentic Wiki_: a persistent knowledge base of interlinked\nMarkdown files that an LLM agent grows and curates by talking to the server over the MCP\nprotocol. The agent **never touches the files directly**.\n\nThe wiki is grounded in **Karpathy's \"LLM Wiki\" pattern** (operating model: knowledge accretes\nover time, it is not stateless RAG) on top of the **OKF** substrate (Open Knowledge Format v0.1 by\nGoogle Cloud) — each KB is a folder of `.md` files with YAML frontmatter, self-contained and\nversion-controlled with git. Zero lock-in: the wiki is readable by any tool, including Obsidian and\nany text editor.\n\nCartographer offers **two complementary profiles**:\n- **Local Core** — single agent, stdio transport, local git. Captures the value of the pattern with\n  minimal complexity.\n- **Server** — multi-KB, HTTP + token auth. One server holds several knowledge bases, hands each\n  client the artifacts its KBs define, and lets a team share some KBs while keeping others private.\n\nTwo consequences are worth stating on their own, because they are what most of the design is for:\nthe KB **configures the agents that read it** across every client you use, and it does that for a\nwhole team rather than a single laptop.\n\n## One KB, every agent\n\nA knowledge base is not only what an agent reads — it is also **how that agent is set up to work**.\nCartographer treats skills, subagents, hooks and standing instructions as content of the KB, and\nmaterializes them into each client's native format.\n\nThe manual alternative is what most setups do today: the same skill hand-copied into\n`.claude/skills/`, `.opencode/skills/` and `.codex/skills/`, each drifting on its own, each config\nfile edited by hand for every MCP endpoint. Change one thing and you change it in five places, on\nevery machine, forever.\n\n```bash\ncartographer connect        # detects installed clients and configures all of them\n```\n\nThat single command writes, per client and in the format that client expects:\n\n| | claude | opencode | codex | kiro | hermes |\n|---|---|---|---|---|---|\n| **MCP endpoint** | `.claude.json` | `opencode.json` | `config.toml` block | `.kiro/settings/mcp.json` | *rendered by its own deploy* |\n| **Skills** | `.claude/skills/` | `.opencode/skills/` | `.codex/skills/` | `.kiro/skills/` | delivered to its inbox |\n| **Subagents** | `.claude/agents/*.md` | `.opencode/agent/*.md` | `.codex/agents/*.toml` | — | — |\n| **Hooks** | `settings.json` | generated JS plugin | `config.toml` block | — | — |\n| **Instructions** | block in `CLAUDE.md` | block in `AGENTS.md` | block in `AGENTS.md` | `.kiro/steering/` | — |\n\nSubagents and hooks are **translated**, not copied: the same KB artifact becomes a Markdown agent\nfor Claude Code, a TOML one for Codex, and a generated JavaScript plugin where a hook has no native\nequivalent. Cells that cannot exist are `unsupported` by explicit declaration, never by silent\nomission — and a cell missing from the table fails a test.\n\nWhat keeps it true after the first run:\n\n- **it re-syncs by itself** — a `SessionStart` hook on every client that has one, a scheduled timer\n  for those that don't;\n- **it verifies the files on disk**, not just its own bookkeeping: an artifact edited by hand or\n  deleted is restored from the server;\n- **every materialized file carries a provenance stamp** saying which KB it came from and where to\n  edit it for real;\n- **it only ever touches what it created** — pruning is limited to its own tracked paths, and\n  `--dry-run` shows the plan without writing;\n- **`doctor`** diagnoses residues and drift read-only; **`reconnect`** rebuilds a client from\n  scratch while preserving every setting.\n\nEdit a skill once in the KB, and every client of every machine converges on it.\n\n## Teams\n\nThe same mechanism is what makes Cartographer work for more than one person. A server mounts\nseveral KBs and routes by `?kb=<name>`, so colleagues can each keep a private knowledge base while\nsharing others.\n\n- **Per-KB authorization** — bearer tokens carry `kb:<name>:r` or `kb:<name>:rw` scopes. **Roles**\n  ([`docs/transport-auth.md`](docs/transport-auth.md)) narrow that further to specific maps, journals\n  and concept types, so a teammate can be an editor of the runbooks and a reader of everything else.\n  Rules are unioned: adding a role can only widen access, never silently revoke it.\n- **Git is the sync layer** — every write is a commit, with fetch/pull-rebase before and push after,\n  so teammates running their own server against **separate clones of the same remote** converge\n  without a coordination protocol. A conflict is then not an error page but a workflow: the affected\n  concepts are flagged `degraded`, `conflicts_list` enumerates them, and a bundled skill walks an\n  agent through resolving them. (One process is the sole writer of a given working copy; pointing\n  two writers at one checkout is not a supported model — partition KBs across instances instead, see\n  [`docs/concurrency.md`](docs/concurrency.md).)\n- **Shared content stays portable** — a skill that mentions a local repository uses a\n  `{{repo:<name>}}` placeholder resolved **on each client** from its own git remotes, so the same\n  artifact works on every teammate's machine without machine-specific paths leaking into the KB. A\n  server-side lint flags the ones that do.\n- **Provenance you can verify** — a KB can sign its provisioning artifacts with Ed25519; clients pin\n  the public key out of band and refuse anything that fails verification. Distributing a skill to a\n  team is then a checkable act, not a matter of trust.\n- **Per-KB identity** — commit author and an optional tool-name prefix are configured per KB, so\n  history attributes correctly and an agent mounting several KBs never confuses their tools.\n\n## Key features\n\n- 🔧 **Full MCP tool suite** — complete list in [`docs/control-plane.md`](docs/control-plane.md)\n- 📖 **Read & navigation** — `atlas_overview`, `index_get`, `concept_read`, `map_list`,\n  `graph_neighbors` (outbound links or backlinks) and `concept_list` (scoped frontmatter facets)\n- 🔍 **Search** — keyword: a pure-Go inverted index, or SQLite FTS5 with a trigram tokenizer when the KB has a persisted index\n- ✍️ **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)\n- 📎 **Concept assets** — read, write, list, and delete binary or text dossier files inside expanded concepts\n- 🛡️ **Governance** — deterministic `lint` (broken link, stale claim, orphan, map contracts), `commit_gate`,\n  `gate_check`, `supersede`, contradiction tracking\n- 🧬 **Transactional git** — one commit per write operation; optional synchronization to a remote\n  (fetch/pull-rebase before and push after every write), which is also what lets several instances\n  serve one KB — see [Teams](#teams)\n- 🔐 **Audit log** — append-only with hash-chain and Ed25519 signature\n- 🧩 **Domain skills** (`SKILL.md` / agentskills.io format), including executable scripts and binary\n  assets — see [One KB, every agent](#one-kb-every-agent) for how they reach each client\n- 🔑 **Secrets via SOPS** — JSON Pointer references, scoped resolution and safe rotation; plaintext values never stored\n- 📦 **OKF-compliant** — each KB is an OKF bundle and a standalone git repo, zero lock-in (just git +\n  Markdown)\n\n## Architecture\n\nCartographer separates a **data plane** from a **control plane**:\n\n- **Data plane** — the KB itself: OKF Markdown files under `data/`, organized as\n  **atlas → map → concept** (the KB, its thematic archives, the pages; journals are the\n  chronological maps). Plain files + git: history, diff, backup, sharing for free.\n- **Control plane** — the MCP tools the agent calls. The server applies every invariant (validation,\n  gates, immutability) so the agent operates safely without direct filesystem access.\n\nThe interaction rests on the **MCP + Skill + Hook** triad: MCP carries data and capabilities, Skills\ncarry procedural know-how loaded on demand, Hooks carry deterministic 0-token automation.\n\n```mermaid\nflowchart LR\n    A[\"🤖 Agent (LLM)<br/><i>only via MCP — never touches files</i>\"]\n    S[\"Cartographer<br/>Go MCP server<br/><i>invariants enforced server-side</i>\"]\n    KB[(\"KB<br/>Markdown + git\")]\n    R[(\"remote git\")]\n    A -- \"MCP tools\" --> S\n    S -- \"bounded reads\" --> A\n    S -- \"one commit<br/>per write\" --> KB\n    KB -. \"sync in/out\" .-> R\n```\n\n## Install\n\n```bash\n# macOS (Homebrew)\nbrew install beppetemp/tap/cartographer\n\n# Linux / macOS without Homebrew\ncurl -fsSL https://raw.githubusercontent.com/BeppeTemp/cartographer/main/install.sh | sh\n\n# From source (Go 1.26+)\ngo install github.com/BeppeTemp/cartographer/cmd/cartographer@latest\n```\n\n### Agent-driven install\n\nGive an agent this prompt to install Cartographer, mount its first KB, connect itself, and verify the setup:\n\n```text\nSet up Cartographer on this machine by following\nhttps://raw.githubusercontent.com/BeppeTemp/cartographer/main/docs/agent-install.md\nMy first knowledge base is at: `<git remote URL>`\n```\n\n## Quick start\n\nThe primary path is four commands: install the binary, run it as a native service, create your\nfirst KB, and connect an agent client to it.\n\n```bash\nbrew install beppetemp/tap/cartographer   # or curl install.sh, or `go install` (see Install above)\ncartographer service install              # generates config, installs and starts the service\ncartographer kb create <name> --remote <url>  # scaffolds a KB in the data dir, pushes it to <url>\ncartographer connect                      # configures every detected client — see One KB, every agent\n```\n\n`--remote <url>` is an **empty** git repository that becomes the KB's `origin`: a KB is a git\nrepository, and that remote is what makes it durable and syncable (`--no-remote` creates a\nlocal-only KB that is neither, D134). A repository that already holds a KB is mounted with\n`cartographer kb clone <remote>` instead. `kb create` prints how to get the server to pick up the\nnew KB (`cartographer service restart`, or `--restart` to do it and wait for it automatically);\n`service install` itself hints at `kb create` if it starts with no KB mounted yet.\n\nUpgrades of a native local install (`brew upgrade` or `install.sh update`) repair themselves:\nthe new binary restarts the running service and re-synchronizes the configured providers in\nplace — repair in place is the default, and `cartographer reconnect` is the explicit rebuild for\nwhat an incremental sync cannot see. Only already-open agent sessions need restarting. See `docs/deployment.md` §Upgrades, schema migration, and repo growth.\n\n`connect` with no flags in a TTY opens an interactive form (server URL, server\nname, token env var, auth) instead of the flag defaults; pass `--no-input` to\nforce the non-interactive behavior. Once connected:\n\n```bash\ncartographer status    # drift check and client/server version check after upgrades; exit 0 in-sync / 1 drift / 2 error\ncartographer sync      # re-apply after drift\ncartographer doctor    # read-only diagnosis of the client configuration: residues, drift, missing triggers\ncartographer reconnect # rebuild a client configuration from scratch, preserving every setting\n```\n\nFor local stdio use (a single KB, no service, typically for development) or a manually-configured\nHTTP server, see `serve --kb <path> --init` in `docs/deployment.md` — the native-service path above\ncovers everyday use.\n\n## Configuration\n\n| Environment variable | Default | Description |\n|---|---|---|\n| `CARTOGRAPHER_KB` | — | KB path(s) (single, or multiple comma-separated) |\n| `CARTOGRAPHER_DATA` | — | Directory whose subfolders are auto-discovered KBs |\n| `CARTOGRAPHER_HTTP` | — | HTTP address (e.g. `:39273`). Absent = stdio only |\n| `CARTOGRAPHER_AUTH` | auto | `true` / `false` / unset (auto on HTTP) |\n| `CARTOGRAPHER_TOKENS` | — | Comma-separated bearer tokens |\n| `CARTOGRAPHER_GIT_AUTOCOMMIT` | `true` | One git commit per write operation |\n| `CARTOGRAPHER_GIT_SYNC` | `true` | fetch/pull-rebase + push on `origin` around each write |\n| `CARTOGRAPHER_AUDIT_LOG` | — | Audit log file path |\n| `CARTOGRAPHER_AUDIT_KEY` | — | Ed25519 key for audit signing |\n\nFull list with CLI flags and defaults → [`docs/deployment.md`](docs/deployment.md).\n\n## Building and testing\n\n```bash\nmake build         # → bin/cartographer\nmake test          # Unit tests (go test ./...)\nmake smoke         # stdio smoke test\nmake smoke-http    # operator-level HTTP smoke test (creates temp KBs via curl)\nmake e2e           # deterministic HTTP/CLI end-to-end scenarios\n```\n\nThe E2E suite drives the compiled binary through HTTP, CLI, filesystem and real\ntemporary git remotes. It is deterministic, requires no model credentials and\nruns in CI. Full strategy → [`docs/testing.md`](docs/testing.md).\n\n## Project structure\n\n```\ncmd/cartographer/   # single binary: server (serve), client (connect/status/sync/kb/service), TUI\ninternal/           # okf, kb, mcpserver, search, sqlindex, lint, gitx, audit, auth, embed,\n                    # skill, sops, configurator, provisioning, agents, clientconfig, client\ndocs/               # full documentation (docs/index.md is the map)\ntest/               # deterministic HTTP smoke and cross-component E2E tests\n```\n\nPackage-by-package map, with what each one owns → [`AGENTS.md`](AGENTS.md) §Code map (kept next to\nthe contributor instructions so there is a single copy to keep true).\n\n## Documentation\n\nBrowsable at **[beppetemp.github.io/cartographer](https://beppetemp.github.io/cartographer/)** — same content as `docs/`, rendered.\n\nThe full index lives in [`docs/index.md`](docs/index.md). Main entry points:\n\n- [`docs/overview.md`](docs/overview.md) — vision, guiding principles, architecture\n- [`docs/data-plane.md`](docs/data-plane.md) — KB model, hierarchy, OKF\n- [`docs/control-plane.md`](docs/control-plane.md) — Go server, MCP tool API\n- [`docs/concurrency.md`](docs/concurrency.md) — single-writer, git sync, conflicts\n- [`docs/deployment.md`](docs/deployment.md) — topologies (local service / k8s / multi-server), backup, env vars\n\n## Contributing\n\nIssues and PRs are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the build/test loop, the\nPR flow (squash-merge, conventional titles, docs updated in the same PR), and how to find your way\naround the codebase. Cartographer is a personal project maintained on a best-effort basis: no\nresponse-time SLA. For security reports, see [`SECURITY.md`](SECURITY.md).\n\n## License\n\nReleased under the Apache License 2.0. See [`LICENSE`](LICENSE).\n",
  "bytes": 17154,
  "sha": "6399c3f5547988921b55454516b116040dc4d43ed1f7fbb8cc27f31c2e6bb54d",
  "repo_slug": "beppetemp/cartographer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_beppetemp_cartographer_c25009e3/readme"
}