Open Knowledge Format: Markdown Files as a Portable Knowledge Layer for Agents

Agents burn tokens re-reading the same internal documents over and over, and Google Cloud has proposed a fix: the Open Knowledge Format, OKF. Version 0.1 was announced on the Google Cloud blog on June 12, 2026. The pitch is plain. Every concept a team cares about becomes one markdown file, and a folder of those files acts as a lightweight knowledge graph any agent can read. It needs no SDK, no database and no lock-in. A skeptic might expect yet another platform dressed up as a format, but this really is just files, and that is the interesting part. Teams keep piling complexity around agents when one of the hardest questions is simpler: where does the useful knowledge actually live?

The problem: agents keep relearning

Here is the common pattern. An agent gets a question about a metric, pulls in the entire internal wiki, embeds the text and works out the meaning from scratch. On the next query it does exactly the same. Raw text may be cached, but nobody caches the understanding.

Picture an agent that has to re-read a document defining an active user on every single query because that definition has no proper home and sits in a Notion page three folders down. Each call is cheap, but the waste adds up the way small waste does when nobody is watching, and across a team running the same handful of queries daily the token spend is real. There's no public figure for it, since outsiders don't have Google's internal numbers, yet the problem itself is familiar to most people running agents.

A more concrete case: an analytics doc defines an active user as anyone who took at least one meaningful product action in a calendar month. Ask an agent how many active users there were last month and it needs two different things. It needs the numbers, and it needs to know what active means here. Those are separate problems. The database reports what happened, while a knowledge layer records what the company means by it. OKF aims to make that second part easier to represent.

The fix is a format, not a bigger model

OKF is almost boringly simple, deliberately. A bundle is a folder of markdown files, each describing one concept, whether a table, a metric, an API or a runbook. Each file begins with a small YAML block, the frontmatter, between two marker lines. Only one field is mandatory:

---
type: Metric   # required – tells the agent what kind of concept this is
---

Five optional fields round it out, listed here with their purposes:

| Field         | Purpose                      |
| ------------- | ---------------------------- |
| `title`       | Human-readable name          |
| `description` | Short summary                |
| `resource`    | Link to the underlying asset |
| `tags`        | Keywords for categorization  |

Version 0.2 adds optional fields covering provenance, verification, freshness, lifecycle and computations that have been attested. You may add any extra keys, and consumers are expected to ignore ones they don't recognize and not break, which is what lets the format be extended without wrecking someone else's agent. Two filenames are reserved: index.md for a directory listing and log.md for a change history, saving you from inventing conventions the spec already settled. The spec launched as a v0.1 draft, so expect it to evolve and check the repository for the current version before building anything serious.

Links make the graph

Because the files are plain markdown, concepts connect with ordinary [text](other-file.md) links, and those links are the edges of a graph that lives in the folder, with no extra database. A valid concept file looks like this:

---
type: Metric
title: Monthly Revenue
description: Total money earned each month.
resource: https://console.cloud.google.com/bigquery?p=project&d=dataset&t=revenue
tags: [finance, monthly]
---

Revenue is counted after refunds are removed.

See also: [customer_acquisition_cost.md](customer_acquisition_cost.md)

An agent reading revenue.md learns that a related concept lives in customer_acquisition_cost.md. What the link means still comes from whoever wrote the files, as the format doesn't claim to understand it for you.

Trying it in five minutes

The spec ships with real sample bundles built from GA4 e-commerce data, Stack Overflow and Bitcoin blockchain data. A reference agent that walks BigQuery datasets and drafts OKF documents automatically produced them, and everything sits in one Apache 2.0 repository:

git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/okf

# Add your own concept
cat > new_metric.md <<'EOF'
---
type: Metric
title: Net Promoter Score
description: Measure of customer loyalty.
resource: https://console.cloud.google.com/bigquery?p=company&d=metrics&t=nps
tags: [customer, loyalty]
---
EOF

Each sample bundle includes a viz.html file. Open it in any browser to get an interactive graph of the bundle with nodes, links, search and filters, no backend or server involved. One caveat is that generating a viz.html for your own bundle means running the small Python reference tool in the repo. It bakes the bundle into a single self-contained HTML page built on Cytoscape.js and marked.js, again with no backend, just a file you could email to a colleague.

Benefits

• Lower cost: the definition is written down once and read directly, so you stop paying to re-derive it fifty times a day.
• Faster loading: it's plain text on disk, with no network round trip to a knowledge service and no embedding step before use.
• Real portability: clone the repo, copy the folder or drop it into a Docker image, and it behaves the same on GCP, Azure, AWS or a laptop. There's nothing to lock you in.
• Version control for free: bundles live in git, so pull requests, diffs, blame and review apply, and curating knowledge becomes ordinary engineering work.
• A single source for people and agents: a new hire and an on-call agent open the same file, so the wiki can't say one thing while the agent believes another.
• Exchange across teams and organizations: a vendor can ship a catalog as an OKF bundle that your agent consumes directly, with zero integration work.

Reviewability is a further advantage. Suppose an agent proposes this change:

- Revenue is recognized when an order is placed.
+ Revenue is recognized after delivery and the 30-day return window.

That's a plain git diff, and a reviewer sees precisely what moved. It's much easier to judge than a silent update buried in a proprietary knowledge system.

Where it falls short

• It doesn't repair bad definitions. OKF standardizes the container and not the contents, so if a team can't agree what active user means, a markdown file won't force agreement.
• Someone must maintain it. Files go stale, and the timestamp field and log.md help only if people or agents update them. Outdated knowledge can do more harm than having none, since agents believe whatever they find.
• It's a young draft, explicitly unfinished, so fields and conventions may shift and early adopters should expect churn.
• Meaning isn't enforced. A link says two concepts are related but not how, and the relationship lives in prose, which is flexible and also fuzzy. Strict typed relationships still call for a real graph database.
• Few adopters so far. Almost every producer and consumer at launch came from Google, and the format only wins if other tools and teams pick it up.

OKF alongside RAG and MCP

Nothing in the current stack gets thrown away, because OKF slots in underneath. RAG still finds relevant passages when a query arrives, and OKF supplies it with cleaner, pre-structured text, which makes embeddings more accurate and cheaper to produce. MCP, Anthropic's Model Context Protocol, carries context around during a conversation, and OKF can sit below it as the source those tools draw from. MCP handles the flow while OKF holds the definitions, so nobody re-derives them each time. The three layers look like this:

OKF
↓
"What does this concept mean?"

RAG
↓
"Which pieces of knowledge should I retrieve?"

MCP
↓
"How does the agent interact with the tools and context?"

Each layer solves a different problem, so OKF is better seen as a shared knowledge layer beneath both than as a rival. Markdown files hardly sound like a product launch, yet the dull option is sometimes the one that works.

Should you use it?

For any agent that answers questions about your data, metrics or systems, the answer is yes, give it a go. Trying costs almost nothing: write three files, link them, point the agent at the folder, and an afternoon tells you whether it helps. If your knowledge lives in one person's head or a messy wiki, OKF offers a dull, versionable place to finally write it down, which may be worth it with or without an agent. If you need strict schemas, typed relationships or heavy governance, it's too loose today, so keep your catalog and maybe export a bundle later.

Don't start with the entire company knowledge base. Pick one small area, for example:

metrics/
  active-user.md
  revenue.md
  conversion-rate.md

systems/
  payments-api.md
  orders-api.md

runbooks/
  payment-failure.md

Link the files, hand them to a single agent and measure what changes. That's a far better experiment than three months spent designing an enterprise OKF platform before showing it's needed.

A single required field and a folder of markdown won't cure bad documentation on their own. What they offer is a shared, boring, portable home for the good documentation a team already has, which is worth more than it sounds on paper.