Can Open Knowledge Format Make Claude Code More Accurate and Cheaper? I Tested It

Newsletter What I learned moving the notes Claude Code reads for my homelab into Open Knowledge Format, and what I’d copy even without OKF.
On this page
I’d been hearing about Google’s Open Knowledge Format (OKF) and wanted to know whether it could do anything for my Claude Code second brain. That’s the pile of CLAUDE.md files, rules and auto-memory1 that teaches Claude how my homelab works.
So I tested three versions of it on 44 questions. Adding OKF’s metadata on its own didn’t move the numbers. Adopting OKF’s structure, one concept per file behind an index, cut the notes Claude loads every session about in half and the cost per question by about 30%2, and accuracy held. I switched my real setup over the same day.
OKF is an open spec from Google Cloud. It’s a folder of markdown files, one concept per file, each with a little YAML frontmatter where only type is required, and an index.md in each folder listing what’s there. The agent reads the index, then opens only the concept it needs.
My notes grew the way I think everyone’s do: Claude gets something wrong, so I add a line to make sure it doesn’t happen again. A year of that across my homelab left me with about 200 files, and my Home Assistant doc alone had hit 65 KB. Every session started with about 16,000 tokens of my notes before I typed a word.
I assumed the problem was duplication, but hardly anything was repeated. It was all always-on, so Proxmox and Home Assistant details rode along in sessions where I was fixing a typo on my blog.

For the test, I had subagents split the big docs into small concept files with an index per folder, and every CLAUDE.md shrank to a stub: the few rules that must apply every session, plus a pointer to the right index.
- 3Claude Code’s memory writer and OKF both want a3
Claude records the kind as a `type` field in the memory file’s frontmatter.
Claude Code's docs on memorytypekey. Minutes after I added OKF frontmatter to my memories, another Claude session saved a memory and rewrote my frontmatter, moving mytypeinto the slot Claude Code uses for its own memory categories. The fix was making the OKFtypethe same value as Claude’s category, so a rewrite changes nothing.3Claude records the kind as a `type` field in the memory file’s frontmatter.
Claude Code's docs on memory - Splitting surfaced a stale fact. Two docs disagreed about where one of my services lived, and I never noticed until they were small files side by side.

Most of what I learned doesn’t depend on OKF or on Claude Code. If you keep any kind of notes for a coding agent:
- Treat always-on context as a budget. Every line loads on every turn of every session, whether the task needs it or not.
- Point, don’t preload. Give the agent an index and let it open what it needs. Preload only what’s small, used constantly, or a safety rule.
- One idea per file, named for what’s in it. File names and index lines are how the agent decides what to open, so
critical-alerts-to-phone.mdbeatsnotes-3.md. - Write the index descriptions yourself. The ones my script generated were the weakest part of my conversion.
- 4If a rule must never break, make it a hook. The agent can argue its way past text4.
First impressions of Claude Code modsTest that the hook really blocks. Five of mine never worked, so my must-never-break rules live in Claude Code mods now. - Facts go stale. Put a date on the ones that will5 (OKF has a
stale_afterfield for this), so something reminds you to check them.
[T]arget under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.Claude Code's docs on memory
Short, and only what Claude needs on nearly every task. Anthropic’s own guidance is to keep each CLAUDE.md under 200 lines6.
[T]arget under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.Claude Code's docs on memory
What goes in mine:
- How I want work done: testing, code style, git workflow. These apply to almost everything I ask for.
- Rules, not essays. One or two sentences per rule. If the reason changes how Claude should act, I keep it; otherwise it goes.
- A pointer to everything else. Situational stuff lives in a knowledge folder, and the last line tells Claude where the index is.
What stays out: anything about one project or one service, long examples, anything Claude can figure out by reading the code, and anything a hook can enforce instead.
You can get most of this in an afternoon. The full post has a prompt you can paste into Claude Code from the root of your repo, plus how I tested it. When it finishes, Claude lists what it kept always-on and why. Read that list before you commit. That’s where my conversion went too far: tables I look up constantly ended up behind pointers, and I had to put them back.
My Development Setup in 2026What’s in that global file: its testing and git rules, and how chezmoi copies it to every machine.Once your docs are already lean, this buys you little. I split my global ~/.claude/CLAUDE.md the same way afterward and saved 312 tokens7, because nearly all of it is rules that apply everywhere.
Works on My Machine
Get the next issue by email. It covers homelab builds, AI tools and open source, and it goes out when I have something to say.
It’s free, and you can unsubscribe anytime. You’ll get an email to confirm first.
If you liked this issue, consider sharing it on Hacker News, Bluesky, LinkedIn, or X.

Joe
Karlsson
I write about my homelab, AI tools, databases, and the weird stuff I build on the side.
More about me →