---
title: "Does Open Knowledge Format Help Claude Code?"
description: "What I learned moving the notes Claude Code reads for my homelab into Open Knowledge Format, and what I’d copy even without OKF."
url: https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/
---

Oct 30, 2026 | 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](https://www.joekarlsson.com/images/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/card-photo.webp)

**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](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#what-okf-is)
2.  [How my notes got fat](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#how-my-notes-got-fat)
3.  [Splitting into concepts](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#splitting-into-concepts)
4.  [What broke when I switched](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#what-broke-when-i-switched)
5.  [What I’d copy](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#what-id-copy)
6.  [How I write a CLAUDE.md now](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#how-i-write-a-claudemd-now)
7.  [Doing it yourself](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#doing-it-yourself)

**[1](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) (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-memory [1](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-1) that teaches Claude how my homelab works.

**[2](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-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](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-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"](https://www.joekarlsson.com/images/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/meme-charlie-conspiracy.webp)

## Splitting into concepts

_Diagram: Before: one 65 KB Home Assistant doc in every session. After: a 2 KB stub and small concept files 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](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-3)** Claude records the kind as a \`type\` field in the memory file’s frontmatter.[Claude Code's docs on memory](https://code.claude.com/docs/en/memory)
    
    **Claude Code’s memory writer and OKF both want a[3](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-3) `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](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-3)** Claude records the kind as a \`type\` field in the memory file’s frontmatter.[Claude Code's docs on memory](https://code.claude.com/docs/en/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"](https://www.joekarlsson.com/images/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/meme-pawn-stars.webp)

## 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.  **[4](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-4)**
    
    [First impressions of Claude Code mods](https://www.joekarlsson.com/blog/claude-code-mods-first-impressions/): Test that the hook really blocks. Five of mine never worked, so my must-never-break rules live in Claude Code mods now.
    
    **If a rule must never break, make it a hook.** The agent can argue its way past text [4](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-4).
6.  **[5](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-5)** A concept is stale when \`now >= stale\_after\`.[The Open Knowledge Format spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
    
    **Facts go stale.** Put a date on the ones that will [5](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-5) (OKF has a `stale_after` field for this), so something reminds you to check them.
    
    **[5](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-5)** A concept is stale when \`now >= stale\_after\`.[The Open Knowledge Format spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
    

## How I write a CLAUDE.md now

**[6](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-6)** \[T\]arget under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.[Claude Code's docs on memory](https://code.claude.com/docs/en/memory)

Short, and only what Claude needs on nearly every task. Anthropic’s [own guidance](https://code.claude.com/docs/en/memory) is to keep each CLAUDE.md under 200 lines [6](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-6).

**[6](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-6)** \[T\]arget under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.[Claude Code's docs on memory](https://code.claude.com/docs/en/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](https://www.joekarlsson.com/blog/claude-md-open-knowledge-format/) 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.

**[7](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-w-7)**

[My Development Setup in 2026](https://www.joekarlsson.com/blog/my-development-setup-2026/): What’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 tokens [7](https://www.joekarlsson.com/newsletter/can-open-knowledge-format-make-claude-code-more-accurate-and-cheaper-i-tested-it/#mn-7), because nearly all of it is rules that apply everywhere.

[Read the full post](https://www.joekarlsson.com/blog/claude-md-open-knowledge-format/)

## 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.

![Joe Karlsson at his desk, chin on hand, with a microphone in front of him](https://www.joekarlsson.com/images/about/collage/studio.webp)

Joe  
Karlsson

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

[More about me →](https://www.joekarlsson.com/about/)

[Bluesky](https://bsky.app/profile/joekarlsson.com) | [LinkedIn](https://www.linkedin.com/in/joekarlsson/) | [GitHub](https://github.com/JoeKarlsson)
