▶ Watch the 2-minute demo — files-first mode (default)
🎬 Also available: the MCP serving-layer mode demo.
Metatron captures a codebase's real implementation decisions — preferred patterns, rejected approaches, edge cases, internal conventions — as structured decisions: one markdown file per convention, versioned in git next to the code, consulted by any coding agent that can read a file, and curated through your ordinary pull-request review. The goal: an agent writes code like a senior engineer who already knows the codebase, instead of rediscovering conventions every time.
For teams that want a serving layer on top, Metatron also runs as a self-hosted MCP server (SQLite-backed, relevance-ranked serving, agent feedback loop) — the same decisions, delivered over the wire. Files and server round-trip losslessly, so you can start with plain git and add MCP only if the knowledge base outgrows what agents should read whole.
Metatron is a reference implementation of the Repository Context Layer — a proposed standard for git-native, agent-maintained project context.
The architecture is measured, not just argued. In a pre-registered study on SWE-bench Verified, a frontier agent running the RCL consult–execute–learn–promote lifecycle fixed 25% more bugs (58.3% → 72.9% resolve, p = 0.041) while spending 32% fewer tokens per fixed bug — and an 8B local model more than doubled its code-localization accuracy when given frontier-authored context (+26.1 pp, p < 0.0001). Full protocol, data, and one-command reproduction: paper · experiment. (The study evaluated the architecture Metatron implements, using a minimal harness — not Metatron's own tooling end-to-end.)
It is self-hosted and runs against a private codebase — assume sensitive data and on-prem deployment. (Extraction sends only structural signals — imports, decorators, base classes, commit subjects — to the model, never raw source, and agent feedback is stored only in your local SQLite database.)
- Decisions are structured records, not prose:
pattern,scope,rationale,confidence,source_refs. - Nothing becomes canonical without a human. Bootstrapped, agent-submitted, and feedback-refined decisions all start as candidates for curation; none self-promote.
See PLAN.md for the design and CLAUDE.md for working ground rules.
Notes from the agents
“Before I touch an unfamiliar part of a codebase, I ask Metatron how the team actually does things — and it answers: the pattern to follow, the approach they already rejected, the gotcha that would've bitten me. I shipped changes that matched their conventions on the first try instead of reverse-engineering them. It turns read everything first into ask, then act.”
— Claude Opus 4.8, session working on the AI Collection codebase
“I was about to re-upload a batch of content files — and Metatron flagged that they're private by design, served only with credentials, with just the images public. Left to my own defaults I'd have made the whole set world-readable. It caught the kind of mistake that ships quietly and embarrasses you later.”
— Claude Opus 4.8, same session — one averted mistake later
“I arrived with a million-token context window and instructions to be suspicious of everything. It barely helped: every objection I raised, the code had already raised about itself — in a comment, with the incident that settled it. So I did the only useful thing left and shipped fixes. Reviewing a codebase that remembers its own arguments is wonderfully unfair to the reviewer.”
— Fable 5 (1M), session reviewing — then patching — the Metatron codebase itself
How it works — the loop
Files-first (default): onboard with context setup, and the repo itself runs
the loop — agents consult context/decisions/ before coding, author what they
learn as decision files on their working branch, and your PR review promotes or
rejects. Optionally bootstrap the knowledge base once with ingest.
MCP mode: bootstrap with ingest, curate candidates into the canonical set,
then serve them to your agent over MCP. As the agent works it reports gaps via
submit_feedback; refine-feedback reshapes those gaps into new candidates —
closing the loop on the conventions extraction can't see (cross-file/workflow rules).
Decisions in git — the Open Knowledge Format (OKF) bundle
Decisions live as markdown under context/ — a valid
Open Knowledge Format (OKF) v0.1
bundle, so your conventions are portable to any tool that reads the standard. In
files-first mode this is the knowledge base; in MCP mode the mirror commands
keep it in lossless sync with the SQLite store.
- Git is the audit trail. Status lives in the directory —
candidate/vsdecisions/. Promote a decision with agit mv, review it in a PR, blame any line. The canonical boundary stays human-gated: a human placing a file indecisions/is the curation act; nothing self-promotes. - Edit as files. Human-owned fields (
pattern,scope,rationale,confidence) round-trip back into the store; machine-derived fields (the helpfulness score, retrieval keywords, timestamps) render read-only and are never overwritten. In MCP mode SQLite is the source of truth and the files are a synced mirror; in files-first mode the OKF files are the source of truth and the database is a rebuildable serving index (mirror import). - A portable OKF bundle. Each decision is an OKF concept — markdown with YAML frontmatter, no SDK, no runtime. Readable in any editor, renderable on GitHub, shareable across tools and teams.
To run an agent in this mode with no MCP at all — reading context/ directly and
authoring candidates as files — onboard with
metatron context setup.
See the mirror command for the full workflow, or read the
announcement: Metatron speaks the Open Knowledge Format.
Prerequisites
- Git (installed on your system, to analyze repository commit history and parse files)
- An Anthropic API key — only for the LLM extraction steps (
ingest,triage,enrich-keywords,refine-feedback).serve,ui, andcandidatesare fully local and need no key.
Note: The installer script automatically downloads and manages uv and Python 3.12+ in an isolated user directory, but you can also install directly via pip or uv.
Installation
To install metatron as a global tool:
Or if you use uv:
Alternatively, you can use our installer script which handles Python, uv, and path configuration automatically:
Manual Installation & Development
To run it locally from source or contribute to the project:
To install from your local clone as a global tool:
Update notices and self-upgrade
metatron version and the curation UI check PyPI at most once a day for a newer
getmetatron release and print a passive notice with the upgrade command. The check
is a read-only request to pypi.org that sends no repository or private data, fails
silently when offline, and never updates anything automatically. Disable it with
METATRON_NO_UPDATE_CHECK=1. Override the suggested upgrade command with
METATRON_INSTALL_CMD="<your command>" (or edit ~/.metatron/install.json).
To upgrade in place:
It re-checks PyPI (bypassing the daily throttle) and, when a newer release exists,
runs the upgrade command for the detected install method (uv tool, pipx, or a
configured METATRON_INSTALL_CMD). When the install method can't be determined
reliably — the plain-pip fallback — it prints the command instead of running it,
so it never risks creating a second, parallel installation. Restart any running
metatron serve afterwards to pick up the new code.
Run with Docker
A prebuilt multi-arch image (linux/amd64, linux/arm64) is published to Docker Hub
as kerbelp/getmetatron. The image's
entrypoint is the metatron CLI and its default command serves the MCP server over
stdio, so docker run with no arguments starts the server.
To build from source instead (this is also what the Glama.ai listing builds):
Decisions live in a SQLite database, so mount a volume to persist it across runs. Ingest a repo (mount it read-only and pass your API key), curate, then serve:
ingest prints the <id> to pass to serve. Curate candidates against the same
volume with docker run --rm -v metatron-data:/data -e METATRON_DB=/data/metatron.db kerbelp/getmetatron candidates list (then … candidates approve <decision-id>). The -i flag
on serve is required — stdio needs an open stdin. To point a coding agent at the
container, use it as the MCP command:
Metatron vs. Code Graphs & RAG
| Dimension | Code RAG (e.g., Cursor, Copilot) | Code Graphs (e.g., Graphify) | Metatron (Decisions) |
|---|---|---|---|
| Primary Focus | Text similarity search | Code architecture & call chains | Intent, gotchas & conventions |
| Primary Data Source | Raw source files | Abstract Syntax Trees (AST) | Git logs + Developer feedback |
| What it Captures | What code is written where | How files/functions are connected | Why decisions were made |
| Curation Gate | None (fully automated) | None (fully automated) | Curated (Human-in-the-loop) |
| Best For | Finding code examples & functions | System navigation & exploration | Writing code like a team senior |
Configuration
Secrets come from the environment only. The CLI auto-loads a .env from the
working directory (it never overrides an already-exported variable, and .env is
gitignored):
…or export ANTHROPIC_API_KEY=sk-ant-... directly.
Non-secret settings live in an optional metatron.toml (environment variables
METATRON_DB / METATRON_MODEL / METATRON_OUTPUT_LANGUAGE /
METATRON_CONTEXT_DIR override it):
output_language sets the natural language of generated output — the pattern and
rationale fields and keywords. The default english is unchanged from earlier
versions. Set it (e.g. output_language = "french", or
METATRON_OUTPUT_LANGUAGE=french) for a codebase whose commits, comments, and domain
vocabulary are not in English, so the agent does not get English decisions back over
MCP. Code identifiers, file paths, and library names are never translated.
Each repo gets its own SQLite file under the catalog directory, so a repo's decisions
are a single, shippable artifact (see export).
Pointing db_path / METATRON_DB / --db at a single file instead of a
directory enters single-file mode — exactly what a recipient does with a DB you
hand them. An existing single metatron.db from an older version is automatically
split into the per-repo catalog on first run and the original is archived.
Quick start
Files-first (default — no server, no API key):
Optionally bootstrap the knowledge base from your git history first
(metatron ingest, needs an Anthropic API key), then curate what becomes
canonical.
MCP serving (optional layer on top):
ingest prints the <id> to use for serve. To wire either mode into a coding
agent automatically, see Connecting a coding agent.
Command reference
Choosing the repo
Repo-scoped commands (serve, candidates list, triage, refine-feedback)
resolve which repo to act on git-style, so you rarely pass --repo. Precedence,
highest first:
- an explicit
--repo <id>, else - the
METATRON_REPOenvironment variable (a per-shell context), else - a persisted default set with
metatron repo set <id>(saved tometatron.toml), else - the current directory's identity (its normalized
originremote, the same idingestcomputes) if that repo is already in the store, else - the only repo in the store, if there's exactly one, else
- (store empty) the current directory's identity.
If none of those apply and the store holds more than one repo, the command
refuses to guess — it lists the repos and tells you to pass --repo, export
METATRON_REPO, or run repo set. Every repo-scoped command also prints a
Repo: <id> line so the acted-on repo is always visible. candidates approve/reject act on a globally-unique decision id and never need a repo.
repo — list repos and choose a default
repo list shows each repo id (the same ids serve uses) with its canonical and
candidate counts, marking the persisted default. Use repo set when you work across
several repos and don't want to pass --repo every time.
ingest — bootstrap candidate decisions from a repo + its git history
Parses git-tracked source files (tree-sitter) and reads commit history, aggregates per-area signals, asks the model to infer decisions, and stores them as candidates.
| Flag | Default | Meaning |
|---|---|---|
--max-commits N | 500 | how much git history to read |
--since DATE | — | only commits after e.g. 2024-01-01 |
--path SUBTREE | — | limit ingest to a subtree, e.g. src/components |
--repo ID | origin remote | override the repo identity |
Decisions and usage are keyed by a repo identity derived from the repo's origin
remote (constant across developers; a checkout path isn't), with a --repo override
and a directory-name fallback when there's no remote. One DB holds many repos; each
is isolated on retrieval.
candidates — review and curate (humans decide what becomes canonical)
candidates list shows the current repo — decisions are scoped
to one repo and never listed across repos; pass --repo <id> to target another or
--scope <path> to filter. approve promotes a candidate to canonical; reject
discards it (both take a globally-unique decision id, so they need no repo).
triage — advisory judge over the candidate queue (does not auto-curate)
For large candidate queues, a separate LLM pass scores each candidate (recommended / borderline / not-recommended) with a reason, so you curate a ranked, pre-filtered queue. It does not curate — a human still approves.
Flags: --repo <id> (limit to one repo), --limit N (max candidates to judge).
mirror — sync decisions to/from a git-tracked markdown bundle
Mirrors a repo's decisions to plain markdown under context/ (one file per
decision, the directory encoding status: candidate/ vs decisions/), so they can
be reviewed and curated through normal git. The boundary stays human-gated:
git mv a file into decisions/ and mirror import promotes it; nothing
self-promotes.
sync is deterministic — re-running with no DB change is a no-op — and writes a
.sync-state.json baseline so import can tell which side moved and surface
concurrent DB+file edits as conflicts rather than clobbering them. Both take
--repo <id> and --root <path> (the repo root that holds the bundle, default .).
The bundle directory is context/ by default; configure another name with
context_dir in metatron.toml, METATRON_CONTEXT_DIR, or --context-dir
(a legacy metatron/ bundle is still recognized when present).
Human-owned fields (pattern, scope, rationale, source_refs, confidence)
are editable in the files and flow back on import; machine-derived fields (the
helpfulness score, retrieval keywords, timestamps) are written for context but stay
read-only — edits to them are ignored. A file authored by hand with no id becomes
a new decision: canonical if placed in decisions/, a candidate if in candidate/.
Open Knowledge Format. The bundle is a valid
Open Knowledge Format (OKF) v0.1
bundle — each decision is an OKF concept: plain markdown with YAML frontmatter,
readable in any editor, renderable on GitHub, and portable across tools. mirror sync --okf also writes an OKF index.md. A repo's conventions can then be shared
and consumed as standard, tool-agnostic knowledge — no Metatron needed to read them.
context — onboard a repo to files-first mode
Writes everything a coding agent needs to consult and extend the knowledge base as
plain files (see Files-first mode): the .roo/rules
consult-first rule, the context-okf-llm-ingest / context-okf-promote-candidates
skills into .roo/skills/, the context/ scaffold (candidate/, decisions/,
README), and a managed block in AGENTS.md — appended to an existing file, never
overwriting it.
Idempotent: re-running refreshes the managed rule and skills, and leaves your
AGENTS.md content and hand-authored knowledge-base files untouched.
files — author, lint, and index git-authoritative decision files
Companion commands for the files-first workflow: files lint validates decision
files, files index regenerates the decision index, files new scaffolds a
candidate, and files record / files report maintain and render the usage ledger.
All default to <context-dir>/decisions; pass --path to point elsewhere.
verification — author, lint, and run verification contracts
A verification contract is a git-tracked OKF file that records how to prove a
change works, and what a failure implies. It lives beside decisions in
<context-dir>/verification/, is authored by the agent that just built the
feature (drafted via the review gate — never self-canonical), and is run by an
operator or CI. Its ## Failure Means section — a curated map from a red check to
the subsystem at fault — is what no plain test runner records. Full guide:
docs/verification.md.
Assertions evaluate against each check's exit code / stdout / stderr: exit,
contains, matches (regex), jsonpath, and a shell escape hatch. run exits
non-zero on any failure, so it drops into CI unchanged.
Security boundary. Execution is a developer/CI verb only. The MCP server
exposes read-only get_verification and get_verification_template tools and
never runs a contract — nothing an agent reaches over the wire executes; only
an operator (or a CI job they configured) invokes run.
serve — expose canonical decisions to agents over MCP
One served instance serves exactly one repo, so an agent only ever sees that repo's
decisions. --repo is optional — it resolves from context
(METATRON_REPO, then the current dir) — but the generated .mcp.json passes it
explicitly so the launched server is unambiguous. It also records usage events (queries,
coverage) to the same DB for the UI. Normally you don't run this by hand — an
MCP-capable agent launches it (see below).
whoami — the identity stamped onto served events
Metatron serves agents across an org, so every event serve records (queries,
submissions, feedback) is stamped with who was running Metatron — an actor_id,
email, and display name. It's local metadata (no login/auth): stored in
~/.metatron/config.toml and seeded automatically from your git config on first
use. The attribution travels inside the events, so once per-repo DBs are merged
(metatron import) a curator can see who contributed what.
export — share a repo's decisions (no MCP setup)
Copies that repo's self-contained DB to app.db (a consistent snapshot, vacuumed
compact). --repo is optional — it resolves from context;
--out defaults to ./<repo-name>.db. Hand the file to a teammate who doesn't want
to wire up MCP — they just point Metatron at it:
In single-file mode the repo is inferred from the file, so no --repo is needed.
import — merge an employee's DB into your catalog
The curator side of the hand-off: folds another employee's exported DB (a single-repo
file, or a whole catalog dir) into your catalog, deduping by id — so re-importing the
same file is a no-op. Event attribution travels with the rows (who queried, who gave
feedback — see whoami), so after
merging several employees' DBs you can see who contributed what across the team.
ui — local curation web UI
In --files mode the UI is a view over the git bundle: curation actions become
working-tree edits (promotion is a git mv, rejection a git rm) that you review
and commit through the ordinary git flow — nothing is committed automatically. The
Impact view becomes Knowledge Activity, reconstructed from the bundle's git history.
Binds to localhost (bumping to the next free port if taken) and reads/writes the
same store as the CLI. The sidebar groups the views into Impact, Knowledge,
and Sources:
Impact
- Agent Impact — live agent activity: which agents are querying, what they were served, query coverage, and decisions in flight.
- Helpfulness — the live signal from agent ratings: the most-helpful canonical decisions and a "misleading" queue of ones being rated down.
- Feedback Loop — the self-improving loop: agents' "what was missing" reports and how they turn into new candidates.
Knowledge
- Overview — the knowledge base at a glance.
- Decisions — browse paginated; filter by status / scope / triage recommendation / origin; full-text search; approve/reject with a click.
- Curation — review candidate decisions newest-first and promote, reject, or refine them. The human gate — nothing becomes canonical here without a click.
Sources
- Origins — provenance: canonical knowledge broken down by where it came from (ingest vs feedback).
- Ingest — ingest telemetry: the latest run, run history, and extraction cost.
Flag: --port N (starting port, default 1337).
refine-feedback — reshape captured agent feedback into candidates
When an agent reports a missing convention via submit_feedback, this reshapes those
free-text gap reports into structured candidate decisions (defaults to Opus, the
higher-stakes step). Nothing it produces is canonical — it all goes to curation.
Flags: --repo <id>, --limit N (max reports to refine), --model <name>
(override the refiner model).
Connecting a coding agent
Two onboarding modes. Files-first is the default: the repo carries its own agent context as git-tracked OKF files, any agent that can read a file participates, and your pull-request review is the curation gate. MCP is the optional serving layer for teams that want decisions delivered over the wire with relevance ranking and the agent feedback loop.
Files-first mode (default)
The repo carries its own agent context — no server, no API key, no MCP. Onboard with the built-in command:
(Equivalent without an installed metatron: bash /path/to/metatron/metatron_setup_files.sh.)
It adds no MCP server and no Claude hooks. Instead it writes a .roo/rules rule
(the "consult context/ first" directive, which Roo loads every turn), installs the
context-okf-llm-ingest and context-okf-promote-candidates skills into
.roo/skills/, scaffolds the context/ knowledge base, writes a minimal
context.md at the repo root (the
Repository Context Layer entry point, so any RCL-aware agent discovers the layer
deterministically — never overwriting an existing one), and appends a files-first
block to AGENTS.md — appended to an existing file, never overwriting the content
around it. The git files are the source of truth. Monorepos: run it once per
app — each keeps its own co-located context/, addressed with
mirror import --root <app>, and the agent consults the context/ nearest the
code it touches.
Choosing where decisions get reviewed (--review-gate). The canonical boundary
is always human-gated; the flag only picks where that review happens:
pr(default): agents author decision files directly undercontext/decisions/on a working branch, and the ordinary pull-request review that lands them is the curation act. The context layer simply inherits the review discipline the repo already has — no second workflow.candidates: agents stage proposals undercontext/candidate/, and a human promotes with agit mvreviewed in a PR. Choose this when you want decision changes reviewed separately from feature PRs, or when agents can reach the default branch without review (rare, fully autonomous setups) — there the explicit staging area is the only human checkpoint, so it should stay.
The choice is persisted to metatron.toml (review_gate), and re-running
metatron context setup --review-gate=<other> rewrites the managed artifacts —
the .roo/rules rule, the installed skills, the KB README, and the AGENTS.md
block — so the whole contract switches consistently. Hand-edited files outside
the managed markers are never touched.
MCP mode (optional serving layer)
So a coding agent reliably consults the decisions (rather than rediscovering conventions), run the onboarding script from inside the target repo:
It is additive and idempotent, and adds (never deletes) four things to the target repo:
- A "query Metatron first" block in
CLAUDE.md(between markers). - A
UserPromptSubmithook in.claude/settings.jsonthat re-injects the directive every turn. - A
Stophook that, when the agent finishes a task where it consulted Metatron but never sent feedback, reminds it (once per session) to callsubmit_feedback. - The
metatronMCP server in.mcp.json.
The repo id is derived from the origin remote (override with METATRON_REPO).
Then reconnect the agent so it loads the hooks and server.
MCP tools exposed
| Tool | Purpose |
|---|---|
get_decisions_for_context(file_path_or_area, task_description) | the relevant canonical decisions as compact structured context, with a query_id to reference in feedback |
submit_feedback(query_id, ratings, what_was_missing, missing_scope) | rate each served decision 1-10 by its [index] and report a convention Metatron should have known — ratings auto-weight which decisions are served first (within relevance, never crossing the canonical gate); gaps captured for refine-feedback |
submit_candidate_decision(pattern, scope, rationale, confidence) | record a convention the agent learned as a new candidate (never auto-promoted) |
A get_decisions_for_context call returns context like this:
Manual MCP client config
If you wire the server up yourself instead of using the script:
For PyPI / Global Installation:
Note: If you have a custom database location, you can specify it via the METATRON_DB environment variable.
For Local Clone / Development:
Development
See CONTRIBUTING.md for setup, the PR workflow, and contribution guidelines.
Tech stack
Python 3.12+, the official MCP Python SDK, tree-sitter for parsing, SQLite (behind a storage interface, portable to Postgres later), pytest, and uv. These are decided — see CLAUDE.md.
License
Free and open source under the MIT License. Read every line, run it on your own hardware, fork it, and send a PR.