Metatron speaks the Open Knowledge Format

The feedback I kept hearing

Metatron has always stored decisions in a local database and let you curate them in a small web UI. The UI is good, but I kept hearing the same thing: I don't want another app to click around in. I live in my editor and my agent. Why can't these just be files?

It's a fair ask. Decisions are some of the most important text in a codebase — the pattern to prefer, the approach you already rejected, the native dependency that must never reach the browser. Text that important deserves to live where the rest of your engineering truth lives: in version control, with history, diffs, blame, and pull requests. Not locked behind a tool's screen.

What the Open Knowledge Format is

On June 12, 2026, Google Cloud published the Open Knowledge Format — OKF for short — an open specification for the knowledge that AI agents need to do useful work. Its premise is refreshingly small: a knowledge bundle is just a directory of markdown files with YAML frontmatter. No SDK, no runtime, no proprietary platform. If you can cat a file you can read it; if you can git clone a repo you can ship it.

Each file is a concept. It needs exactly one required field — type — and may carry any other fields the producer finds useful. That's the whole contract. The point of the standard isn't a rich schema; it's that knowledge written by one tool can be read by another without translation.

Your decisions, as an OKF bundle

One command mirrors a repo's decisions to disk:

metatron mirror sync --okf

You get a tree of markdown under metatron/, one file per decision, with the directory encoding status — candidates under candidate/, canonical decisions under decisions/:

metatron/
├── index.md                         # OKF directory listing
├── candidate/
│   └── prefer-zod-at-boundaries-…md
└── decisions/
    └── isolate-server-only-deps-…md

And each file is an OKF concept — readable in any editor, renderable on GitHub, indexable by any search tool. Here's what that sharp rule from the outage looks like as a concept document:

---
type: Metatron Decision
id: dec_01HZ…
scope: web/api
confidence: high
---

## Pattern
Native, server-only dependencies (e.g. `sharp`) must be structurally
isolated from client bundles — never rely on tree-shaking to keep them out.

## Rationale
Exporting a helper that transitively imports a server-only module pulls it
into the browser chunk, where its init throws. Make the import lazy so it
can never reach the client.

Git is the audit trail — and the editing surface

Because the bundle lives in your repo, the whole lifecycle becomes something git already does well. Reviewing a proposed convention is reading a diff. Asking who changed a decision and why is git blame. And the boundary that matters most in Metatron — what becomes canonical — stays human-gated, the way it always has:

git mv metatron/candidate/isolate-server-only-deps-…md \
       metatron/decisions/
metatron mirror import

Moving a file into decisions/ is the act of promotion. A human did it, deliberately, and it's recorded as a commit. Nothing self-promotes; no agent and no score can cross that line. You can also just open a file and edit the pattern or rationale — or ask your coding agent to — and mirror import applies the human-owned fields back to the database. Machine-derived fields (the helpfulness score, retrieval keywords, timestamps) ride along read-only, so an edit can't quietly overwrite them. The database stays the source of truth; the files are a faithful, two-way mirror.

Why this matters

I think knowledge should outlive the tool that captured it. If Metatron earns a place in your workflow, it shouldn't be because your decisions are trapped inside it — it should be because it's the best place to capture and serve them. Emitting a standard, open bundle is how I keep myself honest about that. Your conventions are yours: a portable OKF bundle you can read without Metatron, hand to another tool, or share across teams.

It also fits the shape of the product. Metatron's job is to give a coding agent a teammate to ask before it acts. The Open Knowledge Format is becoming a common language for exactly that kind of agent knowledge — so speaking it natively means the decisions you curate here can travel as far as the standard does.

It's live now. Point Metatron at a repo, run metatron mirror sync --okf, and watch your team's hard-won decisions become plain, portable, version-controlled files — without giving up the human-gated curation that makes them trustworthy. The docs have the details.