Your Second Brain Finally Gets a Standard: Inside Google's Open Knowledge Format

I run five LLM-maintained knowledge bases on a Mac mini. One is a chief-of-staff catalogue of every project I work on. One holds my family’s health records. One handles household finance. One is the long-term memory of a companion agent I built for my wife. One tracks what I am learning. All five are directories of markdown files with YAML frontmatter, interlinked, curated by agents, searched locally. I built every one of them by feel, before the pattern had a name.

In April 2026, Andrej Karpathy gave the pattern a name. His “LLM wiki” gist collected around 40,000 stars and spawned a small industry of second-brain builds. And in June, Google did the thing that actually matters for the long run: they gave the pattern a spec. It is called the Open Knowledge Format, OKF for short, and it is one of the most quietly important releases of the year for anyone building with agents.

This post is a deep dive: why agents need knowledge bases at all, what Karpathy’s wiki pattern actually is, what problem OKF solves on top of it, how it compares to the conventional approaches (RAG, search layers like qmd, graph tools, Obsidian), and what happened when I audited my own knowledge base against the spec. Spoiler on that last one: I was one field away.

Why agents need a knowledge base in the first place

Agents have a memory problem, and it is not the context window.

A Claude Code session in one repo knows nothing about the project in the repo next door, even when one literally drives the other. A fresh session starts from zero on things you settled weeks ago. The knowledge exists: in your head, in scattered CLAUDE.md files, in a wiki nobody updated since 2019, in 47,000 messages of Slack scrollback. It exists. It just is not reachable by the agent doing the work right now.

I wrote a full post on this problem and the build-store-surface playbook for solving it: AI Is Downstream of Context. The short version is that a knowledge base an agent can query turns the same model from a plausible guesser into something that behaves like the senior engineer who has been on the team for five years. I will not repeat that argument here.

What that post did not cover is the part that has changed in 2026: you no longer have one agent. I have Claude Code on a Mac mini, a different assistant on the work laptop, scheduled agents running jobs overnight, and whatever ships next quarter. My wife’s companion agent and my chief-of-staff agent are different personas with different knowledge, on the same machine.

The moment you have more than one agent, your knowledge base stops being a private implementation detail and starts being an interface.

And interfaces need standards. That is the whole story of OKF, but to see why, you first need the pattern it standardizes.

Karpathy’s LLM wiki: curate at write time, not read time

The default answer to “give the agent knowledge” in 2024 and 2025 was RAG: dump documents into a vector store, embed everything, retrieve chunks at query time. It works, and at large scale it is the right tool. But for personal and team knowledge it has a smell. The system never actually understands anything at rest. It pays the understanding cost on every single query, forever.

Karpathy’s llm-wiki gist flips the timing. Instead of indexing raw documents, the LLM reads each new source once, extracts what matters, and integrates it into a persistent wiki of interlinked markdown pages. Summaries, entity pages, concept pages, comparisons. When a new source arrives, the agent does not just file it; it updates every page the new information touches. Karpathy notes a single source might touch 10 to 15 wiki pages in one ingest.

His framing for the whole thing is the best one-liner in the gist:

Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.

The architecture has three layers:

graph TB
    subgraph RAW["raw sources, immutable"]
        A1["articles"]
        A2["transcripts"]
        A3["papers and plans"]
    end
    LLM["LLM maintainer
reads, extracts, integrates"]
    subgraph WIKI["the wiki, agent-owned"]
        W1["index.md"]
        W2["entity pages"]
        W3["concept pages"]
        W4["log.md"]
    end
    A1 --> LLM
    A2 --> LLM
    A3 --> LLM
    LLM --> W1
    LLM --> W2
    LLM --> W3
    LLM --> W4

Raw sources stay immutable; the human curates what goes in. The wiki layer belongs entirely to the agent. A schema file (in practice, your CLAUDE.md or equivalent) defines the conventions, and Karpathy calls it the thing that makes the LLM “a disciplined wiki maintainer rather than a generic chatbot.” Two housekeeping files hold it together: an index.md the agent reads first on every query, with one line per page, and an append-only log.md recording every ingest.

Why did this take off now? Because wikis were always the right shape and always failed for the same reason: the maintenance burden grows faster than the value. Humans get bored. Humans forget to update the cross-reference. Karpathy’s point is that LLMs do not get bored, do not forget the cross-reference, and can touch fifteen files in one pass. The exact property that killed wikis for humans is the one LLMs are best at.

The economics follow. A wiki pays the understanding cost once at ingest; from then on, queries are cheap file reads over pages where the cross-references already exist and the contradictions have already been flagged. RAG pays that cost at every query. For stable personal and team knowledge, curation at write time wins.

I can confirm this from the operating side: my five knowledge bases are exactly this pattern. Agents ingest sources, write structured pages, maintain indexes, and a human reviews the writes. It compounds. Pages written in May make the agent smarter in July.

The problem the gist left behind

Here is what happened after 40,000 people copied that gist: 40,000 structurally different wikis.

One person’s wiki has tags, another’s has categories. One nests entities under entities/, another spreads them flat. One links related concepts in a footer section, another inlines them, a third uses Obsidian-style wikilinks that plain markdown tooling cannot resolve. Every choice is individually reasonable. Collectively they mean no wiki can be read optimally by anyone else’s agent.

That is not a hypothetical annoyance. It kills real use cases: a team wiki that every member’s second brain reads independently. A knowledge bundle a creator shares with their audience. An enterprise handing curated context to a vendor’s agent. Even sharing your setup with a friend means they inherit your conventions or start over.

I felt this one personally. My chief-of-staff knowledge base has clean conventions: YAML frontmatter with a summary, status, linked repos, a next action per project. But they are my conventions. A fresh agent with no access to my CLAUDE.md cannot navigate the corpus optimally, because nothing tells it that summary is the field to quote in an index or that linked_repos encodes the project graph. The knowledge is portable in the trivial sense (it is just markdown) and non-portable in the real sense (no other agent knows the map).

A knowledge base without a shared convention is a private language. Useful to you, opaque to every other agent on earth.

Enter OKF: what Google actually standardized

On June 13, 2026, Google Cloud published the Open Knowledge Format: an open, vendor-neutral spec that formalizes the LLM wiki pattern into something portable. The spec fits on one page, and that is deliberate. It standardizes exactly two things: how files are organized, and what the metadata fields are. Nothing else.

The unit of distribution is a bundle: a self-contained directory of markdown files. Each file is a concept, one unit of knowledge. The file path is the identity; there is no separate ID scheme.

sales/
├── index.md              # reserved: directory listing
├── log.md                # reserved: update history
├── datasets/
│   ├── index.md
│   └── orders_db.md
└── tables/
    ├── orders.md         # concept id: "tables/orders"
    └── customers.md

Every concept file carries YAML frontmatter, and here is the part I respect most: the spec mandates exactly one field.

---
type: BigQuery Table          # the ONLY required field
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

type is required because it is what lets a consumer route, filter, and present concepts without reading them (“search only the videos”, “show me the runbooks”). Five more fields are recommended: title, description, resource, tags, timestamp. Everything else is a legal extension, and consumers must preserve keys they do not recognize. The spec’s own golden rule: “If it has frontmatter with type, it’s valid OKF.”

Two filenames are reserved. index.md is the progressive-disclosure entry point, sections of links each quoting the concept’s description. log.md is the date-grouped update history. Both are optional.

Links between concepts are plain markdown links, and the spec treats them as untyped directed edges in a knowledge graph. The relationship’s meaning lives in the surrounding prose, not in link syntax. And in a genuinely thoughtful touch, consumers must tolerate broken links: a link to a page that does not exist yet is valid, it marks knowledge not yet documented.

How does an agent actually use one of these? The same way skills work: progressive disclosure.

graph TB
    Q["question arrives"] --> I["read root index.md"]
    I --> F["filter by type and tags"]
    F --> C["read the matching concept"]
    C --> L["follow links if the answer needs them"]
    L --> A["grounded answer"]

Start from almost no context, drill down only where the question points, stop as soon as the answer is grounded. In Cole Medin’s demo of his own OKF bundle, a cold question resolved in four tool calls: index, section, concept, answer.

Conformance is equally minimal. A bundle is valid if every non-reserved markdown file has parseable frontmatter with a non-empty type, and the reserved files follow their conventions when present. A consumer must not reject a bundle for missing optional fields, unknown types, unknown keys, broken links, or a missing index. That asymmetry (strict about almost nothing, tolerant about everything else) is how formats survive contact with the real world.

How OKF differs from the conventional approaches

The question I kept asking during my research: I already have qmd running over markdown, I evaluated graph layers, I know RAG. Where does OKF actually sit? The answer is that most of these are not competitors. They are layers.

Only the first row is portable to another agent without translation, and that is the entire point of a standard. The other axes (who pays the understanding cost, and when) are unpacked below.

OKF vs RAG. Different timing of the same cost, as covered above. The OKF FAQ itself refuses the fight: bundles handle the known knowns (stable facts, canonical definitions, zero-latency file reads), RAG handles exploratory queries over corpora too big to curate. They stack. An OKF bundle is, in the FAQ’s words, ideal chunking material for a RAG pipeline. My earlier post has the full storage-pattern comparison if you want the trade-offs in detail.

OKF vs qmd. This is the one I personally needed to settle, because qmd is the retrieval engine under all five of my knowledge bases: BM25 plus local vectors plus reranking, about 30 milliseconds per query, everything on-device. The answer is that OKF vs qmd is a false choice. OKF is the storage and interchange layer: how files are organized and tagged. qmd is the retrieval layer: how an agent finds the right file fast. Adopting OKF conventions changes nothing about qmd; it makes the same corpus legible to consumers that are not qmd. OKF’s built-in traversal story (read the index, drill down, keyword search) is exactly what Cole Medin’s little CLI does, and a semantic search layer on top strictly improves it. My stack already runs both roles; the spec just names the seam between them.

OKF vs graph layers. Here OKF takes an actual position, and it surprised me. I spent weeks this spring evaluating graph tools for my chief-of-staff KB: Mnemon (an agent-memory graph store) and Graphify (a folder-to-knowledge-graph builder). I declined Graphify because my corpus is curated prose and its LLM edge extraction would have meant either shipping family-sensitive documents to a cloud model or settling for slow local extraction. I deferred Mnemon until real cross-project questions demand it. OKF’s stance validates both calls: the markdown links are the graph. Untyped edges, meaning in the prose, and graph structure is a consumer-side derivation. Google ships a static HTML visualizer that builds the graph view from the links, no backend, no LLM. If you need formal semantics, a W3C community group is layering an optional RDF-compatible profile called DataBook on top, with the storage unchanged. Nobody in this ecosystem is putting a graph database under the knowledge. The graph is derived, on demand, from links agents already write.

OKF vs Obsidian. Same markdown DNA, different optimization target. Obsidian optimizes the human: wikilinks, graph view, plugins, a beautiful editing surface. OKF optimizes interoperability: standard markdown links that any tool resolves, a mandatory type for programmatic consumption, conventions a consumer can rely on sight unseen. An Obsidian vault can absolutely hold an OKF bundle (the files are just markdown), and “Obsidian as the IDE” survives intact. What changes is that the vault stops being a private language.

The receipts: I audited my own KB against the spec

Talk is cheap, so here is the concrete test. I took my chief-of-staff knowledge base, a catalogue of 20-plus projects that agents on my machine read every day, and mapped its hand-rolled frontmatter onto OKF field by field.

My knowledge base, built over months with zero knowledge of any spec, is one frontmatter field away from OKF conformance. Every convention I invented independently landed on either a recommended field or a legal extension. Even my index-first design (a README table agents read on activation) is OKF’s index.md idea under a different filename, which the spec does not even require.

I do not think that means I am clever. I think it means the spec is honest. Google standardized what practitioners were already converging on instead of inventing a data model and asking the world to migrate. That is the same play that made AGENTS.md and CLAUDE.md conventions stick, and it is why I expect this pattern (if not necessarily this exact spec) to survive.

The best standards do not tell you to change what works. They name what everyone already built, so the next person’s agent can read it too.

The adoption cost for an existing markdown KB is accordingly tiny: one scripted pass adding type: to frontmatter. Search layers ignore the extra field. Nothing breaks. The upside is every OKF-aware consumer, present and future, can now navigate your corpus cold.

Other things worth knowing about OKF

Producer and consumer are formally decoupled. A bundle hand-written by a human, generated by a metadata pipeline, or synthesized by one LLM can be consumed by a different human, agent, or visualizer, with no coordination between the two sides. This sounds abstract until you realize it is the property that makes every use case below possible.

Bundles are becoming a distribution channel. This is the sleeper feature. Cole Medin has started packaging his best videos as an OKF bundle on GitHub: transcript-verified concept pages and video summaries you mount into your own second brain and query, instead of scrubbing through hours of footage. Point your coding agent at the spec, then at the bundle, and you can ask “what is his mental model for reliable AI coding” and watch it drill to the answer. Knowledge as a shippable artifact, from any creator to any agent, is a genuinely new primitive, and it only works because both sides speak the same format.

It stacks with the other AI-content standards. schema.org tells search engines what a public page is. llms.txt tells AI crawlers where to go on your site. OKF tells your own agents what you or your organization actually knows, private by default. They compose rather than compete; your llms.txt can point at a public OKF bundle.

The “too simple” critique, and why it misses. The Hacker News reception was predictably spiky: markdown plus frontmatter is not new, Obsidian users have done this for years, the semantic web tried richer versions of this every decade. All true. And all beside the point. Successful infrastructure standards look obvious in hindsight because they win by cutting coordination cost, not by being technically exotic. The complexity in knowledge systems lives in the integration, not the representation. A spec thin enough that my hand-rolled KB accidentally almost conforms is a feature. Minimally opinionated is the design goal, stated right in the spec.

The critique that does land: OKF does not solve curation. The sharpest HN worry is real. LLM-maintained knowledge systems drift: context bloat, stale references, entity pages that quietly contradict each other. OKF standardizes structure and says nothing about discipline. My answer, learned the hard way, is a human-in-the-loop write path: agents propose knowledge-base updates into a review queue, a human confirms diffs before they land, git records everything. I wrote about the drift failure mode in the previous post; letting agents edit the KB autonomously remains the fastest way to un-earn your team’s trust in it. Adopt OKF for the format. Keep a human on the merge button.

Should you adopt it?

If you already keep knowledge in markdown, with or without knowing about any of this, my honest read after a week inside the spec, the critiques, and my own audit:

Adopt the conventions now. The cost is one frontmatter field and optionally an index.md per folder. The payoff is that your knowledge stops being a private language. My own next steps are exactly that: a type: pass across all five knowledge bases, then the real test, handing a fresh agent nothing but the OKF spec and checking whether it can navigate my chief-of-staff KB cold, no CLAUDE.md, no tribal knowledge.

Do not adopt it expecting new capability on one machine. OKF gives you nothing that your existing setup plus a good search layer does not already do locally. The value is at the boundaries: the second agent, the second machine, the second person. But in 2026, everyone hits those boundaries faster than they expect.

Hold the specific spec loosely, and the pattern tightly. Cole Medin himself doubts OKF v0.1 ends up being the standard, and I agree; something will. Markdown files, frontmatter with a type, an index for progressive disclosure, links as the graph: that shape has now been independently discovered by Karpathy, by Google, by thousands of second-brain builders, and by at least one guy with five knowledge bases on a Mac mini. The shape is the bet, and it is a safe one.

The wiki was always the right idea, waiting for a maintainer that never gets bored. Now it has one, and a shipping format too.

Sources

• Karpathy’s llm-wiki gist, the origin of the pattern
• OKF specification and FAQ and the spec repo with reference implementations
• Google Cloud’s OKF announcement
• Cole Medin’s video on OKF and his AI-coding knowledge bundle
• Hacker News discussion of OKF
• okf-skills, Claude Code tooling for authoring and validating bundles
• qmd, the local search layer referenced throughout

For more on agentic engineering, including the knowledge-base playbook this post builds on, subscribe to The Agentic Engineer on YouTube. The research behind this post was run by my chief-of-staff agent, whose knowledge base is, fittingly, one field away from OKF.