OKFZ: the portable, shareable knowledge bundle

What an OKFZ is

An OKFZ is the portable, shareable bundle pdf2okf builds from your PDF. Under the hood it's exactly what the standard describes. It's a set of OKF-compatible concept files: small, linked Markdown documents with YAML frontmatter, where the text, tables, and diagrams of the original have been turned into explicit, greppable structure. The difference is that an OKFZ is packaged. The whole knowledge base (concept files, frontmatter, the index.md entry point, the relationships between the pieces) travels as one self-contained artifact you can hand to someone.

Think of the format as the grammar and the OKFZ as the finished, sealed envelope. OKF tells you what a single knowledge file looks like. An OKFZ is what you get once pdf2okf has read an entire PDF and packaged the result so it's ready to move.

Build once, share

Here's the workflow that makes it a differentiator. You run pdf2okf against a PDF once: on your own hardware, or against your own key, with no page leaving your machine. That single build produces the OKFZ. From then on, the bundle is just a thing you have:

• Version it. Commit it to git like any other artifact, diff it, tag releases of your knowledge.
• Move it. Copy it to another machine, drop it in object storage, attach it to a ticket.
• Share it. Hand it to a colleague, a client, or another agent.

And here's the part that matters: none of those actions re-process the source PDF. The expensive step (reading the document, extracting structure, writing the concept files) happened exactly once, when you built the bundle. Sharing an OKFZ doesn't re-run it. The recipient doesn't need the original PDF, doesn't need pdf2okf to parse anything, and doesn't stand up any infrastructure to read what they received. Build once, share the bundle, done.

Why this beats shipping a vector database

Compare that to how knowledge usually gets shared with an AI today. The conventional RAG path is: chunk the document, embed the chunks, load them into a vector database, and then (if you want a colleague to have the same thing) ship that database too. That's a bad thing to ship, for concrete reasons:

• It isn't portable. A vector index is bound to the embedding model that produced it and the runtime that serves it. Hand someone the vectors and you've handed them a dependency, not a document.
• It isn't human-readable. Open the index and you see numbers. There's nothing a person can review, correct, or even sanity-check.
• It usually means re-embedding. Different model, different version, or different provider on the other end: the knowledge has to be rebuilt before it's useful again.
• It carries hosting with it. Something has to keep running for the data to be queryable at all.

An OKFZ is the inverse on every count. It's portable because it's files. It's human-readable because it's Markdown. A recipient can open it, read it, even edit it in a text editor. There's nothing to re-embed, because there are no embeddings in the bundle; the structure is the text. And there's no vector DB to ship, because the knowledge was never trapped in one. A vector index is something you host. An OKFZ is something you own.

You own the bundle

That ownership is the through-line. An OKFZ isn't a view into a service you're renting; it's an artifact that sits on your disk and answers to no one. No account has to stay current for it to remain readable. No vendor's runtime has to stay alive for it to mean something. If the company that made the tool vanished tomorrow, your OKFZ would still open, still read, still work, because it's just OKF-compatible Markdown in a wrapper, and the format is a published, vendor-neutral standard, not a private trick.

This is what we mean by own your format. A model you run yourself means no one can switch off your intelligence. A format you own means no one can lock up your knowledge. An OKFZ is that principle made into a file you can email. The standard, OKF, gives the format its legitimacy; the OKFZ gives it legs.

pdf2okf exists to build them. Point it at a PDF, get back a portable, shareable, OKF-compatible bundle you actually own: no cloud round-trip, no vector database, and no re-processing the day you want to hand it to someone else.