In this video I break down Google Cloud's Open Knowledge Format (OKF), a way to give your coding agents memory that's just a folder of markdown files. I go through how a bundle works step by step, what changed in version 0.2, where the idea came from, and how I use it for project memory in Beckon. If you run Claude Code, Codex or Cursor on long projects and you're tired of your agent forgetting yesterday's decision, this one's for you.
What I cover in this video
- 0:00 Why your agent re-reads the repo every session and still forgets what you decided
- 0:46 The real problem: knowledge scattered across wikis, catalogs, code comments and people's heads
- 2:17 How OKF works, step by step: bundles, paths, frontmatter, body and links
- 3:48 The graph viewer, plus index.md and progressive disclosure
- 5:18 log.md and what version 0.2 adds for trust and freshness
- 6:50 Where it came from: Andrej Karpathy's LLM Wiki
- 8:22 Who OKF is for, and how I use it in Beckon
- 9:55 Is it worth using?
The problem: every team reinvents context
Google frames it like this: the knowledge your agents need is scattered everywhere, and every tool stores it differently. In their words, every agent builder is solving the same context assembly problem from scratch. There's no agreed answer for what fields a document should carry or what file names mean, so every team makes up their own, and an agent from a different tool can't make sense of either.
It's not only a team problem. I bounce between Claude Code and Codex, and each keeps its own notes its own way, so context I built up in one doesn't carry over to the other. And you've seen what happens at the start of a new session: the agent says it'll explore the codebase and reads file after file. You pay for that in tokens, and half the time it still misses the one thing that mattered. The bigger the project, the worse it gets.
Google's answer is a shared format that any agent can read, any agent can write to, and you can open in a plain text editor. No new database, no SDK.
How an OKF bundle works
It's simple. Here are the five pieces:
- The bundle is a folder. Every concept gets its own markdown file. One concept, one file. A concept can be a database table, an API, a metric, a playbook for when something breaks, pretty much anything your team knows.
- The path is the identity. The file's path inside the folder, minus the
.md, is the concept's ID. So tables/orders is the orders table. No ID registry, no database.
- Frontmatter on top. Every file starts with a YAML block, and only one field is required:
type. A file that just says type: playbook is fully valid. Recommended fields are title, description, resource (a link to the real thing it describes) and tags. You can add any extra fields, and readers aren't allowed to reject them.
- The body is normal markdown. Headings, tables, code blocks. The spec suggests headings like schema and examples, but nothing in the body is required.
- Links make it a graph. Concepts point to each other with plain markdown links. The orders table links to the customers table, a metric links to the table it comes from. Now your folder isn't only a tree, it's a graph.
In the video I show Google's own viewer running on their Stack Overflow sample. Every dot is a file, every line is a link, and clicking one shows its frontmatter, body and everything that links back to it.
index.md and log.md
Two special file names are where the savings come from. index.md can sit in any folder and is just a list: each line links to a file with a one-line description. Google calls this progressive disclosure, letting a human or agent see what's there before opening anything.
So instead of loading too much into context or digging through file after file, your agent reads the top index, opens the one folder that matters, reads that folder's index, then opens the two or three files it actually needs. Everything else stays closed. To be clear, Google doesn't publish a token number, benchmark or percentage for this, so I'm not going to make one up. The mechanism is the point: fewer files read means fewer tokens spent, and because the right note is easy to find, it's more likely to get pulled in.
log.md is the history, newest first, grouped by date: created this, updated that, deprecated this. When your agent comes back tomorrow, it doesn't have to guess what changed.
What version 0.2 adds: trust, freshness and attestation
If you only read Google's June introduction, you're looking at version 0.1. In July Google released version 0.2, and in August the spec moved into its own repo. Version 0.2 goes after one question: when agents write most of your notes, how do you know what to trust? The answers live in the frontmatter:
- sources: a list so a claim can point back to where it came from.
- generated: who wrote it and when.
- verified: who checked it. That gives three trust tiers: unverified (nobody checked), machine-confirmed (only a machine checked) and human-reviewed (a human signed off).
- status: draft, stable or deprecated.
- stale_after: a date when the note goes stale, so your agent knows to double check a fact past its date.
Then there are attested computations. A team locks in the approved way to calculate a number like revenue. The agent can only fill in the blanks, like which year, and isn't allowed to write its own query. A plain piece of code, no AI, checks that the approved query is what actually ran. If you've ever had an agent confidently hand you a made-up number, you'll see why that matters. Version 0.2 also renames two v0.1 fields, so check the spec if you started on 0.1.
Where it came from, and who it's for
In April, Andrej Karpathy posted a gist called LLM Wiki. Instead of the AI digging through raw documents every time, it builds and maintains its own markdown wiki with an index it reads first and a log of everything that happened. Google quotes his line on why it works: LLMs don't get bored, don't forget to update a cross reference, and can touch 15 files in one pass. Google turned that pattern into a spec.
They also shipped tools as a proof of concept: an enrichment agent that walks a BigQuery dataset and writes one file per table, a viewer that turns any bundle into an interactive graph in one HTML file, and sample bundles (e-commerce, Stack Overflow, Bitcoin and a retail example). The catch: the reference agent needs your own Google Cloud and Gemini setup. The format itself needs nothing but files.
I'd say it's for three groups: anyone running coding agents on long projects where decisions pile up, teams that switch between tools like Claude Code, Codex and Cursor, and anyone who wants agent memory in git where they can read it, diff it and roll it back. Google's own design rule: format, not platform.
How I use it in Beckon
In Beckon, project memory is built on OKF notes: frontmatter on top, markdown underneath, links, backlinks and a graph view. Every agent in the project is told to read those notes (goals, decisions, rules) before it starts, and to leave a handoff note when it finishes so the next agent, even a different one, can pick up where the last left off. You can put the memory hub right on the canvas as its own pane. My favorite part: Beckon can turn a folder into catalog notes, one per folder plus an index, each saying where it lives, what's in it and example questions it can answer. My agents read the map instead of re-walking the tree.
Key takeaways
- An OKF bundle is a folder of markdown files, one concept per file, with the path as the ID and only
type required.
index.md lets your agent read the map first and open only the files it needs. Google publishes no token numbers, just the mechanism.
log.md tells a returning agent what changed, newest first.
- Version 0.2 adds sources, trust tiers, status, stale dates and attested computations checked by plain code.
- It's version 0.2, so expect changes, but worst case you end up with well organized markdown that you and your agents can both read.
Full video transcript
0:00Your coding agent reads through your whole repo every single session and it still forgets the decision you made yesterday. You told it we're not using that library. Next morning it's right back in there. Come on now. So Google Cloud put out something that goes right at this problem. It's called the open knowledge format, OKF for short. And here's the wild part. There's no new database, no SDK. It's a folder of markdown files. That's basically it. So, in this video, I'm breaking down how it actually works step by step, why it means your agent doesn't have to read everything just to find one thing, who it's actually for, and how I'm using it inside Becken. Let's jump right into it. So, what's the actual problem? Here's
0:46how Google frames it. The knowledge your agents need is scattered all over the place. It's in wikis. It's in data cataloges. It's in code comments. And a lot of it is just in people's heads. and every tool stores it differently. In their words, every agent builder is solving the same context assembly problem from scratch. And they point out there's no agreed upon answer to what fields every document should carry or what file names mean what. So every team just makes up their own. My notes look one way, your notes look another way, and an agent from a different tool can't make sense of either one. And it's not only a team problem. Even solo, if you bounce between claude code and codecs like I do, each one keeps its own notes in its own way. So the context you built
1:32up in one tool just doesn't carry over to the next one. And you've felt this. You open a new session and the agent goes, "Let me explore the codebase and it reads file after file after file. You're paying for all of that in tokens." And half the time it still misses the one thing that mattered. And the bigger your project gets, the worse it gets. more files to walk, more tokens burned, and more stuff for the agent to lose track of. So, Google's answer is a shared format, something any agent can read, any agent can write to, and you can open in a plain text editor. Still juggling cloud code, codecs, and cursor in five terminal windows. Beckin puts every coding agent on one canvas side by side. Press a key and just talk to them.
2:17Every idea gets its own workspace with memory that carries over. Becken, hey, Beckin.ai. So, here's how it actually works. And don't get lost in the sauce here. It's super simple. Step one, the bundle. A bundle is just a folder. And inside it, every concept gets its own markdown file. One concept, one file. A concept can be a database table, an API, a metric, a playbook for when something breaks. Pretty much anything your team knows. Step two, the path is the identity. The files path inside the folder minus the MD is that concepts ID. So tables/orders is the orders table. No ID registry, no database. The folder is the whole system. Step three, every file starts
3:03with a little block of YAML up top called front matter. And here's the part I love. Only one field is required. Type. That's it. A file that just says type playbook is fully valid. Then there's a few recommended ones. title, description, resource, which is a link to the real thing it describes, and tags. And you can add any extra fields you want, and readers aren't allowed to reject them. Step four, the body. Under the front matter, it's just normal markdown, headings, tables, code blocks. They suggest a few headings like schema, and examples, but nothing in the body is required. And then step five, the links. Concepts point to each other with plain markdown links. The orders table links to the customers table. A metric links to the table it comes from. And just
3:48like that, your folder isn't only a tree anymore. It's a graph. You can see that right here. This is Google's own viewer running on their Stack Overflow sample. Every dot is a file. Every line is a link. And when you click one, you see the front matter, the body, and everything that links back to it. Pretty cool. Now, there's two special file names, and this is where the token savings come from. The first one is index.nd. It can sit in any folder and it's just a list. Each line is a link to a file plus a oneline description. Google calls this progressive disclosure, letting a human or an agent see what's there before opening anything. So, think about how your agent works today. To answer one question, it either loads way too much
4:33into context or it goes digging through file after file. With an index, it reads the top index first. Then it opens the one folder that matters, reads that folder's index, and then it opens the two or three files it actually needs. Everything else stays closed. Here's something to pay attention to. Google doesn't publish a token number for this. No benchmark, no percentage, so I'm not going to make one up. But the mechanism is simple. Your agent reads the map first, then only the pages it needs instead of the whole book. Fewer files read means fewer tokens spent. And because the right note is easy to find, it's way more likely to actually get pulled in. That's your recall. The second special file is log.md. It's a
5:18history. Newest first grouped by date. Created this, updated that, deprecated this. So when your agent comes back tomorrow, it doesn't have to guess what changed. It just reads the log. Now, here's something most people don't think about. If you only read Google's post from June, that's version 0.1. But in July, Google put out version 0.2. And in August, the spec moved into its own repo. And 0.2 goes after one problem. When agents are writing most of your notes, how do you know what to trust? So the spec asks five questions. Where did this come from? How much should I trust it? Is it still true? Is it the current version? And was this number produced the way we said it must be? And the answers live right in the front matter.
6:04There's a sources list, so a claim can point back to where it came from. There's a generated field, who wrote it and when. And there's a verified field, who checked it. And from that, you get three trust tiers. Nobody checked it, it's unverified. Only a machine checked it, it's machine confirmed. A human signed off, it's human reviewed. Then there's status, draft, stable, or deprecated. and stale after a date when the note goes stale. So your agent can see, okay, this fact is past its date. I should double check it. And there's one more piece that's pretty interesting. It's called an attested computation. Basically, a team can lock in the approved way to calculate a number like revenue. The agent can only fill in the blanks like which year. It's not allowed
6:50to write its own query. And then a plain piece of code, no AI, checks that the approved query is what actually ran, which is huge if you've ever had an agent confidently give you a number it just made up. So where did this come from? Back in April, Andre Karpathy posted a gist called LLM wiki. The idea is instead of your AI digging through raw documents every time you ask something, it builds and keeps up its own wiki in Markdown. It has an index file it reads first and a log file of everything that happened. And Google quotes his line on why this works. LLMs don't get bored. Don't forget to update a cross reference and can touch 15 files in one pass. So Google took that pattern and turned it into a spec. In June,
7:37version 0.1, in July 0.2, and in August it got its own repo. And they shipped a few tools with it. An enrichment agent that walks a Big Query data set, writes one file per table, and then a second pass fills in docs, schemas, and how the tables join. A viewer that turns any bundle into an interactive graph in one HTML file. And sample bundles, J4, e-commerce, Stack Overflow, Bitcoin, and now a retail example, too. Google calls the tools a proof of concept. The format is the real contribution. Here's the catch, though. That reference agent is built around BigQuery. So, you need your own Google Cloud and Gemini setup to run it. But you don't need any of that to use the format itself. It's just files.
8:22So, who is this actually for? I'd say three groups. One, anyone running coding agents on long projects where decisions pile up over weeks. Two, teams that switch between tools. Your notes from Cloud Code should still make sense to codeex or cursor or whatever you open next. And because it's just markdown, they can. And three, anyone who wants their agents memory in git where you can read it, diff it, and roll it back. No proprietary account, no SDK. That's one of Google's own design rules. Format, not platform. And this is the part I care about. In Becken, project memory is built on OKF notes. Front matter on top, markdown underneath, links between notes, back links, and a graph view.
9:09Every agent in the project is told to read those notes before it starts. The goals, the decisions, the rules, and when it finishes, it's told to leave a handoff note so the next agent, even a totally different one, can pick up right where the last one left off. And you can put the memory hub right on the canvas as its own pain. And then my favorite part, Beckin can turn a folder into catalog notes. One note per folder, plus an index. Each one says where it lives, what's in it, and example questions it can answer. So instead of re-walking the whole tree every session, my agents read the map. Same idea as progressive disclosure. And like I said at the start, the agent forgetting yesterday's decision. That's exactly the problem this goes after. So is it worth using? I
9:55think so. It's version 0.2, so expect it to change, but it's just files. Worst case, you end up with really well organized markdown that you and your agents can both read. So, let me ask you this. What does your agent forget every single session? Tell me down below. And if this made OKF make sense, give the video a thumbs up. It really helps the video spread. Have a blessed day.