Google's Open Knowledge Format is just Markdown in folders (and that's the point)

Google Cloud published the Open Knowledge Format (OKF), a specification for structuring knowledge as a folder of Markdown files with YAML frontmatter and links, designed to be readable by AI agents. The format requires no database, SDK, or runtime, relying instead on a folder tree with index.md files for discovery and a log.md for history. A developer building Hjarni, a Markdown knowledge base with MCP server support, added OKF export and import, demonstrating the format's portability across tools.

Last week Google Cloud published the Open Knowledge Format https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing 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 --- Deploy 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 loading everything. --- type: Collection title: Projects --- 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.