Google recently shipped a new open spec called the Open Knowledge Format, or OKF. Their core argument is simple and, frankly, hard to disagree with. Large language models are no longer held back mainly by raw intelligence. They’re held back by context.
If a model doesn’t understand your app, your business, your systems, or your internal vocabulary, it can still sound clever while getting the important details wrong. That gap is exactly what OKF tries to solve.
The idea is to package curated knowledge in a format that agents can actually use. Google describes it as a vendor neutral open standard that formalizes the LLM wiki pattern into a portable set of markdown files. In plain English, that means taking the loose idea of an AI friendly wiki and giving it enough structure that different tools can share it.
This matters because context is now a first class problem in AI systems. If agents are going to do useful work inside real products, they need more than access to a model. They need access to a clean, understandable map of the domain they operate in.
What OKF actually is
At its core, OKF is a directory of markdown files with YAML front matter. If that sounds familiar, it should. It’s very close to patterns that tools like Notion, Obsidian, and markdown based knowledge systems have used for years.
That’s also why the announcement sparked immediate debate. Some people see this as Google taking Andrej Karpathy’s LLM wiki idea, adding a schema, and publishing it as a standard. Others see it as the first serious attempt to create an open format for agent knowledge that different tools can actually exchange.
I think both sides have a point.
The concept clearly draws from Karpathy’s earlier gist. Google is not hiding that. At the same time, formalizing a useful pattern into a shared spec can be genuinely valuable. A lot of important standards look obvious in hindsight. The hard part is not always inventing the idea. Sometimes it’s getting enough consistency around it that other people can build on top of it.
That’s where OKF gets interesting. It takes the loose shape of an LLM wiki and turns it into a structured knowledge bundle. The result is portable, auditable, and easy to store in version control.
Why this idea has a real chance of spreading
Open conventions can catch on very quickly when they solve a real pain point. I’ve already seen this with agent skills. The idea there is also remarkably simple: a folder with markdown files that teaches an agent how to perform a task.
That pattern has spread fast because it works. It’s easy to author, easy to inspect, and easy for an agent to load on demand.
OKF has a similar feel. It uses a near identical markdown first approach, but it serves a different job. That distinction matters.
- Skills tell an agent how to do something.
- OKF tells an agent what you know.
One is procedural know how. The other is declarative knowledge.
A skill might explain how to process invoices or how to deploy a service. An OKF bundle might describe your customer model, your API endpoints, your permission system, or the workflows inside your product.
Those are different layers, but they fit together nicely. A skill can point to an OKF bundle for the knowledge it needs. That means the execution logic and the domain context can remain separate while still working together.
I used OKF to document a full stack AI agent app
To test the spec properly, I used it on a real application I’m building. The app is a full stack AI agent platform built with Supabase, React, and Python.
Rather than hand writing every page, I pointed a coding agent at the codebase and had it perform a deep pass across the project to generate a full knowledge layer. The result was a browsable LLM wiki with roughly forty five concept files, each cross linked into a graph.
That was useful for two reasons.
- It showed that the format is practical outside Google’s own stack.
- It made the app transferable in a way that raw source code often isn’t.
Source code contains truth, but it doesn’t always contain the clearest explanation. A curated knowledge layer sits above the code and describes the system in a form that an agent can traverse more intelligently.
In my case, the graph represented several kinds of concepts:
- Workflows in orange
- API endpoints in blue
- Front end surfaces in pink
That gave me a map of the product’s feature set and technical interfaces. If I wanted to share the application context with another person, another team, or another coding agent, I could simply share the knowledge bundle.
That is the real promise of this format. It turns domain context into something portable.
What portability actually means here
Portability sounds abstract until you picture how it works in practice.
An OKF bundle can be zipped and sent. It can live in a GitHub repository. It can be versioned, diffed, reviewed, and updated over time. It can be imported into a coding agent, a documentation tool, or a personal knowledge system.
That gives you a clean path for sharing context across tools and across teams.
Instead of saying, “Here is the codebase, good luck,” you can say, “Here is the knowledge layer that explains the codebase, the workflows, the resources, and the relationships.”
This is where the open standard angle becomes important. If enough tools agree on the same file layout, front matter, and reserved names, the friction of exchanging context drops a lot.
Of course, that depends on adoption. A standard is only a standard if people use it.
How OKF differs from Karpathy’s original LLM wiki idea
Karpathy’s gist introduced a strong pattern. Google’s spec takes that pattern and formalizes it.
The most obvious difference is that OKF introduces stricter conventions around file structure and metadata. There’s mandatory front matter, reserved file names for interoperability, and a more explicit folder layout.
The nice thing is that the spec remains lightweight. There’s only one truly required field in the front matter: type.
Everything else is optional, though recommended. That includes fields such as:
- title
- description
- resource
- tags
- timestamp
You can also add extra keys for your own use case. That flexibility is good. It keeps the format simple enough to use without forcing everyone into a heavy ontology.
At the same time, OKF adds one major structural feature that changes how agents can use the bundle: index files.
Why index files are one of the best parts of the spec
OKF includes a global index file and can also include index files inside subdirectories. These indexes act like compact guides to what exists in each section of the knowledge bundle.
That’s a small idea with a big payoff.
Without index files, an agent mostly sees a folder tree and has to infer meaning from file names. With index files, it can load a summary of the directory first and decide where to go next.
That creates a progressive disclosure pattern, which is exactly what you want when context windows are limited.
The agent doesn’t need to read everything up front. It starts broad, then drills down.
This is very similar to how agent skill registries work. The system first exposes a compact list of available options. Then it loads the detailed material only when needed.
For large knowledge bases with hundreds or thousands of files, that’s a big improvement. It makes traversal easier and reduces the chance that the agent loads the wrong material or too much material at once.
There is one awkward side effect right now. Tools like Obsidian don’t currently support the spec directly, so those index files appear as extra notes in the graph and can clutter the view a bit. From an agent’s perspective they are helpful. From a human graph view, they can look noisy.
That’s a tooling issue rather than a flaw in the concept, but it does show why adoption matters. The experience gets much better when the ecosystem understands the convention.
How the concept pages work
Each knowledge document in OKF represents a concept. That concept could be a customer entity, an API route, a workflow step, a data table, or a feature like PII redaction.
The concept ID is essentially the file path. So a path like tables/users.md identifies a specific concept within the bundle.
Each file contains two main parts:
- YAML front matter at the top
- The markdown body underneath
The body can contain standard markdown links to other concepts. Those links create the edges in the graph. It can also include citations to external sources that support claims made in the page.
That combination gives you a structure that is easy for both humans and agents to inspect:
- Readable in plain text
- Diffable in Git
- Cross linked like a wiki
- Loose enough to support many domains
The resource field is one of the smartest details
One field in particular deserves attention: resource.
This field lets a concept point to the actual source of truth. That could be a Python file, a database table, an API endpoint, or some other live system.
That’s a much better pattern than copying everything into the markdown file.
If a concept page about PII redaction points at the real Python file that implements the feature, the page can stay thin. It can summarize the concept, explain its role, and connect it to related ideas without duplicating all the implementation details.
This matters because curated knowledge goes stale very easily.
The more data you duplicate into your knowledge layer, the more maintenance overhead you create. By pointing to live sources where possible, you reduce drift and keep the wiki focused on explanation rather than raw duplication.
That thin layer approach is, in my view, one of the strongest parts of the LLM wiki pattern. You want the knowledge page to orient the agent, not become a bloated shadow copy of the underlying system.
Why this is not the same thing as RAG
A lot of people immediately frame LLM wikis and formats like OKF as the thing that kills RAG. I think that’s mostly a category mistake.
They solve different problems.
An LLM wiki or OKF bundle is a curated knowledge layer. You prepare and maintain the answer structure in advance. You decide what concepts matter, how they relate, and how they should be described.
RAG, on the other hand, is about retrieving relevant information from a source set at query time. It is a retrieval strategy.
Those approaches can complement each other perfectly well.
Here’s the simplest way to think about it:
- Compiled knowledge gives the agent a curated map.
- RAG helps the agent fetch supporting detail when needed.
Naive RAG, where you chunk everything blindly and hope similarity search saves the day, is clearly weak. That approach deserves most of the criticism it gets.
But agentic RAG remains useful. An agent can use a curated knowledge layer to understand where to look, then use retrieval to pull the freshest or deepest material from the underlying sources.
So I wouldn’t frame OKF as anti RAG. I’d frame it as a better context layer that can sit alongside retrieval.
The librarian pattern is where this gets really compelling
One of the strongest ideas behind the LLM wiki pattern is making the model itself act like the librarian.
Humans are usually bad at maintaining wikis over time. Cross references break. Pages drift. Updates get skipped. Structure decays.
Language models are good at exactly that kind of repetitive bookkeeping. They don’t get bored. They can scan many files in one pass. They can update references consistently across a system.
That doesn’t mean they should operate without oversight. It means they’re well suited to the maintenance layer.
Google pushed this idea further by including a reference agent in the repo. This is effectively a producer agent for generating and updating OKF documents.
The clever part is that they pair the free form markdown format with deterministic validation guardrails.
How the type field enables validation
Remember that the only required front matter field is type. That field doesn’t just describe the concept. It can also drive custom logic in the tooling that creates or updates the page.
For example, if a page has the type BigQuery Table, the producer agent can apply validation rules specific to that kind of object.
In Google’s examples, that includes checks like:
- Making sure a URL was actually fetched before the page claims to use it
- Preventing rewrites that would shrink or damage a verified schema
- Refusing edits that drop citations from the end of the document
That’s a very useful pattern.
It means the wiki is not just free form text generated by a model. The generation and maintenance process can be wrapped in rules that verify certain facts before updates are accepted.
Those checks sit in the harness around the agent. They control how files get written and edited. You could build similar controls around other LLM wiki workflows too, but it was smart to make this part of the reference implementation.
It shows how a soft format can still support harder guarantees where needed.
What makes the format attractive
There’s a lot to like about the overall shape of OKF.
- Plain markdown keeps it readable and tool friendly.
- YAML front matter gives enough structure without making authoring painful.
- Git friendly files make changes easy to audit and review.
- Open and portable avoids locking your knowledge layer inside a proprietary product.
- Interlinking creates a useful graph structure for both humans and agents.
- Index files improve traversal on large bundles.
For teams building AI agents, that combination is appealing. Context engineering is quickly becoming one of the biggest practical bottlenecks in agent quality. A standard knowledge container helps.
If you want the original announcement, Google’s OKF introduction and the public GitHub repository are the key references. The full specification is also worth reading directly because it is relatively compact.
For historical context, Karpathy’s original LLM wiki gist makes it easy to see how the idea evolved.
Where the format falls short
For all its strengths, OKF standardizes the container much more than it standardizes the meaning.
That is an important limitation.
Suppose I create a bundle and use type: customer. Someone else creates a bundle and uses type: client for the same concept. The files are still structurally valid, but semantically they do not line up automatically.
There is no central registry of types. They are free text.
That keeps the spec flexible, but it also means merged bundles can end up with overlapping concepts that don’t reconcile cleanly.
The same problem appears in the links. A markdown link tells you that one concept is related to another. It does not tell you the exact kind of relationship in a machine readable way.
You can say that PII redaction links to security or document knowledge data, but the edge itself is not typed. It might mean “depends on,” “belongs to,” “protects,” or “uses.” The relationship exists, but its meaning lives in the surrounding text.
That’s fine for many workflows, but it limits comparability and deeper reasoning across bundles.
So I’d put it like this:
- OKF makes knowledge portable.
- It does not automatically make knowledge semantically aligned.
The harder problem is curation, not structure
File structure is the easy part. Curation is the hard part.
You can generate a beautiful knowledge bundle today and still end up with a poor context layer a month from now if you don’t maintain it properly.
That happens because a curated knowledge layer is a duplicate of something you already own. Your real sources of truth might be code, docs, APIs, databases, or internal systems. The wiki sits above them as a compiled artifact.
Once that duplicate exists, drift becomes a risk.
An update lands in the codebase. A table schema changes. A workflow is removed. An endpoint gets renamed. If the knowledge bundle does not update with those changes, the context layer becomes stale.
And stale context is dangerous because it is highly believable. The markdown page still looks clean and organized. The agent can still read it fluently. It is just wrong.
That’s why this pattern works best when the maintenance loop is automated.
You want an LLM or agent process that can react to:
- New files
- File changes
- Deleted resources
- Schema updates
- Broken links
Then you still want human review over time, especially for high value concepts. The model can do the bookkeeping. Humans still need to judge whether the summary is accurate and useful.
The basic OKF structure in plain English
The spec introduces a few core terms that are worth translating into simpler language.
Knowledge bundle
A self contained collection of knowledge documents arranged in folders.
Concept
A single unit of knowledge, such as a customer, feature, table, endpoint, or workflow.
Concept ID
The path to that file inside the bundle.
Front matter
The YAML metadata block at the top of the file.
Body
The markdown content that explains the concept.
Links
Standard markdown links that connect one concept to another.
Citations
External links that support claims made in the concept page.
The bundle can also include:
- A global index file
- Index files inside subfolders
- An optional log file
There are no required body sections. That is another nice touch. The format gives examples, but it does not force every concept into the same rigid template.
Why Google’s positioning may hurt adoption
Ironically, the biggest threat to OKF may be how Google packaged it.
On paper, this is a vendor neutral format. In practice, the repo and examples feel very Google centric. The reference setup leans on BigQuery, Google Knowledge Catalog, and Gemini powered enrichment.
That can create the impression that the spec is more tied to Google Cloud than it really is.
I think that’s a mistake.
The most interesting thing about OKF is that you do not need Google’s full stack to use it. I generated an OKF aligned knowledge layer for my own application without depending on that ecosystem. The format works perfectly well as a plain markdown convention with optional tooling around it.
If Google had presented it more aggressively as a lightweight open convention rather than surrounding it with their own product story, I suspect more people would warm to it faster.
Developers are usually open to useful standards. They are much less open to standards that look like product funnels.
