Blog
Writing about the Open Knowledge Format and okf-gem: project knowledge as plain files in git, curated by agents, checked by tooling, 100% local.
馃嚙馃嚪 Posts em portugu锚sYour bundles, served to any agent: okf-mcp 1.0.0
Until now your bundles needed a shell: the CLI, the skill, the graph. okf-mcp 1.0.0 serves them to any MCP-capable host, Claude Desktop included, with answers sized to the question instead of the archive.
Should your team adopt OKF?
You are not evaluating a tool, you are deciding whether a practice becomes standard for people who did not choose it. Here is the honest version: what OKF costs, what it survives, and the one thing it does not do, in the terms an engineering lead actually asks about.
Bundles you can group, a graph you can read: okf 1.12.0
A registry that only lived in your home directory could not be shared, and a dense graph greeted every reader with a thicket. okf 1.12.0 commits the registry alongside your code and opens the graph on its spine, plus a new read that tells you whether a directory is a concern or a container.
Your agent is reading four times more than it needs to
A test in okf's suite fails the build if answering a question ever costs more than a quarter of handing the whole project over. Not a benchmark run once for this post, a line in CI green since version 1.5.0. Here is what it measures, what it comes to in tokens on a real project, and the one thing a leaner context does not buy you.
Find your way around a big bundle: okf 1.11.0
Every read verb in okf could tell you about concepts. None of them could tell you about the tree those concepts live in. okf 1.11.0 makes the directory a thing you can ask about, cut, and filter by, and stops a served bundle rebuilding its search index on every request.
Search every bundle at once: okf 1.10.0
Your knowledge is spread over a handbook, a service, a repo you were in an hour ago. okf 1.10.0 lets one search reach all of them from the page you are already reading, ranked against the whole corpus instead of four lists glued end to end.
Search you can swap: okf 1.9.0
okf 1.9.0 lets you pick the search engine. The new one is 44 to 56 times faster per query and ships off by default, because a process that exits pays the index build for exactly one question.
A 50x speedup you cannot spend
The benchmark said 50x. The default did not move. A CLI invocation builds an index, asks one question, and exits, so the throughput it bought is throughput it never lives to spend. What would change that is not a faster index, it is a process that stays alive.
The map was always in the bundle. Now the graph draws it.
A bundle's index is the one file its author wrote to be read first. On the graph page it was reachable only by finding a tab and clicking a row. okf 1.9.0 turns the authored map into a layer you can draw over any layout, and shows who wrote it in the shape of the node.
Your bundles get names: okf 1.8.0
A path says where a bundle is. A name says what it is. okf 1.8.0 adds a registry: name a bundle once and every verb, the server, and search reach it from anywhere, and the graph page now travels from a phone to a desktop with a command palette in every mode.
Your docs are already the bundle: /okf migrate
Adopting a knowledge format usually means rewriting what you already wrote, which is why adoption stalls. /okf migrate adopts your Markdown in place, every body verbatim, and the links you already wrote become the graph on day 0.
Host the graph anywhere: okf render
okf server draws your bundle as a live graph, but a server is a process that needs somewhere to run. okf render writes that same page as one static HTML file with the bundle baked in, so the graph hosts on GitHub Pages or anywhere static files go. New in 1.6.0, one switch away from the server.
Run okf anywhere: the Docker image
okf is pure Ruby, but the Ruby on the box is not always yours to choose. The official Docker image carries the whole CLI, so validate, lint, search, and the live graph run with nothing to install. Multi-arch, built from source, on ghcr.io.
What is the Open Knowledge Format?
OKF is an open, vendor-neutral format for keeping project knowledge as Markdown + YAML, versioned with the code and readable by people and agents from the same file. How a bundle works, and how to start one.
Why I built okf-gem
Standards are what make scale possible. How my agent workflow evolved from spec frameworks to a well-documented harness, and why that led to a complete OKF toolkit: skill, CLI, Ruby objects, and a mountable graph. 100% local.