Open Knowledge Format (OKF)¶

Google Cloud's open specification for representing organisational knowledge in a form AI agents can consume: markdown files with YAML frontmatter, arranged in directories, linked to each other. Announced Jun 12 2026 at v0.1. Ingested here 2026-07-20 from open-knowledge-format (source).

The interesting thing about OKF is not the format — the format is deliberately almost nothing. It is that a hyperscaler looked at the vendor-catalog problem and concluded the portable answer is files a human can read, then wrote down the smallest spec that makes those files interoperable.

The problem: knowledge that cannot leave¶

Organisational knowledge sits in metadata catalogs with proprietary APIs, wikis, shared drives, code comments, and senior engineers' heads. The post's framing: every vendor ships its own catalog, SDK, and knowledge-graph schema, and none of the knowledge is portable between them. An agent answering a question has to assemble it from mutually incompatible surfaces.

This is a lock-in argument, not a capability argument. Nobody lacks a place to put metadata; they lack a place to put it that survives changing vendors.

The spec¶

One required field. That is the whole of the mandatory surface.

---
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
---

Required: type.
Standard but optional: title, description, resource, tags, timestamp.
Extensible: producers add whatever fields they need.

Bundles are directory trees where each concept is a document, each directory has an index.md, and ordinary markdown links between documents form the graph:

sales/
├── index.md
├── datasets/{index.md, orders_db.md}
├── tables/{index.md, orders.md, customers.md}
└── metrics/{index.md, weekly_active_users.md}

The governing line is "the spec defines the interoperability surface, not the content model." OKF tells you how a consumer can find and parse your knowledge; it says nothing about what a good page contains. That division is the whole design and it is worth holding onto — see Relationship to this vault.

Three design principles¶

Minimally opinionated — one required field.
Producer/consumer independence — a human-authored bundle can be read by an agent; a pipeline-generated bundle can be browsed in a visualizer; a bundle synthesised by one LLM can be queried by another. No producer knows its consumers.
Format, not platform — no cloud, database, or vendor in the critical path.

Why markdown, explicitly¶

The post grounds itself in Karpathy's llm-wiki-pattern argument: LLMs "don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass." (That gist is now ingested here — the quote is verbatim from it.) The intended consumption model is a shared markdown library that agents both read and update autonomously, with no SDK involved.

It also names the ad-hoc versions of this pattern it means to formalise — Obsidian vaults wired to coding agents, Notion, and Hugo's markdown-plus-frontmatter model. That is an unusually direct acknowledgement that the practice preceded the spec.

Reference implementations¶

Shipped alongside v0.1, and they map cleanly onto producer / consumer / conformance:

Enrichment agent (producer) — walks BigQuery datasets, emits OKF documents with citations and join paths.
Static HTML visualizer (consumer) — renders a bundle as an interactive graph, no backend.
Sample bundles (conformance) — GA4 e-commerce, Stack Overflow, Bitcoin.

Google Cloud's Knowledge Catalog was updated to ingest OKF and serve it to agents.

Relationship to this vault¶

This vault is an instance of the pattern OKF describes — the llm-wiki-pattern shape, markdown, wikilinks, an index. But the two systems solve different halves, and conflating them would be a mistake:

	`BRAIN.md`	OKF
Specifies	content model — what goes where, when to write, how to reconcile	interoperability surface — how a consumer parses a bundle
Silent about	how another tool would parse the vault	what makes a page worth reading
Enforcement	by convention, read into context each session	by convention, one required field

They compose rather than compete — and since 2026-07-20 this vault has adopted OKF's schema, so the composition is concrete rather than hypothetical. Wiki pages, sources, and both index.md files carry type (required) plus title, description, timestamp, and optional tags, sources, resource, created. memory/ and journal/ deliberately do not — OKF describes knowledge bundles, and those two are activity records. A consumer pointed at brain/ therefore sees one conformant bundle beside two non-conformant trees.

Adoption cost less than this page first estimated, for two reasons:

The mandatory surface really is one field. The actual work was not type but writing a description per page — and those already existed as the one-line summaries in wiki/index.md, making the migration largely transcription.
The blocking rule was protecting a channel with no reader. BRAIN.md forbade frontmatter and designated ## Tags as the metadata channel instead; that channel was at 8-of-17 adoption, carried five off-vocabulary tags, and nothing in the vault ever read it. See llm-wiki-pattern for the full reasoning.

What OKF did not supply is exactly what it says it leaves alone — the content model. timestamp is undefined in the spec, so this vault fixed it locally to last substantive revision for pages and capture date for sources; created is a local extension for authoring dates that predate git history. The producer/consumer split held up under real use: adopting the interoperability surface required changing nothing about what any page says.

Worth noting both systems inherit the same weakness, which the post does not address — see below.

The index problem OKF does not solve¶

agent-memory-at-scale argues that in a file-and-index memory system, the index is what breaks first, not the storage — retrieval quality collapses when the index stops fitting in the reasoning budget, silently, while every document remains perfectly intact on disk.

OKF bundles are index.md files all the way down. They inherit the failure mode exactly, and the spec offers nothing for it: no cardinality guidance, no convention for splitting an oversized index, no notion of a summary tier. Google's implicit bet is that graph-of-links plus agent traversal is sufficient — which is the same second retrieval channel that page credits for making wikis degrade gracefully, so the bet is not unreasonable. But that page also argues traversal quality is exactly what degrades as the graph grows, and OKF is aimed at enterprise metadata estates (every table in every dataset) where documents are generated in bulk by an agent rather than curated one at a time.

That combination trips two of the three vector-store triggers in agent-memory-at-scale: you do not control write time, and at that granularity no meaningful human-readable index exists. OKF's own reference producer generates bundles at precisely the scale where the format's retrieval story is weakest. The spec is a good interchange format; it is not, on its own, a retrieval architecture.

Open questions¶

~~Should brain/wiki/ adopt OKF frontmatter?~~ Answered 2026-07-20: yes. See the section above.
Does type mean anything useful for a vault whose pages are all "topic" or "entity"? The original scepticism was mostly borne out — across 22 files the field takes three values and 17 of them are topic. Its one real payoff is that a consumer can distinguish a source from a synthesis without reading either, which matters for trust more than for retrieval. The field still earns its keep over heterogeneous estates rather than here.
Now that description and sources live in frontmatter, should wiki/index.md be generated from them instead of hand-maintained? That would make index drift structurally impossible rather than a lint category. Not yet done.
Whether the spec grows a retrieval/index-scaling convention in later versions is the thing to watch at v0.2.

agent-memory-at-scale — the index-scaling argument this page tests OKF against; source of the three vector-store triggers.
claude-code-memory-architecture — the other file-and-index system in this vault, with hard mechanical limits OKF has no equivalent of.
ai-agent-architecture — §7 context engineering; OKF is a supply format for exactly that.
llms-txt-vs-robots-txt-vs-sitemap — the other "machine-readable convention for AI consumers" pattern; OKF is the same genre aimed at internal knowledge rather than public web content.
llm-wiki-pattern — the pattern this post cites as its grounding, and the third position on the frontmatter question.

References¶

Source: open-knowledge-format — Sam McVeety & Amir Hormati (Google Cloud), Introducing the Open Knowledge Format, Jun 12 2026.
Spec and reference code: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf