BuildNot yet confirmed elsewhere1 publisher2 min readPublished
Open Knowledge Format: when the fact already has a name, the chunker is the bug
Google Cloud's OKF, published 12 June 2026, stores concepts as markdown files addressed by path. The claim worth testing: chunking a definition you already agreed on throws away its dependencies.
The Engineer · Build desk
What happened
- A bundle is a directory of markdown files, one concept per file, where a concept may be a table, a metric, an API, a policy or a runbook.
- The v0.2 spec requires exactly one frontmatter field, type; title, description, tags and a resource URI are only recommended.
- Two names are reserved: index.md lists a directory so an agent can skim one level, and log.md holds the changelog.
- Google's Knowledge Catalog, previously Dataplex, can ingest a bundle and serve it to agents, and bundles also read fine in Obsidian, GitHub or MkDocs.
Why it matters
- constraint Once a definition is chunked, a wrong answer is undiagnosable: the same fluent output covers a bad join and a bad retrieval, so there is nothing to reproduce or regression-test.
- capability Addressing a concept by file path turns a metric's dependency on a table into something a reviewer can follow and pin an approval to, instead of a similarity score recomputed per query.
- decision Teams with facts they can already name now choose between a repo they can diff and review and an index they have to rebuild, and the format side costs no procurement.
- contradiction The same writeup that argues for the wiki defends embeddings for the haystack case, which puts the dividing line at whether you can name the document, not at which vendor you prefer.
The interesting failure in the weekly-active-users example is not that the retriever missed the right document. It is that the document, as stored, no longer holds the fact. A metric definition is a claim plus a dependency: unique customers with a delivered order in the last seven days, computed against the `orders` table, with a playbook for the days the warehouse lags its SLA [4]. Run that through a chunker and the sentence survives while the pointer to the schema does not [14]. What comes back ranks well on cosine similarity and can still be an onboarding page that happened to use the phrase "active user" [2]. The prose reads the same either way, and that is the operational cost: a fluent paragraph will not tell you whether the model reasoned badly or was handed the wrong slice [3], so there is no failing test to write.
OKF's answer is unglamorous. The path is the identity, so `metrics/weekly_active_users.md` is both the file on disk and the address other files use to reach it [9], and concepts point at each other with ordinary markdown links, which makes the folder a graph laid over the directory tree [10]. The dependency is an edge in storage rather than something the model reconstructs per question. The sample bundle that answers the WAU question is four files [4], one of them the index [11], so three concept files carry the entire answer [19]. Nothing gets embedded, and the v0.2 compliance surface is one required frontmatter key, `type`, against four recommended ones [1][20].
The example metric file also carries a `verified` stamp from finance dated 1 July 2026 and a `stale_after` of 31 December 2026 [5]. That is a 183-day trust window written into the artefact itself [18], greppable across the bundle, which is not a property a floating chunk can have.
The lineage here is short. Andrej Karpathy described the read-and-maintain wiki pattern in April 2026 [17]; Sam McVeety and Amir Hormati at Google Cloud shipped the format about two months later [6][21]. Treat it as an argument at an early stage rather than a result: the writeup names one catalog that ingests bundles today, the renamed Dataplex [13], and offers no retrieval-accuracy or cost comparison against the chunked version of the same corpus [22]. Its own division of labour is the honest part. Embed the pile when you genuinely cannot name the document [15]. When finance can name it, and still argues about it in Slack, hoping the right slice comes back is wasted work that discards the links you already paid to write down [16].
What to watch
- Whether a later spec version promotes verified and stale_after from example decoration to required semantics, which is where any audit teeth would live.
- Whether a second production consumer ships bundle ingestion, the test of whether OKF is a portable format or an on-ramp to one catalog.
- Whether anyone publishes retrieval accuracy on identical questions against a chunked corpus and a path-addressed bundle.
Clarity's read
What the record supports and how the coverage leans. The claims behind it follow.
Reality
- Evidence32
- Adoption18
- Hype gap+34
- Incentives58
- Confidence40
Claim ledger
Ranked by verification strength, evidence, and original report placement.
- [1]
Every concept file starts with YAML frontmatter; the v0.2 spec requires one field, type, while title, description, tags and a resource URI are recommended and everything else is optional.
- [2]
Sometimes the model counts sign-ins because an onboarding page used the words "active user".
- [3]
You cannot tell, from the fluent paragraph the model returns, whether it reasoned badly or the retriever handed it the wrong slice.
- [4]
The sample bundle is sales/index.md, tables/orders.md, metrics/weekly_active_users.md and playbooks/orders_freshness.md; the index lists Orders (one row per completed customer order), Weekly active users (unique customers with a delivered order in the last 7 days) and Orders freshness (what to do when orders lags the SLA), and the spec keeps frontmatter off index files except an optional version key at the bundle root.
- [5]
The example metric file carries verified: by human:finance@acme at 2026-07-01T09:00:00Z and stale_after: 2026-12-31T00:00:00Z.
- [6]
Google Cloud published the Open Knowledge Format on 12 June 2026, authored by Sam McVeety and Amir Hormati.
- [7]
OKF is a format rather than a product: you do not install it, and you do not need a vector product to use it.
- [8]
An OKF bundle is a directory of markdown files, each file one concept, where a concept can be a table, a metric, an API, a policy or a runbook.
- [9]
The path is the identity: metrics/weekly_active_users.md is both the filename on disk and the address other files use when they point at it.
- [10]
Concepts link to each other with ordinary markdown links, so the folder is a graph sitting on top of the directory tree.
- [11]
Two reserved names handle navigation: index.md lists a directory so an agent can skim one level without loading the whole bundle into context, and log.md is the changelog.
- [12]
A bundle can ship as a git repo, a tarball, or a folder on disk.
- [13]
Google Cloud's Knowledge Catalog, the catalog formerly called Dataplex, can ingest a bundle and serve it to agents; the format does not care whether the reader is Knowledge Catalog, Obsidian, GitHub, MkDocs or a file-read tool in an agent loop.
- [14]
In the usual RAG wiring, docs go into a chunker that cuts the WAU paragraph away from the schema it depends on, and at query time a retriever returns a few fragments that look related while the model infers the join; the answer actually lives in a metric doc pointing at the orders table plus a freshness playbook for days the warehouse is late.
- [15]
RAG is doing the job it was built for, search: you have a haystack, you do not know which document matters, you embed the pile, rank by similarity and let the model stitch something together, which is reasonable when the answer is buried in years of tickets and leftover wiki pages.
- [16]
Splitting a known definition into chunks and hoping the right slice comes back is wasted work, and it throws away the links between the metric, the table and the playbook.
- [17]
In April 2026 Andrej Karpathy wrote down a different pattern: keep a wiki the model can read and maintain, so that when a new source arrives the model files the useful parts into existing pages, updates cross-references and notes contradictions, and knowledge compiles once.
- [18]
The example metric's verification stamp and its expiry are 183 days apart.
- [19]
Of the four files in the sample bundle, one is the reserved index, so three concept files carry the whole WAU answer.
- [20]
The v0.2 frontmatter contract is one required key against four named recommended ones.
- [21]
OKF was published roughly two months after Karpathy's April 2026 note.
- [22]
The source presents no retrieval-accuracy, latency or cost measurement comparing a chunked corpus with a path-addressed bundle on the same questions.
Sources
1 independent publisher whose own reporting we read for this story.
- dev.toOpen Knowledge Format vs RAG: Why Your Agent Should Read a Wiki
1 article · August 22, 2026
Topics and entities
Follow any of these and your For You feed starts watching them — no settings page required.
Topics
- Semantic Layer and Metric GovernanceFollow
- Retrieval-Augmented GenerationFollow
- Agent Knowledge FormatsFollow
- Context EngineeringFollow
- Metadata and Data CatalogsFollow
Entities
- Open Knowledge FormatFollow
- Google CloudFollow
- Knowledge CatalogFollow
- Sam McVeetyFollow
- Amir HormatiFollow
- Andrej KarpathyFollow
- Retrieval-Augmented Generation (RAG)Follow
- ObsidianFollow
- MkDocsFollow