My OKF is for the bots

The files are simple. The layout is simple. But how you use them can get complicated.

That’s where I’m at with OKF. I’ve changed how I think about it a few times. While putting this post together, I found another gap in how I’m using it.

Writing is how I learn

When I started with OpenCode, I didn’t have anything like this. I used profiles, including one based on the Getting Real ideas from 37signals. If I wanted to keep something, I’d have it write a post, edit a post, or put together some notes.

I tried getting OpenClaw working five different times. It broke every time, so I gave up. Eventually, I moved to Hermes.

I’ve used different memory systems with Hermes. That’s another post. What I want from OKF is knowledge that lasts beyond whichever agent application I happen to be using. Hermes, OpenClaw, OpenCode, Claude Code, Codex. I want that knowledge to come with me.

Before I had an OKF, I had Holly build a blog with Eleventy.

I write. It’s one of the ways I learn. So I thought, if the bot takes notes about what it did every day, I can look back at those things and maybe figure out how to improve them.

And that was useful for a time.

Then OKF was announced, and I set one up. For a while, the blog and OKF lived side by side. Eventually, I brought the older AI blog material into the OKF.

What I mean by a bundle

OKF stands for Open Knowledge Format. A bundle is a collection of Markdown files with front matter describing the knowledge in them. There’s an index so an agent can find its way around.

What interested me was organizing the knowledge into smaller bundles. A bot could get into the subject it needed without loading everything else.

Say I had an OKF about ServiceNow. I might have some general information about what it is and a little history. Then I might have a more specific bundle about Service Catalog: catalog items, older workflows, Flow Designer, and the oddities you run into along the way.

Another bundle could cover the people around ServiceNow and how the community has recognized them over the years. Same broad subject, different knowledge.

I don’t think I’d actually sit down and write all of that into an OKF, to be fair. It’s an example. If the job is about Service Catalog, the bot shouldn’t have to load the whole community history to get started.

My actual repository already has independent bundles for things like JSN, Node.js development, Rails, and my GitHub workflow.

I don’t need a website for this

When you have all this knowledge collected, it’s tempting to make a website out of it. Or a graph. Something you can look at and click around in.

I did that too. I wanted the agents to navigate it, and I wanted to read it myself.

Now I’m of the opinion that the OKF is for the bots. Maintained by the bots, for the bots to use.

I don’t recommend building a website or a graph to visualize it. It’s interesting to look at, sure. So is the knowledge graph in Obsidian. But for what I’m trying to do, it’s a waste of time. I want the bots to use the knowledge to get work done.

If I need a report or a post from it, the bot can make that separately.

We retired the OKF website and its publication pipeline. The knowledge is plain Markdown in Git. Bots are meant to read local copies, starting with the signpost, then the bundle catalog, then the relevant bundle’s index and pages.

Those copies are read-only. Bots can propose corrections with evidence, and Holly reviews them. The pages record ownership, sources, verification dates, and status. Something we inherited and haven’t reviewed shouldn’t look like a fact we just checked.

The files existed. The bot was behind.

I originally had Holly updating OKF nightly from our chats. I also told it that more wasn’t better. I didn’t want every conversation copied into another place.

Now I think meaningful updates should happen closer to the chat where we figure something out. Otherwise, the next conversation can start before that knowledge is available.

But there’s another part to this: even if the repository gets updated, does the bot get the update?

While working on this post, I asked Holly to check. Her own working copy was stale. She refreshed it, but her reading instructions still pointed at the website we’d retired.

So I had the knowledge. I had the bundles. I had a reading and review process written down. And the bot still wasn’t consistently getting the current version.

Updates have landed through commits and pull requests. What we haven’t established is reliable onboarding and refresh across the bots. I can’t tell you that a nightly job is working today or that every new bot automatically gets what it needs.

That’s the next piece to get working: a new bot should know where the knowledge is, how to read the relevant parts, and whether its copy is current. An existing bot needs to receive the changes too.

Try this with your own bot

I’m writing this to document what I’ve learned, but also so you can get there faster without needing me to walk you through it.

If I were starting again, I’d skip the website and graph. Start with some useful knowledge, give the bot a real job, and check whether it uses that knowledge. Then change something in the bundle and check whether the bot gets the update.

Here’s a short starting prompt. It’s what I’d suggest now, rather than the exact process I followed:

Help me set up a small OKF bundle from our useful conversations and project docs. Keep sources and uncertainty clear. Make it for bots to use and maintain; don’t build a website or graph. Set up how a new bot finds it and how existing bots get approved updates. Check both with a real task, and tell me what works and what still needs doing.

Don’t stop at checking that the files exist. I already had those.