okf: knowledge graphs without the vendor box

The Open Knowledge Format is a good idea: a portable, spec’d way to represent a knowledge graph — concepts, relationships, backlinks — that an agent can read, validate, and reason over. The promise is right there in the name. Open. A format that any tool, any model, any pipeline can participate in.

Then you go to use the reference implementation and discover it needs Python, the Gemini API, and BigQuery.

That’s not open. That’s a portable format with a one-vendor on-ramp bolted to the front of it. If the only blessed way to work with OKF requires Google’s language runtime, Google’s model API, and Google’s data warehouse, then the format is open in theory and captured in practice. I’ve spent enough of my career untangling vendor lock-in to recognize the shape of it, and I wanted the format without the box it shipped in.

So I built okf: useokf.com.

A single binary that speaks JSON

okf is a vendor-neutral CLI for building and managing knowledge graphs in the Open Knowledge Format. It’s a single Go binary, stdlib-only, with zero runtime dependencies. No Python interpreter to install, no cloud API key to provision, no warehouse to stand up. You download it, it runs anywhere Go runs, and it speaks JSON as its native tongue — not behind an opt-in --json flag, but by default, because the primary consumer was never going to be a human squinting at a terminal.

It’s Apache 2.0, and it’s test-first. That part matters more than it sounds: a format implementation that other people are supposed to trust as a reference needs to be the kind of thing you can read, audit, and verify, not a black box with a model in the middle of it.

Agentic-first, the same four primitives

If you read my piece on the agent-first CLI, the design here will look familiar, because it’s the same contract applied to a different domain. okf is built to be discovered and operated by an AI agent without any prompt engineering, and it rests on four primitives:

1. Schema discovery. okf schema emits a complete JSON manifest of every command — flags, arguments, output shape, exit codes. An agent loads it once and knows the entire surface. No parsing --help, no guessing at flags, no screen-scraping stdout.
2. JSON-native output. Structured output is the default, not the exception. There’s no English prose on stdout to parse heuristically.
3. Typed error envelopes. Failures come back as structured objects the agent branches on, not error strings it has to interpret.
4. Deterministic exit codes. Codes map to recovery strategies, so retry-and-recover logic can be deterministic instead of guesswork.

This is the whole point. The old way an agent worked with a CLI was to parse --help text, guess at flags, screen-scrape stdout, and hope the English error message was stable. okf removes every one of those guessing games.

The command surface

Eleven commands across four jobs:

Discovery — okf schema emits the full machine-readable manifest so an agent can self-discover the CLI.

Structure — okf init scaffolds a bundle; okf index generates progressive disclosure so a large graph can be navigated without loading the whole thing into a context window.

Quality — okf validate enforces spec compliance; okf lint flags warnings. This is the part I care about most: if the format is going to be a real interchange standard, the tooling has to be able to tell you, deterministically, whether a given bundle is conformant. A reference implementation that can’t validate isn’t a reference.

Exploration — okf list, okf search, and okf show query concepts; okf graph and okf backlinks map the relationships between them. This is where an agent actually does its reasoning — walking the graph, following backlinks, pulling the concepts relevant to whatever it’s working on.

Why a single binary is the whole argument

The thing I keep coming back to: portability is a property you have to defend, not one you get for free by writing “open” in a spec. A format is exactly as open as its most-used implementation is easy to run.

A Python-plus-Gemini-plus-BigQuery toolchain is a participation tax. It says: to work with this open format, first adopt these three products. A single static binary says the opposite. It drops into a CI pipeline, a cron job, a Dockerfile, a coworker’s laptop, or an agent’s tool list with no runtime to provision and no account to create. That’s not a nice-to-have on top of the format — for a format that wants to be a standard, it is the format’s openness, made real.

knowledge engineers, documentation pipelines, and AI agents that need to build and traverse a knowledge graph shouldn’t have to rent a cloud stack to do it. okf is at useokf.com, it’s Apache 2.0, and it runs anywhere.