- Published on
OKF and the Two Brains of an LLM Agent
- Authors
- Name
- Mattia Peretti
- @mattperetti
OKF is Google's Open Knowledge Format, and it formalizes something Andrej Karpathy had already sketched in a gist months earlier. Both point at the same realization: an LLM agent isn't one brain, it's two:
- frozen weights that can reason but never learn, and
- a wiki on disk that never reasons but never forgets.
This post traces that idea from Karpathy's original pattern through OKF's spec to why the two brains only work together.
What OKF actually is
OKF, published by Google Cloud on June 12 under Apache 2.0, is deliberately unglamorous. It is a directory of markdown files with YAML frontmatter. The spec requires exactly one field, type, in that frontmatter. Everything else, title, description, tags, links to other concepts, is optional.
Two file names are reserved in every bundle. index.md gives an agent a place to start and drill down from, instead of loading every file indiscriminately. log.md is an ISO-dated, newest-first change history, so an agent can tell what changed since it last looked. Concept files link to each other with ordinary markdown links, and that is the whole trick: a directory of files with links between them is already a graph, no database required.
Google shipped three things alongside the spec: a BigQuery agent that generates OKF documentation from warehouse metadata, a static HTML visualizer that needs no backend, and sample bundles built from public datasets like GA4 and Stack Overflow. None of that is complicated. That is the point. The design philosophy is explicit: if you can cat a file, you can read it, and formats that require nothing to use are the ones that tend to last.
Where this comes from: Karpathy's LLM wiki
OKF's own framing credits Karpathy's "LLM wiki" pattern as the thing it is formalizing. Karpathy posted the pattern as a gist, and the shape of it is a three-layer setup:
- Raw sources, the unprocessed evidence, documents, conversations, data files.
- The wiki, markdown pages the LLM writes and maintains, summaries, entity pages, cross-references.
- The schema, a
CLAUDE.md-like document that tells the LLM how to keep the wiki consistent.
Karpathy's own line for this is the one that stuck with me: "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." The agent has three operations against that wiki: ingest new sources into it, query it and cite what it finds, and lint it periodically to catch contradictions, stale claims, and orphan pages. The insight underneath all three is a direct jab at plain RAG: retrieval re-derives an answer from scratch every time you ask, a wiki compiles the answer once and keeps it.
OKF is not a new idea on top of this. It is closer to a naming convention. Karpathy's pattern tells an agent how to behave toward its own wiki. OKF tells many different tools how to agree on what a wiki file looks like, so a wiki built by one agent can be read by a completely different one without a translation step.
So where does "two brains" come in
Here is the synthesis I actually want to defend. An LLM, in this whole picture, is not one memory system, it is two, and they fail in opposite ways if you mix them up.
Brain one is the weights. Whatever the model knows from training is frozen the moment training stops. It is broad, it is fast, and it is completely unable to learn your team's Tuesday deploy convention or that a given customer already churned last quarter. Retraining is the only way to change it, and nobody retrains a frontier model to teach it one fact.
Brain two is the wiki, or in Karpathy's original framing, whatever external file store an agent is pointed at. It is narrow, specific, and mutable on every single session. It has no reasoning of its own, it is just files, but it is the only part of the system that can learn something new on a Tuesday and still know it on Wednesday.
Neither one is a full brain without the other. Weights alone forget every project the moment the session ends, which is the exact problem the Medium article opens with: you start fresh in the morning and the agent has no memory of yesterday. A wiki alone is inert, a folder of markdown files that need something with actual reasoning to read them, decide what is relevant, and write back to them. What OKF adds to this two-brain picture is not a third brain, it is a standard plug so that the second brain, wherever it is stored, is legible to more than one first brain.
That maps onto a layered stack I recognize from my own MCP experiments in an earlier post: CLAUDE.md answers "how should the agent behave," OKF answers "what does the team or the project actually know," and MCP is how the agent reaches out for anything that is live rather than written down. Three different jobs, and it turns out none of them can substitute for either of the others.
What surprised me
The part I did not expect: how boring the actual spec is, on purpose. I went in assuming "the missing piece for AI agents" would be an architecture diagram with a dozen services. It is a type field and two reserved filenames. That is a strange thing to feel reassured by, but it tracks with every format that actually stuck around, JSON, git, markdown itself. They won by asking almost nothing of you.
What I would do differently
I would test the two-brain framing against a case where it should break, an agent with no persistent wiki at all, working purely from weights and a live MCP connection, and see how much of "brain two" that setup actually recovers implicitly through tool state. That is the next thing I want to put notes toward.