What is the Open Knowledge Format?

Every team has a second codebase. Not the one in src/, but the one in people's heads: why the billing service exists, what "active user" actually counts, which schema decision looks wrong but was made on purpose.

And it is not only an engineering archive: it holds what the company knows about its competitors, the survival guide that carries the on-call through an incident, the feature catalog that lives in the PM's head. That second codebase decides how fast a new hire ships, how well an AI agent works on your repo, and how many times the same question gets answered in chat. In most teams it has no home.

The Open Knowledge Format (OKF) is a specification for giving it one.

The shape of the problem

Project knowledge today lives in four places at once. A wiki that was accurate eight months ago. A CLAUDE.md or AGENTS.md that mixes standing instructions with bits of context. An agent's private memory, which no colleague can read or review. And people, who go on vacation, switch teams, and leave.

The result is the same everywhere: an agent re-derives your architecture from scratch every session, and a human asks in chat what a metric means for the third time this quarter. The knowledge exists. It just is not anywhere a tool or a teammate can reliably find it.

What OKF actually is

OKF is an open, vendor-neutral format published by Google Cloud in 2026. The whole idea fits in one sentence: a knowledge base is a directory of Markdown files with YAML frontmatter, and each file is one concept.

That directory is called a bundle. There is no database, no proprietary editor, no export step. A bundle lives in your repo like any other folder, which means it is versioned with the code it describes, reviewed in pull requests, and diffable when it changes.

Here is an entire bundle, nothing hidden:

docs/
├── index.md                  # the map: what lives here, one line per entry
├── log.md                    # dated history of what changed in the knowledge
├── services/
│   ├── index.md
│   └── billing.md            # one concept = one Markdown file
├── tables/
│   ├── orders.md
│   └── customers.md
└── decisions/
    └── payment-id-dedup.md

That is the whole trick: Markdown files under folders, plus a small set of structure rules that make those folders self-describing. The spec itself puts it plainly: "If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it." A file's path is its identity (tables/orders.md is the concept tables/orders), folders group concepts however makes sense for your domain, and a bundle travels as a git repo, a zip, or just a folder inside the repo you already have.

If you have used Obsidian, or the wiki conventions people now write for LLMs, this will feel familiar on purpose. The difference is that OKF is specified: a short, written list of rules instead of a house style, and that is exactly what lets tooling validate a bundle and lets an agent consume it without guessing.

A concept looks like this:

---
type: BigQuery Table
title: Orders
description: One row per confirmed order, deduplicated by payment id.
tags: [billing, core]
---

Joined with [customers](/tables/customers.md) for revenue reports.
The 2023 dedup incident is why payment_id is the key, not order_id.

The only hard requirement is that frontmatter block with a non-empty type. Everything else, titles, descriptions, tags, timestamps, is recommended rather than mandatory, and a consumer must tolerate what is missing. The spec is deliberately small enough to read in one sitting.

Think of the frontmatter as the spine and back-cover blurb of a book. You can walk the shelf, read the spines (type, title, a one-line description, tags), and decide which books to pull down, without opening a single one. That is what makes a bundle cheap for an AI to use: most questions are answered by the spines plus two or three opened files, not by reading the whole library.

The graph you never declare

Here is the part I find elegant. Concepts link to each other with plain Markdown links: [customers](/tables/customers.md). Files are nodes. Links are edges. So a bundle is a knowledge graph, without a single line of graph configuration. You never declare relationships in some sidecar file; the graph emerges from how the writing already refers to itself.

Two more reserved files give a bundle structure at scale. An index.md per directory acts as a map, so a reader (human or agent) can descend from an overview to detail instead of loading everything at once. The spec calls this progressive disclosure, and it is what lets a bundle outgrow a context window without becoming useless to an agent. And a log.md keeps a dated history of what changed in the knowledge itself.

How it compares to the places knowledge lives now

Each existing home holds something real. None of them was built for curated, durable team knowledge:

The last row is the interesting one. A wiki has no detector for its own rot. A bundle does: because the format is structured, a tool can tell you that a concept is orphaned, that three files link to a page nobody wrote yet, or that a "current" doc has not been touched since the schema changed. Drift becomes findings you can gate a CI run on, instead of a surprise during onboarding.

Not just for code

The folder tree above should make something obvious: nothing in the format is code-specific, and some of the biggest wins live outside the codebase. A competitor file that sales and product both trust. An incident survival guide the on-call actually finds at 3 a.m. A feature catalog that tells the PM what exists, why, and for whom. Onboarding notes, pricing rationale, the compliance checklist. The whole company benefits from well-curated content, and every one of those is just a concept file in a folder.

It reaches beyond companies too: a legal practice's playbooks, an SEO consultancy's research, an accountant's closing procedures. If the knowledge can be written as Markdown, it can be a bundle, and any agent that understands OKF can work with it.

That cuts the other way too. A well-curated bundle is an asset in its own right: expertise, packaged in a format any tool can consume, portable across whatever agent your team runs next year. Curating one well is real work, and it is the kind of work that compounds.

Where the tooling comes in

A format on its own is just a promise. I maintain okf-gem, a complete OKF toolkit that ships as one Ruby gem and runs 100% local. It is three tools in a trench coat:

• An agent skill that teaches a coding agent (Claude Code, or any harness that reads skills) to author, curate, and consume bundles. The skill carries the judgment; it knows the spec so your agent behaves like an OKF expert instead of guessing.
• A CLI that does the mechanics. okf validate answers "is this a legal bundle?" exactly as the spec defines conformance. okf lint answers the softer question, "is it well curated?": reachability, completeness, freshness, provenance. Legal and well-curated are different questions, so they are different commands.
• A live graph server. okf server docs/ serves your bundle as an interactive knowledge graph in the browser: click a concept, read its Markdown, follow its links. There is a public demo if you want to click around one right now.

Nothing leaves your machine. There is no SaaS behind it, no telemetry, no account. Your knowledge stays in your repo, where it belongs. If you use Claude Code, a plugin installs the whole pack plus a hook that re-checks the bundle after every edit.

Start small, and smarter

You do not have to do the heavy lifting yourself. That is what the tooling is for: the okf-gem skill authors and curates bundles with the agent doing the writing while you stay the editor. You can even point it at a document you already have (/okf produce in your coding agent, or just ask the skill in plain words) and let it OKF-ify existing prose instead of starting from a blank file.

Use the skill to power the whole activity, whether that is adapting the documentation you already have or creating new concepts from code and conversations. Start with one document or a handful of concepts, run okf lint to see what the bundle asks for next, and let the flywheel take it from there.

The format is open, the spec travels with the gem, and the whole thing is plain files. If OKF ever disappears tomorrow, you are left holding a well-organized directory of Markdown. That is the worst case. I think that says a lot about the idea.