OKF (Open Knowledge Format)

OKF (Open Knowledge Format) is an open specification, published by Google Cloud on 13 June 2026 under Apache-2.0, for writing down what an organization knows as a folder of plain Markdown files that any AI agent can read without custom integration work. Google frames it as formalizing the “LLM-wiki” pattern into a portable, interoperable format. Each file describes one concept, a table, a dataset, a metric, a playbook, a system, with a small block of YAML metadata at the top and ordinary Markdown links to other concepts in the body. Those links form an explicit, human-authored knowledge graph. The pitch is a direct contrast with retrieval-augmented generation: where RAG chops documents into chunks and lets a model infer relationships from embeddings at query time, OKF keeps the relationships written down, version-controlled, and editable, and hands the agent a curated map instead of a pile of fragments.

The Problem: Knowledge Trapped in Silos

Most organizations already have the knowledge an agent needs. The problem is where it lives: in a data-catalog product with its own API, in a Confluence wiki, in shared drives, in Slack threads, in code comments and docstrings, in someone’s head. Each of those stores has a different format and a different access method, so every agent that needs the knowledge requires a bespoke integration, and the integration breaks when the underlying tool changes.

OKF’s answer is to make the format the contract, not any particular product. If knowledge is a directory of Markdown files with a documented structure, then:

• Any producer can write it. A human editing files by hand, an export script walking a database, an agent built on any framework, a pipeline dumping an existing catalog.
• Any consumer can read it. An LLM loading files into context, a static site generator, a search index, a graph viewer, an editor like Obsidian or a docs tool like MkDocs.
• It travels with your code. The bundle is plain text in a git repo, so it diffs, reviews, and versions like source, and an agent that edits it produces a reviewable pull request rather than an opaque write to a vector store.

The design is deliberately minimal. Only one frontmatter field is mandatory. Everything else is convention, so a bundle can start as three files and grow without a migration.

Anatomy of an OKF Bundle

A bundle is a directory tree of .md concept files, usually with an index.md at each level acting as a table of contents:

sales/
  index.md
  datasets/
    index.md
    orders_db.md
  tables/
    orders.md
    customers.md
  metrics/
    weekly_revenue.md
  playbooks/
    orders_backfill.md

Each file opens with YAML frontmatter. Per the spec, type is the only required field; the rest are optional but widely used:

The body is plain Markdown. Relationships are just links: [customers](/tables/customers.md). An agent that reads orders.md and sees a link to customers.md knows those two concepts are related and can follow the edge, no embedding similarity, no inference.

How an Agent Consumes a Bundle

Reading a bundle is deliberately trivial: list the files, parse each frontmatter block, extract the Markdown links, and you have a typed node-and-edge graph.

# Scenario: an analytics agent needs to load an OKF bundle and answer
# "which tables feed the weekly_revenue metric, and who owns them?"
import pathlib, re, yaml

FM = re.compile(r"^---\n(.*?)\n---\n(.*)$", re.S)
LINK = re.compile(r"\[[^\]]+\]\(([^)]+\.md)\)")

def load_bundle(root: str) -> dict:
    graph = {}
    for path in pathlib.Path(root).rglob("*.md"):
        raw = path.read_text()
        m = FM.match(raw)
        meta, body = (yaml.safe_load(m.group(1)), m.group(2)) if m else ({}, raw)
        graph[str(path)] = {
            "meta": meta,
            "body": body,
            "links": LINK.findall(body),   # outgoing edges
        }
    return graph

bundle = load_bundle("./sales")
# Traverse from the metric file, following explicit links, no vector search:
metric = bundle["sales/metrics/weekly_revenue.md"]
upstream = [bundle[l.lstrip("/")] for l in metric["links"] if l.endswith(".md")]

Because the bundle is editable text, an agent can also write to it: append a “Known issues” note it discovered, mark a concept stale_after a date, add a link it found missing. That update is a file diff, so it goes through the same review as any code change rather than silently mutating an index.

OKF vs. RAG vs. a Vector Database

OKF is often introduced as an alternative to RAG, but the sharper framing is that they solve different halves of the problem.

The practical pattern is to use both: an OKF bundle for the curated core (schemas, metrics definitions, runbooks, ownership) that an agent should treat as authoritative, and RAG over raw docs for the long tail the curation has not reached.

# Scenario: answer from the curated bundle first; fall back to RAG only
# when no OKF concept covers the question.
def answer(question, bundle, rag_index, llm):
    hit = find_concept(bundle, question)          # keyword / type / link match
    if hit and hit["meta"].get("status") == "current":
        return llm.answer(question, context=hit["body"])
    chunks = rag_index.search(question, k=6)       # long-tail fallback
    return llm.answer(question, context=chunks)

OKF vs. llms.txt vs. MCP

OKF sits alongside two other agent-context conventions, and the three are complementary layers rather than competitors:

llms.txt tells an agent where to start; OKF is what it reads once it is inside; MCP is how it fetches things that are not written down. A mature setup can expose all three: an llms.txt at the root, an OKF bundle for curated knowledge, and MCP servers for live systems. OKF can even be served through an MCP server, so an agent queries the bundle the same way it queries any other tool.

The Value of Explicit Links: Multi-Hop Questions

The clearest place OKF beats retrieval is questions that require chaining several facts together. “Who owns the table that feeds the weekly-revenue metric?” is three hops: metric to its source table, table to its owner. With RAG, each hop is a separate retrieval that can miss, and the failure probabilities compound. With OKF, each hop is following a written link, which either exists or does not.

This is why OKF is pitched hardest for structured, relational knowledge (data catalogs, service ownership, metric lineage) rather than prose. Prose is where RAG still wins.

Generating a Bundle

Nobody hand-writes a bundle for a 4,000-table warehouse. The expected pattern is an export pipeline or an agent that walks an existing system and emits concept files.

# Scenario: turn a database's information_schema into an OKF bundle,
# one file per table, with links to referenced tables via foreign keys.
import pathlib, yaml

def emit_table_concept(out_dir, table, columns, foreign_keys):
    fm = {
        "type": "table",
        "title": table["name"],
        "description": table["comment"] or f"Table {table['name']}.",
        "resource": f"bigquery://{table['dataset']}.{table['name']}",
        "tags": ["auto-generated"],
        "generated": {"at": table["exported_at"], "by": "catalog-export"},
        "verified": False,
    }
    lines = [f"- `{c['name']}` ({c['dtype']})" for c in columns]
    for fk in foreign_keys:
        lines.append(f"- `{fk['column']}` -> [{fk['ref_table']}](/tables/{fk['ref_table']}.md)")
    body = f"# {table['name']}\n\n## Columns\n\n" + "\n".join(lines) + "\n"
    path = pathlib.Path(out_dir, "tables", f"{table['name']}.md")
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text("---\n" + yaml.safe_dump(fm, sort_keys=False) + "---\n\n" + body)

The verified: False flag matters here: an auto-generated bundle is a draft. A human (or a review agent) flips concepts to verified: True as they are checked, and consumers can be told to trust only verified concepts for high-stakes answers.

Tooling and Ecosystem

At launch Google shipped a reference set alongside the spec: a BigQuery enrichment agent that generates and updates bundles from a warehouse, a static HTML visualizer that renders a bundle as a browsable linked site, and three sample bundles. The canonical repo is GoogleCloudPlatform/open-knowledge-format; the spec text lives in GoogleCloudPlatform/knowledge-catalog under okf/SPEC.md, Apache-2.0.

Community tooling appeared quickly: a standalone CLI for authoring, validating, and linting bundles; a Ruby gem that bundles a CLI, a library, a graph viewer, and an MCP server so any MCP host can query a bundle; a Claude Code plugin with agent skills and a GitHub Action for validating bundles in CI; and a WordPress plugin that generates a bundle from an existing site. Because a bundle is just Markdown, existing tools (Obsidian, Notion export, MkDocs, plain static file servers) can serve or edit one with no OKF-specific support.

What’s New (2026)

• v0.1 to v0.2. The June 2026 v0.1 spec was minimal: concept files, links, and a small frontmatter set with only type required. v0.2 added optional fields for provenance (sources), trust (generated, verified), and lifecycle (status, stale_after), and renamed timestamp to generated.at. The direction of travel is toward letting a consumer reason about how much to trust a given concept, not just read it.
• Positioned as a standard, not a product. Coverage consistently stressed that OKF ships no hosted service and no required account; Google’s interest is in agents (its own included) having a common knowledge format to consume, the same way robots.txt benefits everyone without belonging to anyone.
• Overlap with the wiki-for-LLMs idea. OKF landed into an active conversation, prompted by widely shared early-2026 arguments that LLM-facing knowledge should live as a hyperlinked wiki of plain-text pages rather than as opaque vectors, and it is the most concrete specification of that idea so far.
• Early, uneven adoption. As of late 2026 there is no web-scale crawler fetching bundles, no ranking or discovery benefit to publishing one, and the verified field is largely unused because verifying every concept is real work. Its proven value is internal: giving an organization’s own agents a clean, reviewable knowledge base, not public-facing AI visibility.

Bottom Line

OKF is a small, deliberately boring specification: a folder of Markdown concept files, YAML frontmatter with one required field, links as edges. Its bet is that curated, explicit, version-controlled knowledge beats query-time inference for the structured core of what an organization knows, schemas, metrics, ownership, runbooks, and that making that knowledge a plain-text format rather than a product is what lets every agent, on any framework, use it without a custom integration. It does not replace RAG for the long tail of prose, and it has no public-discovery story yet. Treat it as an internal agent-knowledge layer that slots in beside llms.txt and MCP, not as a retrieval system on its own.

---
type: table
title: orders
description: One row per customer order, immutable once written.
resource: bigquery://analytics.sales.orders
tags: [sales, core, pii]
generated:
  at: 2026-09-01T09:00:00Z
  by: catalog-export-agent
sources:
  - https://wiki.internal/sales/orders-schema
status: current
stale_after: 2026-12-01
---

# orders

Grain: one row per order. Written by the checkout service; never updated
in place. Refunds are separate rows in [refunds](/tables/refunds.md).

## Key columns

- `order_id` (string, PK)
- `customer_id` -> joins [customers](/tables/customers.md)
- `total_cents` (int64) feeds the [weekly revenue](/metrics/weekly_revenue.md) metric

## Known issues

Rows before 2024-03 have null `channel`; see the note in
[orders backfill](/playbooks/orders_backfill.md).