Google's Open Knowledge Format

Back in June, Google Cloud published something called the Open Knowledge Format, or OKF. It landed pretty quietly for what it is, which is a serious attempt to standardize how you hand curated context to an AI agent. I’ve been using it for about a month in a project of mine, and I’ve come around to thinking it’s one of the more sensible ideas to come out of the whole agent gold rush. So here’s an overview of what it is, with a bit of my own experience mixed in to keep it honest.

The problem it’s trying to solve

If you’ve built anything on top of a foundation model, you’ve run into this. The model is smart, but it doesn’t know your stuff. It doesn’t know that your orders table means completed orders only, or that the payments service has a weird retry quirk, or that this one deprecated API is still load-bearing for exactly one internal tool. That knowledge exists, but it’s scattered across wikis, metadata catalogs with their own APIs, shared drives, code comments, and the heads of your senior engineers.

Google’s framing of the problem is that every agent builder ends up solving the same context-assembly problem from scratch. You write some glue to pull docs from here, schema from there, a runbook from somewhere else, and stitch it into a prompt. Everybody’s doing it, and nobody’s doing it the same way, so none of it is portable.

The insight underneath OKF is what Andrej Karpathy called the LLM-wiki pattern. The reason people abandon personal wikis is the bookkeeping: updating cross-references, keeping things consistent, touching fifteen files when one fact changes. That bookkeeping is exactly the kind of tedious, mechanical work that an LLM is good at and doesn’t get bored doing. So the idea is to keep a shared markdown library that agents help maintain and humans curate like code.

What the format actually is

Here’s the part I like: the whole v0.1 spec fits on a single page. There is very little to it.

An OKF bundle is just a directory of markdown files. Each file is one concept. A concept can be anything you’d want an agent to know: a table, a dataset, a metric definition, a runbook, an API, a playbook. Each file has a small block of YAML frontmatter for the structured fields, followed by a normal markdown body for everything else.

There is exactly one required field: type. It’s a short string that says what kind of concept the document is, so a consumer can route or filter on it. That’s the only thing the spec forces you to include. Everything else is recommended but optional:

• title - a human-readable name
• description - a one-sentence summary
• resource - a URI pointing at the actual underlying asset
• tags - a list for cross-cutting categorization
• timestamp - ISO 8601 datetime of the last change

You’re free to add your own fields, and consumers are required to tolerate ones they don’t recognize. A minimal concept looks like this:

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Globally unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |

There are two reserved filenames. index.md is a directory listing, meant for progressive disclosure so an agent can walk the hierarchy without loading everything at once. log.md is a chronological change history, newest first, keyed by date. Concepts link to each other with plain markdown links, and bundle-relative links starting with a slash are preferred. A link from one concept to another is treated as a relationship, and the nature of that relationship comes from the prose around it rather than any special link syntax.

Conformance is deliberately loose. A bundle is valid if every non-reserved markdown file has parseable frontmatter with a non-empty type, and any index.md or log.md follows the expected shape. On the consuming side, you’re expected to gracefully handle missing optional fields, unknown types, broken links, and missing indexes. The whole thing is built to degrade politely.

The design principles are worth restating because they’re the point: it’s just markdown, just files, and just YAML frontmatter. No proprietary account, no SDK, no platform. It’s a format, not a service. That’s the whole pitch, and I think it’s the right pitch.

How I’ve been using it

The reason I paid attention to OKF at all is that I had accidentally built something close to it, and worse, before the spec existed.

I run a background orchestrator that keeps a fleet of AI coding agents busy across my repos around the clock. It ideates work, opens PRs, and reads feedback. For any of that to be useful, the agents need to know things about each repo: what the stack is, where the bodies are buried, what my standing preferences are. So I’d been having the agents write those facts down into markdown as they went. It worked, but it was ad hoc, and I had no way to check whether the pile of notes was actually well-formed.

When OKF came out I reshaped the whole knowledge base to conform to it, and a few things immediately got better. Each repo became its own sub-bundle with an auto-generated index.md whose resource field points at the repo and whose links fan out to concept docs like codebase.md, gotchas.md, and preferences.md. Those links became the graph. The agents populate the docs; a validation step checks conformance and gives me a report. A couple hundred docs, all conformant, and I can actually trust that now.

The type and tags fields turned out to matter more than I expected. Once I normalized the tags into a real vocabulary, I could build cross-repo rollups mechanically, with no LLM in the loop at all. Give every doc structured frontmatter (language, frameworks, key dependencies, a handful of topical tags) and you can derive a stack matrix, a security-notes digest, and a “see also” web across repos just by parsing files. That’s the quiet superpower of the format: because the structure lives in plain YAML, a lot of the synthesis you’d reach for a model to do, you can just do with a script.

The honest part: I underused resource and the cross-linking-as-relationship idea at first, and my early bundle was flatter and less useful than it should have been. The graph only started paying off once I made the indexes carry real links and gave the tags a consistent shape. That’s on me, not the spec, but it’s worth flagging if you’re going to try it. The format gives you the affordances; you still have to use them.

Worth a look

OKF is explicitly a v0.1, a starting point rather than a finished standard, and Google’s been clear that it’ll evolve as more producers and consumers show up. But the core bet feels correct to me: the unit of AI context should be a plain file you can read, grep, render on GitHub, and hand to any model, with no vendor in the middle. After a month of running my own knowledge base on it, I’m not looking to go back to the pile of unstructured notes.

The spec, reference implementations, and sample bundles live in the GoogleCloudPlatform/knowledge-catalog repo, and the announcement post is a good read if you want the full motivation. It’s a one-page spec. You can absorb the whole thing over a coffee, which is more than I can say for most standards.