Open Knowledge Format (OKF): Google's Answer to the AI Agent Context Problem

The most common failure mode of an AI agent isn't the model. It's the context.

An agent with a great model and a fragmented pile of internal knowledge will confidently answer questions using a table schema that's a year out of date, a metric definition that doesn't match what finance actually reports, and no way to know which of the three sources it just read is authoritative. The models keep getting better; the thing holding them back is that the information they need is scattered, mutually incompatible, and locked behind whatever surface created it.

Google Cloud's answer, introduced on June 12, 2026 by the Data Cloud team, is the Open Knowledge Format (OKF): an open specification that packages the context agents need — table schemas, metric definitions, runbooks, API contracts — as a plain directory of markdown files with YAML frontmatter. No SDK, no runtime, no proprietary catalog, no schema registry. As the announcement puts it, what's missing was never another service. It was a format.

Then, five weeks later, OKF v0.2 (July 24, 2026) added the part that makes it safe to let agents write to the corpus: provenance, trust tiers, freshness, and attestation. That's the part security people should care about.

Here's what OKF is, why it matters for agentic AI, and how to start a bundle of your own.

The fragmented context landscape

In most organizations, the information foundation models actually use is overwhelmingly internal: the schema of a table, your business's meaning of a metric, the runbook for an incident, the join paths between two systems, the deprecation notice for an old API. These atoms of knowledge live in a highly fragmented set of surfaces:

• Metadata catalogs, each with its own API
• Wikis and shared drives, each with its own conventions
• Code comments, docstrings, and notebook cells
• The heads of a few senior engineers

When an agent needs to answer "how do I compute weekly active users from our event stream?" it has to assemble the answer from all of those surfaces. Every vendor ships its own catalog, its own SDK, its own knowledge-graph schema, and none of it is portable across products or organizations. The result, as the Google Cloud team describes it: every agent builder is solving the same context-assembly problem from scratch, and the knowledge itself is locked behind whichever surface created it.

This is the bottleneck behind a lot of the agentic AI market's momentum. Gartner projects that 40% of enterprise applications will embed agents by 2026 — and every one of those agents needs context that most organizations haven't actually organized.

The pattern that was already winning: LLM wikis

Developer teams have been converging on a workaround for the past year. Instead of making agents re-retrieve and re-synthesize the same facts from raw documents on every query, you give them a shared markdown library that compounds — an agent-maintained wiki that sits between the team and the sources.

Andrej Karpathy articulated the pattern most crisply in his LLM Wiki gist from April 2026, which has since racked up thousands of stars: rather than RAG, where the model rediscovers knowledge from scratch every time, the LLM incrementally builds and maintains a persistent wiki of interlinked markdown files — summarizing sources, updating cross-references, flagging contradictions. His line that sticks: LLMs don't get bored, don't forget to update a cross-reference, and can touch fifteen files in one pass. The bookkeeping that makes humans abandon wikis is exactly what LLMs are good at.

The same pattern keeps reappearing under different names: Obsidian vaults wired to coding agents, the AGENTS.md / CLAUDE.md family of convention files, repos full of index.md and log.md artifacts that agents consult before doing real work, "metadata as code" repositories inside data teams. The shape is everywhere — markdown, frontmatter, cross-links — but every instance is bespoke. There's no agreed-upon answer to what fields every document should carry, or what filenames mean what. So the knowledge stays siloed inside the team that built it, and the next agent built by anyone else starts over.

That's the gap OKF formalizes.

What OKF actually is

An OKF bundle is a directory of markdown files. Each file is one concept — a table, a dataset, a metric, a playbook, an API — and the file path is the concept's identity. Each concept document has a small YAML frontmatter block for the structured fields that need to be queryable, and a markdown body for everything else.

From the spec, which is self-contained and fits on a page: if you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.

The frontmatter is deliberately small. type is the only required field — consumers use it for routing and filtering. Recommended fields are title, description, resource (a URI pointing at the underlying asset), and tags. Everything else is up to the producer, and unknown keys must be preserved by consumers, never rejected. The spec does not define a taxonomy of types, does not prescribe storage or query infrastructure, and explicitly does not replace domain schemas like Avro, Protobuf, or OpenAPI — it references them.

The design in one screen, from Google Cloud's example:

---
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).         |
| `total_usd`   | NUMERIC   | Order total in US dollars.                       |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

Concepts link to each other with ordinary markdown links, which turns the directory into a graph of relationships richer than the parent/child hierarchy implied by the file system. Bundles may include index.md files (directory listings for progressive disclosure as agents navigate the hierarchy) and a log.md (chronological history of changes). Those two filenames are reserved; everything else is a concept.

Three principles behind the design

1. Minimally opinionated. OKF requires exactly one thing of every concept: a type. Everything else — what types exist, what other fields to include, what sections the body has — belongs to the producer. The spec defines the interoperability surface, not the content model.
2. Producer/consumer independence. A bundle hand-authored by a human can be consumed by an agent. A bundle generated by a metadata export pipeline can be browsed in a visualizer. A bundle synthesized by one LLM can be queried by another. The format is the contract; the tooling at each end is independently swappable.
3. Format, not platform. No cloud, database, model provider, or agent framework is required to read or write OKF. As the team puts it, the value of a knowledge format comes from how many parties speak it, not from who owns it.

Google shipped reference implementations as proofs of concept, deliberately: an enrichment agent that walks a BigQuery dataset and drafts a concept document for every table and view, and a static HTML visualizer that turns any bundle into an interactive graph view in a single self-contained file — no backend, no install, and no data leaves the page. Google Cloud's Knowledge Catalog (formerly Dataplex) now ingests OKF and serves it to agents, and the spec repo sits at 8.7k stars with a growing ecosystem of third-party producers and consumers.

Why it's useful in AI

Strip the spec language and OKF buys you five concrete things:

Knowledge compounds instead of being re-derived. This is the core of the LLM-wiki insight. With RAG, the model finds and pieces together the same fragments on every question, and nothing is built up. With a maintained bundle, the cross-references already exist, the contradictions are already flagged, and the synthesis already reflects everything ingested so far. The wiki gets richer with every source — and the agent gets better without retraining.

Agents traverse deliberately instead of chunking blindly. Because the bundle is a graph with typed concepts, an agent can read index.md first, follow links to the concepts it actually needs, and read only those bodies — instead of dumping your whole corpus into a vector index and hoping similarity finds the right fragment. The format is structured enough to make retrieval deterministic.

No bespoke SDKs, on either end. Anyone can produce a bundle with a text editor. Anyone can consume it with a markdown parser and a YAML reader — or, increasingly, no tooling at all, since agents read markdown natively. The cost of adding a new knowledge source is a directory of files, not an integration project.

Portable across vendors and organizations. A bundle lives in git, ships as a tarball, mounts on any filesystem. It doesn't lock you to a catalog, a cloud, or an agent framework. That's the property that makes it a candidate lingua franca for exchanging knowledge between organizations, not just within one.

Deterministic code can read it too. OKF isn't only for LLMs. Search indexes, UIs, and plain scripts can walk the same bundle — which matters when you want to verify something without asking a model to be trustworthy.

v0.2: the trust layer — the part security should care about

The first version of a format is easy to trust because humans wrote it. The version that matters is the one where agents write ten thousand concepts overnight — and then a different set of agents reads them. As Google Cloud's v0.2 announcement frames it, a human-authored wiki page carries an implicit guarantee: a person wrote it, and you can hold them accountable. When an agent generated the corpus, that guarantee is gone. A consumer has to judge each concept on explicit signals instead.

OKF v0.2 adds the vocabulary to answer five questions from frontmatter alone:

Question	Field	What it answers
Where did this come from?	sources	The materials a concept derives from, each with objective credibility signals (author, usage_count, last_modified)
How much should I trust it?	generated, verified	Who wrote it (which may be an agent) vs. who confirmed it (possibly a human)
Is it still true?	stale_after	An absolute date — staleness becomes a plain date comparison, no TTL math
Is it the current version?	status	draft → stable → deprecated (absent means stable)
Was this number produced the sanctioned way?	Attested Computation	The computation, its executor, and a deterministic attester

Two design choices here are worth spelling out because they're the security- relevant ones.

First, OKF records signals, not scores. There's no credibility score — a score is subjective, doesn't port across consumers, and goes stale the moment it's written. Instead, consumers derive a trust tier from verified: no verifier means unverified; machine-only confirmation means machine-confirmed; a human:<id> confirmation means human-reviewed. Those tiers are advisory, not access control — but they let a consumer say "only surface human-reviewed metrics in the executive dashboard" as a frontmatter filter, before spending a single token reading bodies.

Second, attestation is separate from verification. verified confirms a definition still matches policy — slow, doc-level, stored in the bundle. Attestation confirms a single run produced the value correctly — per-call, runtime, never stored. An Attested Computation concept carries the sanctioned way to compute a value (say, the SQL for YTD revenue), an executor that runs it and returns a receipt (the job ID, the SQL that actually executed, the result), and an attester — deterministic, no-LLM code — that mechanically compares the query that ran against the sanctioned computation. A rewritten query, a swapped table name, an added filter: the attester refuses, and the consumer refuses to display the value. The format never executes anything itself; it records the computation and how to check it.

That last part matters for the agentic security conversation. The question "did the agent improvise its own SQL?" is exactly the question most observability stacks can't answer. OKF doesn't solve it — it defines a portable way to ask it, which is a reasonable first step. And the whole v0.2 release is backward-compatible: a v0.1 bundle drops in unchanged, every new field is opt-in, and a bundle that adopts none of it is exactly as valid as it was before.

How to start an OKF bundle

OKF is boring on purpose, which makes starting cheap:

1. Scope it. Pick one domain where agents keep asking the same questions and getting wrong or inconsistent answers — a warehouse schema, a metrics glossary, a runbook set. Small beats comprehensive for the first bundle.
2. Structure the directory. One concept per file. Group by kind (tables/, metrics/, computations/, policies/) or by whatever matches how your team thinks. The path is the identity — rename later is a graph-breaking operation, so think before you name.
3. Frontmatter discipline. type is the only requirement, but fill in title, description, resource, and tags from day one. That's what makes concepts filterable without reading bodies.
4. Add trust fields as soon as anything writes to it. The moment an agent (or a pipeline) generates concepts, add generated, verified, status, and stale_after. The absence of a verifier now carries meaning — that's the point.
5. Put it in git. Version history, attribution, and diffs come free, and a git repo is the recommended distribution form anyway.
6. Point an agent at it. Link the bundle root from your agent's convention file, or drop it in a repo your agents already read. Then ask a question that previously required assembling five sources and watch the agent walk the graph.
7. Lint it periodically. Have an agent check for contradictions, stale claims, and orphan pages — the maintenance that kills human wikis is exactly what LLMs are good at, and Karpathy's pattern treats that bookkeeping as a recurring task, not a one-off.

The format itself is the contribution. Whatever shape your knowledge takes today — scattered docs, a proprietary catalog, the heads of two senior engineers — OKF is designed to be the common format you can exchange it into tomorrow, and the trust fields in v0.2 are what let you exchange it safely once agents are the ones writing it.

If you're authoring concept docs and want to see what a consumer actually reads, run the Markdown to JSON tool on a draft: it parses any markdown into the structured node tree an agent walks when it opens your bundle — a useful reality check on whether your structure is doing the work or just the prose.