What Is the Open Knowledge Format (OKF)? The Complete Guide

The Open Knowledge Format (OKF) is an open, vendor-neutral standard for giving AI agents curated context as a simple directory of markdown files with YAML frontmatter. Google Cloud introduced it in June 2026 as a way to represent the metadata, business context, and curated knowledge that modern AI systems need, in a form that is portable across teams, tools, and vendors. No proprietary SDK, no runtime, no lock-in. Just files you can read, diff, version, and hand to any agent.

If you have spent any time trying to make AI agents actually useful on your own data, you have felt the problem OKF is built to solve. The context lives everywhere and nowhere: in a catalog with a proprietary API, in a wiki, in code comments, in the heads of two senior people. Every new agent has to reassemble it from scratch. OKF is the attempt to make that context a portable artifact instead of a per-tool rebuild.

What is the Open Knowledge Format (OKF)?

OKF is an open specification, published by Google Cloud in 2026, for representing knowledge as a directory of markdown files with YAML frontmatter. Each file is one concept. The only required field is type. It is designed to be authored by people, generated by agents, exchanged across organizations, and read by both humans and machines without any translation layer.

This guide covers what OKF is, why it exists, exactly how a bundle is structured, how to build one, and how it fits with the other agent-context standards you have probably heard of (MCP and llms.txt). We build on this format directly, so we will also show what it looks like in practice.

Why the Open Knowledge Format exists

Organizational knowledge is fragmented by default. Table schemas live in a data catalog. Runbooks live in a wiki. Positioning lives in a slide deck. Decision history lives in Slack threads and people's memory. Each system speaks its own dialect, and most of them lock their knowledge behind an API or an account.

That fragmentation has a cost that compounds once you add AI agents. Every agent builder assembles context from scratch. Every catalog vendor reinvents the same data model. Knowledge stays trapped inside whichever tool happened to create it. The result is that the most valuable thing you have, the curated understanding of your business, is the least portable.

OKF's answer is deliberately boring, and that is the point. Make the knowledge plain files. Markdown is readable in any editor, renders on GitHub, and is already what large language models are best at consuming. YAML frontmatter adds just enough structure to be queryable without inventing a schema language. Because it is just files, a bundle ships as a tarball, lives in a git repo, or mounts on any filesystem. The format is the contract, and the tooling at each end stays independently swappable.

How OKF works: the structure of a bundle

An OKF bundle is a directory of markdown files organized by concept. The structure is small enough to hold in your head:

• One concept per file. The file path is the concept's identity. A file at tables/orders.md has the concept ID tables/orders.
• Each file has YAML frontmatter plus a markdown body. The frontmatter carries structured, queryable fields. The body is free-form content for humans and agents to read.
• Links are relationships. A standard markdown link from one concept to another asserts that the two are related. The directory becomes a graph.
• Two reserved filenames. index.md is a directory listing for progressive disclosure. log.md is a dated change history. Everything else is a concept.

Here is a single concept file. Note how little ceremony there is:

---
type: Positioning
title: Positioning
description: Where the brand sits in the market and why it wins.
tags: [brand-core, positioning]
timestamp: 2026-06-17T12:00:00Z
---
# Positioning

Acme helps mid-market ops teams ship faster. The strategic
foundation every other document builds on.

## Informed by
- [Company Profile](/substance/company-profile.md)
- [Competitive Landscape](/substance/competitors.md)

The frontmatter is the only part the spec is opinionated about, and even there it asks for almost nothing.

Field	Required?	What it means
type	Yes	A short string naming the kind of concept. Consumers use it for routing, filtering, and presentation.
title	Recommended	Human-readable display name. Consumers may derive one from the filename if it is absent.
description	Recommended	A single sentence summarizing the concept.
resource	Recommended	A URI identifying the underlying asset the concept describes. Absent for purely abstract ideas.
tags	Recommended	A list of short strings for cross-cutting categorization.
timestamp	Recommended	ISO 8601 datetime of the last meaningful change.

type is the only required field. Producers are free to add any custom keys they want, and consumers are required to preserve keys they do not recognize. That single decision, one required field and unlimited optional ones, is what lets a hand-authored bundle and a machine-generated one share the same format.

What makes an OKF bundle valid (conformance)

The conformance rules fit in three lines. A bundle is conformant when every non-reserved markdown file has parseable YAML frontmatter, every frontmatter block has a non-empty type, and the reserved index.md and log.md files follow their simple structure when present.

The more interesting half of conformance is what consumers are not allowed to do. A consumer must not reject a bundle for missing optional fields, unknown type values, unknown frontmatter keys, broken cross-links, or missing index files. This permissive model is intentional. Bundles grow, get refactored, and are partially generated by agents. OKF is designed to stay useful while messy, which is the realistic state of any living knowledge base.

How to create an OKF bundle, step by step

You do not need any special tooling to produce OKF. You need a folder and a text editor. Here is the practical path.

1. List your concepts. Write down the distinct things worth capturing: a metric, a table, a runbook, a positioning statement, a customer profile. Each one becomes a file.
2. Make one markdown file per concept. Group related concepts into directories. The path is the identity, so choose stable, descriptive names you will not want to rename later.
3. Add frontmatter with a type. Open each file with a YAML block and at minimum a non-empty type. Add title, description, tags, and timestamp when you have them.
4. Write the body in plain markdown. This is the actual knowledge. Headings, lists, tables, and prose. Write it for a smart reader who is new to the topic, because that reader might be a model.
5. Cross-link related concepts. Use normal markdown links, either absolute from the bundle root (/tables/orders.md) or relative (./orders.md). Each link is a relationship; describe the kind of relationship in the surrounding prose.
6. Add an index.md per directory. A short listing of the concepts in that folder, each line a link plus its description. This gives an agent progressive disclosure instead of forcing it to read everything.
7. Track changes in log.md (optional). A dated, newest-first list of what changed. Useful for both humans and agents that want to know what is fresh.
8. Declare the version and ship it. Put okf_version: "0.1" in the bundle-root index.md frontmatter, then distribute the folder however you like: a git repository (recommended), a tarball, or a subdirectory of a larger repo.

That is the whole job. The format rewards curation, not engineering. The hard part was never the syntax; it is deciding what is worth writing down and keeping it true.

OKF vs MCP vs llms.txt: how they fit together

OKF arrives into a small but confusing landscape of "standards for giving AI context," and it is easy to assume they compete. They do not. They sit at different layers and compose cleanly.

	OKF	MCP	llms.txt
What it is	A format for knowledge at rest	A protocol for live tool access	A discovery index
Layer	Representation	Transport and runtime	Discovery
Form	A directory of markdown files	A server an agent calls	A single text file
Answers	How is the knowledge written down?	How does an agent fetch it live?	What is here and where do I start?

A useful mental model: OKF is the payload, MCP is the pipe, and llms.txt is the map. You can serve an OKF bundle's contents through an MCP server, and you can point to both from an llms.txt index. They are complementary tools for the same goal, getting the right context in front of an agent, and notably OKF sits one layer below transport, so it does not depend on MCP at all.

OKF and brand knowledge: the highest-value use case

The clearest place this pays off is brand knowledge. A brand's positioning, voice, audience, messaging, competitors, and differentiation are exactly the kind of slow-changing, high-value context that every AI tool, freelancer, and team member needs and almost nobody has in one portable place. It is the durable layer of a marketing operation, and it maps onto OKF almost perfectly: one concept per document, frontmatter that types each one, links that connect positioning to messaging to audience, an index for navigation, a log for change history.

This is the shape we already build. Brand Architect turns your website or your materials into a complete brand architecture, a 12-facet brand memory that is the single source of truth for your brand, and it exports that brand memory as an OKF bundle natively. Ophelia, your always-on brand strategist, builds and maintains the documents; you review and approve every output; and any OKF-aware agent, editor, or catalog can read the result directly. No proprietary format, nothing to translate, nothing locked in.

OKF best practices

A few habits separate a bundle that stays useful from one that rots:

• Manage it like code. Keep the bundle in version control alongside the work it describes. Review changes in pull requests. The history is part of the value.
• Let agents do the upkeep. Models do not get bored, do not forget to update a cross-reference, and can touch fifteen files in one pass. Have them propose updates; have people approve them.
• Use progressive disclosure. An index.md at each level lets a consumer read a map before it reads the territory, which keeps context windows lean.
• Keep it true, not big. A small bundle that is current beats a large one that is half stale. Curate by what is durable, and prune aggressively.
• Write for a smart stranger. The best concept docs are legible to a new hire and a model alike. If a human cannot follow it, an agent will not either.

Frequently asked questions

Who created OKF and is it free to use?

Google Cloud published OKF v0.1 in June 2026 as an open specification on GitHub, alongside reference implementations and sample bundles. It is open and vendor-neutral by design. You never need a proprietary account or SDK to read, write, or serve a bundle, and the spec welcomes contributions and alternative implementations.

What does an OKF bundle actually look like?

It is a folder of markdown files. Each file is one concept and opens with a small YAML frontmatter block (at minimum a type field), followed by a normal markdown body. Files link to each other with standard markdown links, and two reserved filenames, index.md and log.md, handle navigation and change history.

What is the difference between OKF and MCP?

OKF is a format for knowledge at rest; the Model Context Protocol (MCP) is a protocol for an agent to call tools and fetch context live. OKF describes how the knowledge is written down; MCP describes how an agent reaches it at runtime. They compose: you can serve an OKF bundle's contents through an MCP server.

Is OKF the same as llms.txt?

No. llms.txt is a single discovery file that tells an agent what is available at a site and where to find it. OKF is the actual body of knowledge, structured as many files. llms.txt is the map; OKF is the territory. They work well together.

How do I create an OKF bundle?

List your concepts, make one markdown file per concept with a type in its frontmatter, write the body in plain markdown, cross-link related concepts, add an index.md per directory, optionally track changes in log.md, declare okf_version in the root index, and ship the folder as a git repo or tarball. No special tooling is required.

Does Brand Architect support the Open Knowledge Format?

Yes. Brand Architect produces OKF natively. Your brand memory exports as a portable OKF bundle (as well as markdown or JSON, a shareable link, or live access over MCP), so any OKF-aware agent or tool can read your brand's source of truth directly, with no lock-in.

OKF is young, but the idea under it is not: curated knowledge, written as plain files, owned by you, readable by any agent. If you want practitioner notes on building AI systems that compound, the newsletter goes out weekly. If you would rather have your brand's version of this built for you, Brand Architect is where to start.