Open Knowledge Format (OKF), Explained

Every team has the same problem. The thing your AI needs to be useful (what a metric actually means, the join between two tables, the runbook for an outage, why an old API was deprecated) lives in a wiki nobody updates, a Slack thread, a code comment, or a senior engineer’s head. OKF is Google’s answer: a boring, portable format for writing that knowledge down so an agent can find the exact piece it needs. The format is the whole point, and it is deliberately simple.

What Is the Open Knowledge Format?

Strip away the announcement language and OKF is three things you already know, glued together: markdown files, in folders, with a little YAML at the top. Google’s own framingis that this is “a format, not a platform.” It will never require a proprietary account to read or write. That restraint is the interesting part. The value of a knowledge format comes from how many tools speak it, not from who owns it.

A bundle of these files describes a domain. Concepts can be anything worth capturing: a table, a metric, a playbook, an API, a customer segment. The bundle is human-readable in any text editor and parseable by any agent, with no translation layer in between. That is the trick: one file serves both audiences.

Why Google Built It

Foundation models are smart in general and ignorant about your business in particular. They have read the internet; they have not read your data dictionary. Google calls this the context-assembly problem, and right now every team building an agent solves it from scratch: scraping a metadata catalog here, pasting a runbook there, hard-coding a join path somewhere else.

The insight is that the missing piece is not another service or a bigger context window. It is a shared format: a way to write knowledge once that survives moving between systems, lives in version control next to the code it describes, and reads the same to a person and to a model. Get the format right and the tooling on both ends becomes swappable. That is a familiar bet. It is the same one that made robots.txt, RSS, and markdown itself useful.

The Spec, in One Minute

The full v0.1 spec fits on a page. Here is the whole thing in two figures.

A bundle is a directory of markdown files. The folder structure is the map; each file is one concept, and its path is its identity.

sales/
├── index.md            # entry point
├── datasets/
│   └── orders_db.md
├── tables/
│   ├── orders.md        # a concept
│   └── customers.md
└── metrics/
    └── weekly_active_users.md

A concept is frontmatter plus a body. Exactly one field is required, type, which tells an agent what kind of thing it is looking at. A handful of optional fields (title, description, resource, tags, timestamp) stay structured so they can be queried. Everything below the frontmatter is ordinary markdown.

---
type: BigQuery Table        # the one required field
title: Orders
description: One row per completed order.
resource: https://console.cloud.google.com/…
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema
| Column      | Type   | Description            |
| customer_id | STRING | FK to [customers](/tables/customers.md). |

The quiet but important detail: concepts link to each other with normal markdown links. That turns a flat folder into a graph of relationships richer than the parent-child nesting of the file system. Two reserved filenames carry conventions: index.md for progressive disclosure as an agent walks the tree, and log.mdfor a concept’s change history. That is genuinely it. No compression scheme, no runtime, no required SDK.

The Idea Behind It: the LLM Wiki

If you have searched for LLM wiki and ended up here, that is why. The pattern keeps reappearing under different names: Obsidian vaults wired to coding agents, the AGENTS.md and CLAUDE.md convention files, repos full of index.md artifacts that agents read before doing real work, and “metadata as code” inside data teams. OKF is the attempt to give all of those a single shape, so a wiki one tool writes can be read by an agent another tool built. As Karpathy puts it, “LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass.”

OKF vs llms.txt vs AGENTS.md

These get lumped together because they are all “markdown an AI reads,” but they do different jobs. The cleanest way to think about it is as layers of the machine-readable web.

They stack. llms.txt is the one-page map pointing at what matters; an OKF bundle is the linked content behind the map; AGENTS.md is the in-repo instruction sheet for an agent doing work. None replaces another. If you only do one thing this quarter, a good llms.txt is still the higher-impact move for most websites.

Does OKF Affect SEO or AI Rankings?

This matters because the SEO world moved fast on OKF, and some of the takes blur the line. Be clear-eyed: a bundle on your site will not change your rankings this week, or arguably any week, because it is not part of how search ranks pages. What it can do is the same thing a good llms.txt does: it makes the machines sitting between your writing and your reader understand your site better. If your actual goal is citations in ChatGPT, Perplexity, or AI Overviews, start with answer engine optimization instead.

How to Build an OKF Bundle

You do not need Google’s tooling to start. The whole point is that it is just files.

1. Make a folder and add an index.md as the front door.
2. Write one file per concept. Put a type field at the top, then a short, honest description of what the thing is and how it is used.
3. Link related concepts with ordinary markdown links. A table links to the tables it joins; a metric links to the dataset it comes from.
4. Add the optional fields that help (description, tags, timestamp) so the structured bits stay queryable.
5. Serve it at /okf/ if it is public, and reference it from your llms.txt.

Google also ships a reference toolkit on GitHub: an enrichment agent that walks a database and drafts concept files, and a single-file HTML visualizer that renders any bundle as an interactive graph with no backend. Both are good ways to see the format click before you write a line yourself. Search Engine Journal’s writeup is a solid second read on the launch.

The Honest Caveat

Two things are true at once. OKF is a sensible, well-designed spec from a serious team, and it is version 0.1 with no consumer ecosystem yet. No AI agent crawls public /okf/bundles today the way search engines crawl pages. The developer reaction has been a fair mix of “finally, the obvious format” and “isn’t this just a folder of markdown?” And honestly, both are correct.

So here is our take, as people who build agents and the data layer under them. The near-term value of OKF is not machine traffic; it is the discipline. Writing a bundle forces you to say plainly what your business knows and how the pieces connect, and that surfaces gaps you would never find writing another page. Do it for the clarity now, and you are ready the day the readers show up. Start with your own source of truth, keep it current, and treat the format as the easy part, because it is.

Frequently Asked Questions