Knowledge as Plain Files

The most consequential AI release from Google this summer has no model weights, no API, and no benchmark scores. It is a folder of markdown files.

On June 12, 2026, Google Cloud introduced the Open Knowledge Format (OKF), an open specification for packaging the context that AI agents depend on: what your tables mean, how your metrics are defined, which systems talk to each other, and why. Every team building agents has hit the same wall. The agent is only as capable as the context it receives, and that context is scattered across metadata catalogs with proprietary APIs, wiki pages nobody updates, code comments, and the heads of a few senior engineers. When an agent needs to know what orders.customer_id joins to, none of those places is reachable.

OKF's answer is almost provocatively boring. Version 0.1 of the spec defines a knowledge base as a directory of markdown files with a small block of YAML metadata (called frontmatter) at the top of each one. Google's own summary of the design is the best one:

The context your agents depend on should not be locked inside a proprietary catalog. It should be just markdown, just files, just YAML frontmatter: portable, readable by people, and parseable by machines, with no SDK and no runtime required.

What Google actually shipped

An OKF bundle is a folder. Each concept worth knowing about (a table, a dataset, a metric, a runbook, an API) gets one file, and the file path is its identity. Concepts point at each other with ordinary markdown links, so a consistent bundle forms a navigable knowledge graph without any graph database. An optional index.md per folder gives an agent a summary before it drills into details, and an optional log.md records change history.

The metadata layer is deliberately thin. Only one frontmatter field, type, is required. Five more are reserved but optional: title, description, resource, tags, and timestamp. A table description looks like this:

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

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

Three principles hold the spec together. It is minimally opinionated: the spec defines interoperability, not your content model. Producers and consumers are independent: the format is the contract, so a bundle written by a human, a pipeline, or an LLM can be read by any tool that understands markdown. And it is a format, not a platform: nothing in it requires a particular cloud, database, or model provider. Google shipped reference implementations alongside the spec, including an enrichment agent that walks a BigQuery dataset and drafts concept documents, a static HTML visualizer that renders any bundle as an interactive graph, and three sample bundles built from the GA4 e-commerce, Stack Overflow, and Bitcoin public datasets.

The wiki that finally maintains itself

The idea OKF formalizes has been circulating for a year under the name "LLM-wiki," and its logic traces back to an observation by Andrej Karpathy: language models do not get bored, do not forget to update a cross-reference, and can edit fifteen files in one pass. The bookkeeping that makes humans abandon every wiki they start is precisely the work LLMs do well. That inverts the economics of documentation. A knowledge base that decayed under human maintenance can now improve under machine maintenance, provided the knowledge lives somewhere an agent can both read and write.

READAgent loads the concept files relevant to its task

→

WORKAgent answers the question or runs the job

→

LEARNAlong the way it discovers a gap or a stale fact

→

WRITEIt edits the files and commits, so the next read is smarter

Plain files are what make the loop practical. A markdown bundle lives in git, so every machine edit gets a diff, a review, and a rollback path. It ships as a tarball. It renders on GitHub. Any editor opens it. None of that is true of knowledge locked behind a catalog API.

Files versus pipelines

The obvious question is how this differs from retrieval-augmented generation (RAG), the standard technique of fetching relevant text chunks into a model's context at query time. The difference is where the understanding lives. A RAG pipeline re-derives meaning on every query from raw fragments, and it forgets what it derived the moment the query ends. An OKF bundle stores conclusions that were already curated: this table joins to that one, this metric excludes refunds, this pipeline is deprecated. The agent reads settled knowledge instead of reconstructing it, and when it learns something new it writes the conclusion back.

RAG PIPELINE

• Retrieves raw chunks at query time
• Re-derives meaning on every question
• Insights evaporate after each query
• Quality depends on the retriever

OKF BUNDLE

• Stores curated, cross-linked concepts
• Agent reads settled conclusions directly
• New insights are written back as files
• Quality compounds in version control

The two are complements, not rivals. RAG still wins for large, fast-moving corpora nobody will curate. OKF targets the stable, high-value core: the few hundred concepts an organization keeps re-explaining to every new hire and now to every new agent.

A standard or a folder?

Skeptics have a fair critique: OKF standardizes the container, not the meaning. The spec has no type registry, so one producer writes type: BigQuery Table while another writes type: table, and both bundles are compliant. Links assert that two concepts relate but never say how. Two conformant bundles can share zero common vocabulary, which means conformance guarantees structural interoperability (any tool can find and parse the files) but not semantic interoperability (any tool can understand them the same way). For a v0.1 draft that invites community extension, this is a reasonable starting point, but treat conformance claims accordingly.

It is also worth being precise about what OKF does not replace. A semantic layer still defines your metrics with executable rigor. dbt still documents your transformations. Data catalogs still handle access control and lineage at scale, and several can now ingest OKF rather than compete with it. Repository conventions like AGENTS.md and website conventions like llms.txt tell agents how to behave in a codebase or on a site; OKF describes a body of knowledge. The new thing is the layer in between: a portable context package you can hand to any agent without building a custom integration.

How to try it this week

The barrier to entry is a text editor. A practical first pass looks like this: pick one domain your team explains constantly, perhaps ten or twenty tables and a handful of metrics. Write one markdown file per concept with a type and a description, link them where they join, and add an index.md that summarizes the domain in a paragraph. Put the folder in git. Then point your existing agent at it, either by mounting the folder into its workspace or by listing it in the agent's context configuration, and compare answer quality on real questions against your current setup. If the results hold, close the loop: permit the agent to propose edits to the bundle as pull requests, so human review guards every change while the bundle keeps improving.

Conclusion

Strip away the announcement and OKF is a bet about substrate. For decades the industry assumed organizational knowledge needed heavy machinery: databases, ontologies, catalog platforms. OKF argues the opposite, that once machines can maintain prose, the humblest format wins, because plain files are the only representation every tool, every model, and every human already shares. Whether this particular spec becomes the standard matters less than the pattern it names. Some format for portable, file-based agent context will win, for the same reason markdown itself won.

The strategic implication is uncomfortable for anyone whose moat is a proprietary metadata store. If context becomes files, context becomes portable, and switching agent vendors becomes as easy as pointing a new agent at the same folder. That is exactly the leverage buyers should want.

What leaders should do

1. Inventory where your agent-critical context lives today. Anything reachable only through a proprietary API or a person's memory is a single point of failure; list the top ten concepts and who owns them.
2. Run a two-week OKF pilot on one data domain. Have one engineer draft the bundle (or run Google's enrichment agent against a BigQuery dataset) and measure agent answer quality before and after.
3. Set a write-back policy now. Decide whether agents may edit knowledge files directly or only via pull request, and who reviews. The maintenance loop is where the value compounds, and where the risk lives.
4. Add format portability to your AI vendor checklist. Ask every catalog and agent vendor whether they can export and ingest OKF or an equivalent open format, and treat a refusal as a lock-in signal.