kerbelp/metatron

🎬 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 has been evaluated in a pre-registered study on SWE-bench
Verified.** On tasks sharing relevant project constraints, an 8B local model's
code-localization accuracy rose from **21.1% to 47.2%** with frontier-authored
context (+26.1 percentage points, p “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/ vs
decisions/. Promote a decision with a git mv, review it in a PR, blame any line.
The canonical boundary stays human-gated: a human placing a file in decisions/
*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,