Skip to content

4 min read

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

two featureless mannequin heads, each with a pink brain on top, the one on the right taller with a larger brain

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
  1. What OKF is
  2. How my notes got fat
  3. Splitting into concepts
  4. What broke when I switched
  5. What I’d copy
  6. How I write a CLAUDE.md now
  7. Doing it yourself
1 rules and auto-memory: Auto memory is notes Claude Code writes itself. MEMORY.md is an index with one line per memory, and each memory is its own file.

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.

2 Tokens loaded at session start: 16,237 before, 8,505 after. Cost per question on Sonnet: $0.043 to $0.030. Accuracy: 97% to 99%, within the noise of 44 questions.

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.

What OKF is

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.

How my notes got fat

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.

Charlie Conspiracy meme: Charlie from It's Always Sunny in Philadelphia pointing at a wall of papers and red string, captioned "Me explaining how the 200 markdown files I wrote for my AI agent connect to each other"

Splitting into concepts

BEFORE AFTER home-assistant/ CLAUDE.md 65 KB loads every session home-assistant/ CLAUDE.md 2 KB: rules + pointer knowledge/home-assistant/ index.md one line per concept critical-alerts-to-phone.md dashboard-conventions.md voice-assistant-setup.md ... 1-2 KB each, opened on demand
BEFORE AFTER home-assistant/ CLAUDE.md 65 KB loads every session home-assistant/ CLAUDE.md 2 KB: rules + pointer knowledge/home-assistant/ index.md one line per concept critical-alerts-to-phone.md dashboard-conventions.md voice-assistant-setup.md ... 1-2 KB each, opened on demand

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.

What broke when I switched

  1. 3 Claude records the kind as a `type` field in the memory file’s frontmatter.Claude Code's docs on memory
    Claude Code’s memory writer and OKF both want a3 type key. Minutes after I added OKF frontmatter to my memories, another Claude session saved a memory and rewrote my frontmatter, moving my type into the slot Claude Code uses for its own memory categories. The fix was making the OKF type the same value as Claude’s category, so a rewrite changes nothing.
    3 Claude records the kind as a `type` field in the memory file’s frontmatter.Claude Code's docs on memory
  2. 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.

Pawn Stars Best I Can Do meme: Rick Harrison and another man behind the pawn shop counter, captioned "Me: read the file I pointed you to" and "Claude: best I can do is answer from vibes"

What I’d copy

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:

  1. Treat always-on context as a budget. Every line loads on every turn of every session, whether the task needs it or not.
  2. 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.
  3. 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.md beats notes-3.md.
  4. Write the index descriptions yourself. The ones my script generated were the weakest part of my conversion.
  5. If a rule must never break, make it a hook. The agent can argue its way past text4.
  6. 5 A concept is stale when `now >= stale_after`.The Open Knowledge Format spec
    Facts go stale. Put a date on the ones that will5 (OKF has a stale_after field for this), so something reminds you to check them.
    5 A concept is stale when `now >= stale_after`.The Open Knowledge Format spec

How I write a CLAUDE.md now

6 [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.

6 [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.

Doing it yourself

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.

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.

Read the full post

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 at his desk, chin on hand, with a microphone in front of him

Joe
Karlsson

I write about my homelab, AI tools, databases, and the weird stuff I build on the side.

More about me →

BlueskyLinkedInGitHub