DEV Community

Evert
Evert

Posted on • Originally published at hjarni.com

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

#ai #markdown #opensource #agents

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.

The whole format on one screen

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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.
  • Links are plain Markdown links between files. Follow them and the folder becomes a graph an agent can walk. 
---
type: Collection
title: Projects
---

# Projects

## Notes
- [Architecture decisions](architecture-decisions.md)
- [Deploy runbook](deploy-runbook.md)
Enter fullscreen mode Exit fullscreen mode

That is the entire idea. Files, frontmatter, folders, links, plus a log.md for history.

Why a format, and why now

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.

How it maps to a real tool

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.

Try it

Google Cloud choosing Markdown, folders, and links is the interesting signal. Agent-readable knowledge does not need to start with a database.

Top comments (0)