Last week Google Cloud published the Open Knowledge Format (OKF). It is a way to write down what a team knows so that AI agents can read it.
Strip the announcement and it is refreshingly small: a folder of Markdown files, with a little YAML frontmatter, that link to each other. No database. No SDK. No runtime. The core idea fits on a page.
A knowledge base is a folder tree. Each note or resource is one Markdown file.
my-brain/
├── index.md # a map of this folder
├── log.md # change history
├── projects/
│ ├── index.md
│ ├── architecture-decisions.md
│ └── deploy-runbook.md
└── customers/
├── index.md
└── acme-interview.md
Each document carries frontmatter. The only required field is type
. Everything else is optional.
---
type: Note
title: "Deploy runbook"
timestamp: 2026-05-12T09:30:00Z
description: "How we ship to production, including the rollback path."
tags: [ops, runbook]
---
Promote from staging once CI is green.
See [architecture decisions](architecture-decisions.md) for why.
Two things make it more than a pile of files:
index.md
per folder is a type: Collection
document, so an agent can discover context gradually instead of everything.
---
type: Collection
title: Projects
---
## Notes
- [Architecture decisions](architecture-decisions.md)
- [Deploy runbook](deploy-runbook.md)
That is the entire idea. Files, frontmatter, folders, links, plus a log.md
for history.
The problem OKF targets is the one you hit the moment you point an agent at your own knowledge. The context it needs is scattered across a metadata catalog, a wiki, code comments, and a few people's heads. Every agent builder reassembles it from scratch, and the knowledge stays locked in whatever tool held it.
OKF's answer is boring in the best way: stop inventing proprietary formats. Write the knowledge as files an agent can read, in a shape everyone agrees on. The format is the contract. The tool that produces it and the tool that consumes it can change independently.
For developers the payoff is familiar: it is just files. You can diff it, put it in a Git repo, grep it, render it on GitHub, and feed it to any agent that reads Markdown. Knowledge that lives in one vendor's database is only as useful as that vendor's AI. Knowledge written as plain, linked files travels.
Disclosure: I build Hjarni, a Markdown knowledge base with a built-in MCP server, so Claude and ChatGPT can read and write your notes.
When I read the OKF spec, it felt familiar. Hjarni's model already had the same bones: Markdown notes, nested folders, tags, and links between notes.
So we added OKF export and import. Export writes one Markdown file per note with type
frontmatter, an index.md
per folder, a root index.md
, a log.md
, and relative Markdown links rewritten from wiki-links. Import reads that structure back in.
That round trip matters. A format is not very portable if it only works as an escape hatch. OKF is more useful when tools can both produce it and consume it.
Most days you do not export at all. Through the MCP server, Claude and ChatGPT read your notes live, so the knowledge is current. OKF is for the day you want the files to leave with you.
Google Cloud choosing Markdown, folders, and links is the interesting signal. Agent-readable knowledge does not need to start with a database.