The standard that is just a folder (and why it should matter to you)

Three weeks ago Google published a specification that is, underneath everything, a folder of text files. No database, no SDK, no server. A folder with markdown files in it.

It sounds too plain to matter. It matters because it names a problem every small company already has, and that nobody had bothered to standardise: where does your knowledge actually live, and can a machine read it?

## What it is, plainly

It is called the **Open Knowledge Format**, or OKF. It came out of the Google Cloud blog on 12 June, at version 0.1, under an open licence. The idea fits in a sentence: represent an organisation's knowledge as a set of markdown files, each describing one thing (a table, a metric, a procedure), with a small structured header at the top and ordinary text below.

If you have ever used Obsidian, or a wiki, or even a well-organised folder in Google Drive, the shape will feel familiar. That is deliberate. Markdown is that plain text where you write `# Heading` for a heading and put a link inside square brackets. A human reads it in any editor; an AI model reads the very same file, with no translation in between.

The clever part is the links. Files link to each other with normal markdown links, and that turns the folder into a **map of relationships** rather than a loose list. The agent does not just see your pages: it sees how they connect. That relationship layer is exactly what a blind copy-and-paste throws away.

The sentence that unlocks the rest: **OKF standardises the container, not the meaning.** It agrees on the shape of the box. It does not agree on what you put inside. Hold on to that distinction, because we come back to it.

## The problem it solves

Think of everything you need to know to run a business that is never written down in one place. The exact meaning of a metric. The rule for how two systems talk to each other. The procedure for when something breaks. The reason a thing is done this way and not another.

That knowledge lives scattered: a bit in a catalogue, a bit in a wiki, a bit in code comments, and most of it in one or two people's heads. When you build an AI assistant to answer "how do I calculate this?", it has to stitch the answer together from these fragments, each in its own format. Google calls this the *context-assembly problem*, and the observation behind OKF is a good one: everyone building an agent is solving the same problem from scratch. What is missing is not another tool. It is a common format.

## The honest picture (the part that separates understanding from repetition)

This is where most writing about OKF trips over its own enthusiasm. Three things OKF is **not**:

**It is not SEO.** This will tempt anyone who works in search, and it is a trap. OKF is not a ranking signal. Google's search systems do not fetch your folder and rank you on it. It is an internal knowledge format for agents, not a web-publishing signal. A bundle will not move your traffic this week, or next.

**It does not solve meaning, only format.** This is the serious criticism, and it is a fair one. There is a difference between agreeing on the *layout* (folders, files, one required field) and agreeing on the *meaning* (what each type of thing denotes, what each relationship implies). OKF v0.1 solves the first and deliberately leaves the second open. In practice, two folders can both be perfectly valid and share no vocabulary at all: one writes `type: table`, another writes `type: Table` for the same thing. A link says two concepts are related, but not how. This will have to be resolved, and work has already started: on 19 June a community group formed to map OKF onto existing web standards, with a profile that adds formal meaning on top. But today, at v0.1, the container is standardised and the meaning is left to whoever writes it.

**It is not without risk.** A knowledge base that an agent can update on its own is also a way in. If the agent writes from sources you do not control, the folder becomes a channel for malicious instructions hidden in the text it swallows. It is worth deciding early who, and what, is allowed to write into it.

And there is the usual caveat with Google: the format really is open and requires no account, but the reference tools are all built in-house (the generator uses their model, the sample source is their database, the obvious ingestion path is their product). The gravity of the ecosystem still pulls towards Google Cloud, even when the licence does not.

## From the trenches

This is where it stops being theory. I do not write about OKF because I read the spec. I write about it because I live the problem it names.

For over a decade I have run a two-sided directory in the United States, with a data model that is anything but trivial. And almost everything that explains how the pieces fit together, the rules, the links between systems, the reason behind each architectural decision, lives in two places: my head and scattered configuration files. If I disappeared tomorrow, that knowledge would go with me. I am, quite literally, the "senior engineer whose knowledge is uncaptured" that Google describes, except that the whole organisation is me.

OKF hands me a concrete and uncomfortable question: what if that knowledge were a versioned folder, readable by me and by a machine, instead of living only where it lives now? Describing my own tables, metrics and joins in a bundle is exactly the scenario the format was designed for, only at the scale of someone working alone rather than a data team.

I have not named the product, on purpose. In a piece like this the name adds nothing: what convinces is the detail of the problem, not the brand. And that holds for any business, not just mine.

And you do not need to run a directory to have this problem. Picture a fine-art museum in Porto. The staff coordinate over WhatsApp. The opening hours live in a Word file someone updates now and then. The terms of a loaned artwork sit in a PDF from 2019, in the inbox of someone who has since left. The inventory is in one Excel sheet, the school-visits policy in another, and the website runs on a control panel nobody is quite sure who administers. The knowledge all exists. It is just scattered across half a dozen tools that do not talk to each other.

The day that museum wants to put an assistant on its website, or an internal helper for the gallery team, it hits a wall: there is no source of truth for the assistant to lean on. It invents opening hours, misquotes the terms of a loan, contradicts the group policy.

What OKF would give them is not magic technology. It is a discipline with a format: someone sits down and turns all of it into a readable folder, one file for ticketing, one per exhibition, one per loan, linked to each other. And even if they never build the chatbot, the simple act of building that folder forces the consolidation they never did. That is the real product.

## The long view

So is it worth it? Here you have to separate two things everyone runs together.

The format is not urgent. It is a version 0.1, a moving target, and in a year or two this will not look the way it looks now. If you put your knowledge in markdown in a folder today and the world converges on json tomorrow, or on a database schema, the migration is trivial. Nobody who understands the field will tell you a v0.1 is mandatory.

But the practice underneath is urgent, and on that there is no disagreement at all. Nobody who understands the landscape doubts that organisations need to free, consolidate and organise their knowledge into a single source of truth. OKF is only an early attempt to standardise the shape that might take. The Porto museum needed that work long before Google published anything, and will still need it when OKF is replaced by whatever comes next.

That is why the most interesting thing about OKF is not its technical depth, which is deliberately slight. It is that it names a layer that was missing, and makes visible a job most companies keep putting off. The format is incidental. The discipline is what counts.

And perhaps that is the thing worth keeping: the future of an organisation's knowledge may not be a smarter search engine or a better wiki. It is the decision, which you could already make today, to stop leaving your knowledge scattered across tools that do not talk to each other.