Why OKF
The case for knowledge as code.
Project knowledge drifts. It scatters across wikis and chat, and the parts that are written down quietly stop matching the code. This documentation drift is invisible to an agent, which reads the stale file and inherits the wrong assumption. The Open Knowledge Format gives that knowledge one home a tool can check. The fuller case is in Why okf-gem.
The problem
Project knowledge (why a service exists, what a metric really measures, the reasoning a schema encodes) lives scattered across wikis, code comments, and whoever happened to be in the room. An agent re-derives it every session. A new hire re-asks it every onboarding.
OKF is an open, vendor-neutral format published by Google Cloud in 2026. It gives that knowledge one durable home: a directory of Markdown files with YAML frontmatter, versioned next to the code it describes, read from the same file by people and agents alike. Each file is a concept; a directory of them is a bundle.
Compared to where knowledge lives now
Knowledge already has several homes near an agent, and each holds a different thing. None of the others is built for curated, durable team knowledge:
| OKF bundle | CLAUDE.md / AGENTS.md | Agent auto-memory | Wiki / Notion | |
|---|---|---|---|---|
| Holds | curated team knowledge | standing instructions | what one agent picked up | human docs |
| Versioned with the code | yes | yes | no | no |
| Portable across agents | plain Markdown + YAML | per-harness conventions | per-agent store | export needed |
| Typed and queryable | frontmatter + graph | prose | no | partially |
| Reviewed in PRs | yes | yes | implicit | rarely |
| Scales past one context window | progressive disclosure (okf index) | loaded whole | partially | n/a |
| Checked by tooling | validate + lint, exit codes for CI | no | no | no |
The last row is this gem's job. The other homes have no detector, so their drift stays invisible; a bundle's drift shows up as findings you can gate on in CI.
Why an open standard matters
A format only one tool understands dies with that tool. OKF is vendor-neutral by design: your bundles outlive okf-gem, and every tool anyone builds for the format makes every existing bundle more valuable. The spec itself ships inside the gem, so the version your tooling enforces is the version you can read.
Where the gem fits
okf-gem is the Ruby-native toolkit for the format, three tools in one install:
- the agent skill authors and curates bundles with judgment;
- the CLI validates, lints, and reads them deterministically;
- the graph server makes them explorable by humans.
All of it runs 100% local. No account, no telemetry, no upload: your knowledge stays in your repo.