1 The AI Agent Context Problem
Your AI agent can write code, query a database, and send an email — but ask it one simple thing: "What is our official definition of an active user?" — and it has no idea.
The agent is brilliant, but it knows nothing about your company. That knowledge isn't in one place. It's scattered across:
- A Confluence page nobody updates
- A Notion doc in someone's workspace
- A Slack thread from six months ago
- A comment buried in code
- A BigQuery schema with cryptic column names
- A dozen things that only live inside someone's head
Every agent you build has to go find it, read it, and figure it out — all over again. Same documents, same guesswork, every single time. Google calls this problem "solving context assembly from scratch."
2 What Is Google OKF?
The Open Knowledge Format (OKF) is an open specification from Google Cloud, released under the Apache license. The solution is almost shockingly simple:
- No database
- No vectors
- No platform to log into
An OKF knowledge base is just a folder of plain Markdown files sitting in a Git repository. Each file describes exactly one thing — one table, one metric, one runbook. When an agent needs to understand your business, it just opens the file and reads it, like a new hire reading the handbook.
3 Why AI Agents Need Structured Institutional Memory
Modern agents are genuinely great at doing things. What they're bad at is knowing things — the institutional memory a tenured employee carries around without even thinking. This memory is made of small, specific facts:
- Which metric definition is the canonical one?
- What a column actually means
- Which runbook applies in the EU region
- Which API endpoint is quietly deprecated
- The exact join path between two tables
Today, every team rebuilds that context by hand. Every agent project resolves the same problem. Every catalog vendor reinvents the same data model. The knowledge stays locked behind whatever tool happened to create it.
4 Karpathy's "LLM Wiki" Concept
Why not just keep a wiki? Because humans abandon them. As Andrej Karpathy put it:
This is the key insight behind OKF: the knowledge base isn't maintained for AI agents — it's maintained by them. The tedious work of keeping documentation current, updating cross-references, and ensuring consistency across hundreds of files is precisely the kind of work LLMs excel at and humans inevitably neglect.
5 Anatomy of an OKF File
A single OKF document has exactly two parts:
1. YAML Frontmatter (Structured Metadata)
The metadata block at the top has only one required field: type. It's a short label — bigquery_table, metric, runbook, playbook — that agents use to route, filter, and decide what they're looking at. You invent the types you need; nothing is centrally registered.
Five more fields are recommended but optional:
- title — human-readable name
- description — one-line summary
- resource — link to the real asset
- tags — categorization labels
- timestamp — last updated date
You can add your own custom keys too, and a well-behaved reader preserves keys it doesn't recognize.
2. Markdown Body (Free-Form Content)
Below the metadata, it's just plain Markdown. For a table, that's the schema. For a metric, the exact formula. For a runbook, the steps. Whatever a human would want to read, written for both humans and machines at once.
Links Create a Knowledge Graph
Documents link to each other using ordinary Markdown links. A foreign key points to the customer's file. A metric points to the table it's built on. Together, they form a navigable graph of your whole business.
6 Bundles & Progressive Disclosure
A collection of OKF files is called a bundle — simply a directory tree. Datasets, tables, and metrics each live in their own folder. The structure mirrors how your team already thinks, not some rigid schema.
Index Files — The Clever Part
Each folder can hold an index file — a simple table of contents. An agent reads the index first and decides what's worth opening, instead of pulling every single file into its context window. The spec calls this "progressive disclosure" — a context-efficient strategy that keeps LLM token usage lean.
Log Files & Version Control
There's also an optional log file — a changelog with newest entries first. The knowledge base is managed exactly like code: kept in version control, reviewed in pull requests, with a history of every change.
And the spec is deliberately forgiving: a consumer must tolerate broken links, unknown fields, or types it's never seen before. Real knowledge is always half-finished, so OKF is built to keep working while it grows.
7 Google's BigQuery Enrichment Agent
You're not writing hundreds of OKF files by hand. Google ships a reference enrichment agent that automates the process:
- First pass — point it at a BigQuery dataset, and it walks every table and view, drafting an OKF document for each one automatically
- Second pass — reads your actual documentation and fills each draft with schemas, join paths, and citations back to the source
- You review and curate — the machine does the typing
Google also provides:
- Three ready-made sample bundles: Google Analytics, Stack Overflow, and Bitcoin data
- A HTML viewer to browse a bundle like a tiny website
- Knowledge Catalog integration — ingest a bundle and serve it straight to your agents at runtime
8 OKF vs RAG vs MCP — Where It Sits in the Stack
Cloud Codes lays out the three foundational rules of OKF, then positions it precisely in the modern agent stack:
Three Core Rules
- Files are the API — no server needed. If you can read a file, you can read OKF
- Metadata is structured, body is free — machines parse the YAML, humans read the Markdown
- Links make a graph — each document enriches its neighbors
OKF vs RAG
OKF is not a replacement for RAG. They answer different questions:
- RAG answers: "Find me something relevant" (semantic search)
- OKF answers: "Here is exactly what this thing means" (canonical definitions)
They complement each other: you might search a vector database to find the right OKF file, then hand the agent that file as grounding context.
OKF vs MCP
OKF is not a replacement for MCP either:
- MCP connects agents to live tools and data sources (the socket)
- OKF gives the agent the knowledge to use those tools correctly (the data flowing through the socket)
9 The Honest Verdict on v0.1
Cloud Codes gives a candid assessment. Version 0.1 is thin:
- 14 pages, mostly YAML examples
- No query language
- No schema registry
- No conflict resolution for competing definitions
- Google has published it but it's not yet deeply embedded in their own platform
That said, the idea is sound and the timing is right. Every team building agents today is solving the same context problem from scratch. A shared spec that is "boring enough to just work" might be exactly what the ecosystem needs.
And because it's Markdown in Git, you can start in ten minutes with zero infrastructure.
🎯 Key Takeaways
🔑 Key Takeaways
- OKF is a folder of Markdown files in Git — no database, no vectors, no platform. Each file describes one thing (table, metric, runbook) with YAML frontmatter + Markdown body
- Only one required field:
type— everything else is optional, making it trivially easy to start and deliberately forgiving as knowledge grows - Agents read it like a handbook — no retrieval pipeline required. The agent opens the file and gets canonical definitions instantly
- Progressive disclosure saves context — index files let agents decide what to open instead of loading everything into the context window
- Markdown links create a knowledge graph — documents cross-reference each other, forming a navigable graph of your business
- LLMs maintain it, not humans — Karpathy's insight: the bookkeeping humans abandon is exactly what language models excel at
- Google's enrichment agent automates creation — point it at BigQuery and it drafts OKF documents automatically with schemas, join paths, and citations
- Complements both RAG and MCP — RAG finds relevant content, OKF defines what things mean, MCP connects to tools. Three layers, not replacements
- Apache licensed, v0.1 — thin spec (14 pages), no query language or schema registry yet, but sound idea with perfect timing
- Zero infrastructure to start — write 5 files, put them in Git, point your agent at the folder. You're running OKF
🔗 Resources & Links
- Open Knowledge Format (GitHub) — official OKF specification repository
- Google Cloud Blog — Introducing OKF — official announcement