Converting 270 Knowledge Documents to Google's Open Knowledge Format (OKF)

A real-world OKF conversion log: 199 concept documents, 5 bundles, 100% spec-compliant.

It Started With a Feeling of Déjà Vu

Mid-June, Google Cloud published OKF v0.1 — the Open Knowledge Format. I skimmed it, noted it, and moved on. Another standard from a big tech company.

But a few days later, scrolling through community discussions, I kept seeing something familiar.

OKF's core definition: a directory of markdown files with YAML frontmatter, each tagged with a type field.

That's essentially what my compound-system knowledge base already looked like.

My solutions/ directory had bug records, knowledge entries, and extracted patterns — all markdown with YAML frontmatter. The only difference was that I called it problem_type instead of type.

This kind of coincidence makes you want to try.

Plus, I'd had a long-standing frustration: compound-system had been running for almost a year and accumulated ~170 files, but nobody except me knew what was in there. No directory index, no unified metadata. Asking another agent to read it was like handing someone a box of unlabeled floppy disks.

OKF claims to solve exactly that: make your knowledge traversable by agents instead of forcing them to guess from filenames.

Alright. Let's try.

What OKF Actually Is

OKF defines a Knowledge Bundle: a directory tree of .md files.

Each file represents a Concept:

---
type: Bug
title: Session splitting caused by compression bug
tags: [hermes-agent, compression]
timestamp: 2026-06-21T00:00:00Z
---
Standard markdown body.

The only required field is type. Everything else — title, description, tags, timestamp, resource — is recommended.

The rules are minimal:

• Every concept file must have a non-empty type
• Reserved filenames: index.md (for directory listings) and log.md (for changelogs)
• Bundles can carry any extra fields — consumers must not reject unknown keys

Optional index.md files at each directory level provide progressive disclosure for humans and agents navigating the bundle.

bundle/
├── index.md          ← okf_version: 0.1
├── bugs/
│   ├── index.md      ← directory listing
│   ├── fix.md        ← type: Bug
│   └── crash.md      ← type: Bug
└── patterns/
    ├── index.md
    └── tdd-workflow.md

If this looks like an Obsidian vault or any LLM wiki repository, that's because it's exactly what the format was designed to formalize.

The Google team's contribution isn't inventing a new format — it's writing down the pattern that was already emerging and giving it interoperability guarantees.

That approach, frankly, is itself an OKF-style move: making implicit knowledge explicit.

My Document Landscape

Before writing a single line of code, I did a full inventory:

About 55 files were already close to OKF — frontmatter present, metadata structured, just needing a type field.

Another 215 were pure markdown with nothing.

And then there was a special group: compound-system's 73 auto-mined records. Their frontmatter was built from raw JSON dumps — unescaped quotes, embedded newlines, the works. YAML parsers bailed immediately.

Those I didn't convert.

Conversion Highlights

1. Type Was the Missing Layer

A typical compound-system frontmatter:

---
title: "CodexPlusPlus #1303 UA cache fix"
module: hermes-agent
tags: [task, auto-reflection]
problem_type: knowledge
severity: low
created: 2026-07-02
---

Converting to OKF meant exactly one thing: add type: SessionKnowledge, keep problem_type as-is (OKF allows extra fields), and normalize created into timestamp.

The logic for this was the heaviest part of the converter. Everything else was plumbing.

2. Half-Baked Knowledge Isn't Worth Archiving

Compound-system had auto-mined entries where pipeline output was jammed into the title field as raw JSON fragments:

title: '{"content": "1|[package]\n2|name = "codex-plus-core"\n3|version.workspace = tr"'

This isn't a YAML quoting problem — the content itself is broken. Unescaped quotes inside a quoted string, literal newlines, raw CLI stdout masquerading as a title.

I spent two rounds trying to handle these edge cases in the converter: custom YAML representers, fallback serializers, manual encoding. After the second round, I stopped.

These aren't knowledge documents. They're pipeline byproducts.

OKF's design philosophy carries an implicit assumption: knowledge should be curated, not dumped. My filter was simple — if a source file's YAML frontmatter can't be parsed, skip it. 73 records gone. Didn't lose a single piece of actual knowledge.

3. Pure Markdown Was Actually the Easiest

Files with no frontmatter at all — AGENTS.md, HANDOVER.md, ~/docs/reports/* — had the simplest treatment: extract title from the first # heading, infer type from filename, generate frontmatter automatically.

---
type: AgentInstruction
title: Agent Workspace — lennney
timestamp: 2026-07-05T16:23:18+00:00
---

The inference isn't perfect. The description for my root AGENTS.md came out as the first paragraph — a table header from the "Project Map" section. It's not elegant, but it's enough for an agent scanning the directory index to know what it's looking at.

That's the progressive disclosure principle in action: give enough context to decide whether to drill down.

The Results

After processing ~270 source files, the output was 5 bundles:

Those 100 index.md files are the output I care about most. Every directory now has a navigable index. An agent can start at the bundle root and drill down through progressively detailed listings to find exactly what it needs.

Before: agents guessed from filenames.
After: agents browse a table of contents.

The difference is like guessing a book's content from its title vs. flipping through its table of contents.

What Surprised Me

Writing the converter was faster than handling data quality issues

The entire okf-convert.py is ~650 lines. The first working version took about 40 minutes. The remaining time went into:

• Handling malformed YAML frontmatter
• Tweaking index.md formatting
• Fixing bundle root metadata being overwritten by auto-generated indices
• Verifying all 270 files could round-trip through a YAML parser

Format conversion is never a technical problem. It's a data quality problem.

Byproducts are the hardest to handle

I mentioned this earlier, but it's worth repeating: I didn't expect compound-system's auto-mined records to account for 73 out of 170 files — over 40%. That means the pipeline was producing more noise than signal.

This ratio is itself interesting. If your knowledge pipeline generates mostly garbage, the problem isn't the output format — it's the pipeline.

index.md generation was unexpectedly valuable

I originally added index.md generation as a "might as well" feature. First time I cat bugs/index.md, I noticed several entries showing Untitled as their title — because the source file literally had no title field.

These silent issues were invisible in the raw file listing. index.md surfaced them immediately.

What OKF Enables Right Now

The ecosystem is early, but here's what works today:

1. Git-clone knowledge distribution — a bundle is just a directory. Push, tar, rsync. No server, no database, no API
2. Agent traversal — navigate via index.md, drill down to specifics. Google's reference agent demonstrates this pattern
3. Visualization — Google ships a viz.html generator that renders any bundle as an interactive graph in a single HTML file
4. Framework-agnostic consumption — OKF doesn't lock you into a specific agent framework. Google ADK, LangChain, or my own Hermes skill system can all read the same bundle

For my use case, the viz.html output is the killer feature. A picture really is worth a thousand filenames — especially for non-technical teammates.

Next Steps

OKF is still v0.1 draft. Open questions:

• How to search across 200+ files efficiently? Traversing index.md trees doesn't scale
• How to cross-reference between bundles? Currently limited to intra-bundle links
• How to prevent knowledge staleness? OKF has timestamp fields but no expiry strategy

These are tooling problems, not format problems. The format just provides the hooks.

Still: for a format in its v0.1 phase to cleanly organize 270 documents across 5 bundles with zero compliance failures — that's genuinely impressive.

Code: okf-convert.py on GitHub

The bundle conversion script is open-source. I also saved it as a Hermes skill for future use.

Lennney writes about AI agent architecture, engineering infrastructure, and the systems that make agents smarter. If this resonated, star the repo or share it with someone building agent knowledge systems.