An OKF second brain is a personal knowledge base restructured to Google's Open Knowledge Format: a directory of markdown concept files with YAML front matter, fronted by an index.md map that both you and a Claude agent can read, navigate, and update. I converted my own setup, and my conclusion up front: the format's value is not the front matter. It is that the map becomes a file that lives next to the territory — and that one structural change is what finally stops an agent from duplicating knowledge it already has.
I did not arrive at this neutrally. My working memory system before the conversion was the classic shape: markdown notes in nested folders, held together by a heroic root instructions file doing the work of an index, a librarian, and a memory at once. That architecture works beautifully at thirty files and quietly rots at three hundred. The tell, in my case, was watching Claude write a fresh note on a topic it had already documented weeks earlier — two files, same knowledge, drifting apart, both confidently "correct." The agent was not dumb. It had no reliable way to know what existed before writing something new, so it re-derived and duplicated, session after session. Folder discipline is willpower applied to a structural problem, and it does not last.
What OKF Actually Specifies
The Open Knowledge Format shipped from Google Cloud in June 2026, and the spec (public in the GoogleCloudPlatform/knowledge-catalog repo) is deliberately tiny. Every concept is a UTF-8 markdown file with a YAML front matter block. The reserved fields are type, title, description, resource, tags, and timestamp — and only type is required. The file path is the concept's identity. Bundles can optionally include index.md files for progressive disclosure and a log.md for change history. No SDK, no account, no tooling requirement. It is a shape agreement, not a platform.
A concept file in my converted bundle looks like this:
---
type: playbook
title: Client Onboarding Sequence
description: The exact steps I run when a new automation client signs.
tags: [onboarding, process, clients]
timestamp: 2026-06-18
---
# Client Onboarding Sequence
When a new client signs, I run these steps in order...
And the index that fronts its folder:
---
type: index
---
## clients/
- **onboarding-sequence** — steps run when a new client signs
- **escalation-playbook** — handling an unhappy client mid-project
The quiet hero is the description field. One honest line per concept lets an agent read an index of thirty entries and decide which two files it needs — then open only those. I can vouch for this pattern with unusual confidence because my Claude setup already used it before OKF existed: my persistent memory is an index file of one-line topic descriptions pointing at detail files, and it is the single reason memory retrieval stays cheap as the file count grows. OKF did not teach me the pattern; it standardized the pattern I was already living on, which is exactly what a good format should do. I documented the pre-OKF version in my Claude Code second brain build — the conversion described here is that system, given a spec.
The Conversion, in Two Deliberate Passes
Pass one: one folder, by hand. I picked my messiest area and converted it manually — wrote the index.md, then went file by file assigning a type and writing a real one-line description. This was slow on purpose. Deciding whether a note was a playbook, a reference, or a decision forced me to understand what each note actually was, and the exercise surfaced the thing I had been blind to: a meaningful share of my "distinct" notes were the same concept written twice from different angles. The conversion is a deduplication audit wearing a formatting costume, and that alone justified the afternoon.
The most transferable lesson from pass one: write your type vocabulary down as its own concept file before converting anything else. OKF deliberately refuses to dictate your types, and that freedom becomes decision fatigue by the fifteenth file. I fixed a short list — playbook, runbook, reference, decision, case-study, glossary, index — and refused to invent new ones mid-conversion. Consistent types are the difference between a bundle an agent navigates and one it stumbles through.
Pass two: Claude Code for the bulk, with a review gate. Hand-converting hundreds of files was never the plan. For the remainder I gave Claude Code the verbatim spec and had it add front matter and index entries folder by folder, checking its output against the spec's requirements. The honest split of labor: automation nails the mechanical 80 percent — front matter, index lines, flagging files with missing descriptions — and fumbles the valuable 20 percent, which is decomposition. A 2,000-word note that secretly contains three concepts needs to become three files, and an LLM told to "split this into concepts" naively produces overlapping, contradicting fragments. I reviewed every split by hand. Budget for that; it is where the real knowledge work lives.
The Four Rules That Make the Format Do Anything
Here is the part that most OKF write-ups miss entirely: the format is inert. A perfectly structured bundle changes nothing if the agent does not consult it before acting. The unlock was a short protocol at the top of my CLAUDE.md:
## Knowledge Base Protocol
This is an OKF bundle. Before answering or creating any file:
1. Read `index.md` at the relevant level FIRST.
2. Use `description` fields to decide what to open — do NOT
open files to check relevance.
3. Before creating a concept, check the index for an existing
one. Update it instead of duplicating.
4. After any change, update the index line and append to `log.md`.
Rule 3 is the one that kills the duplicate-file disease at the root: creation now requires a lookup. Rule 4 is the one that keeps the system alive: an index only humans maintain rots within weeks, because humans forget; making index maintenance part of the agent's write path means the map and the territory update in the same transaction. That is the deepest difference from my old setup, where all structure lived as prose in one instructions file that drifted out of sync with reality — the agent navigated on a stale map and I blamed the agent.
One more separation worth enforcing, borrowed from the best knowledge-base builders: keep raw source material (transcripts, scraped pages, dumps) in a /raw directory the agent reads but never serves, and let only synthesized concept files into the wiki proper. Mixing raw and synthesized is how a knowledge base becomes a junk drawer with metadata.
What Broke, Honestly
Three failures from my own conversion log. First, lazy descriptions poisoned navigation — my early entries said things like "notes on pricing," which gave the agent nothing to route on, and it fell back to opening files anyway. The navigation is exactly as good as your worst description; I rewrote about a third of them. Second, over-fragmentation — drunk on the concept-per-file idea, I split some topics too finely and the agent had to open five files to answer one question. Concepts should be answer-sized, not sentence-sized; I merged several back. Third, the log needs pruning discipline — an append-only log.md grows without bound, and past a point the agent wastes context reading history it does not need. Mine gets summarized and truncated periodically, the same hygiene I apply everywhere else in my Claude Code memory stack.
Is the Conversion Worth It?
If your knowledge base is under fifty files, no — a single well-written instructions file plus disciplined naming does the job, and the Obsidian-plus-Claude-Code approach covers that scale gracefully. The conversion pays at the scale where retrieval and duplication start taxing you: when the agent's answers begin depending on which copy of the truth it happened to find. Past that line, the standardized map is worth an honest weekend, and the portability is a real secondary win — an OKF bundle means your knowledge is a language another agent can read, not a private dialect only your setup understands.
The principle underneath is bigger than this format: agents do their best work when your knowledge and your workflows live in plain files with explicit structure. OKF applies that to what you know; the same idea applied to what you do is a skill file. The agent skills marketplace I maintain is that second half — workflows encoded as files the agent reads before acting — and running both halves together is what a second brain actually promised in the first place.
