OKF#

AI Generated, Human Reviewed at: 2026-11-16T19:56:21Z

Use it when the knowledge needs to say where it came from, who checked it and when it expires, especially when agents write part of it. Open Knowledge Format is a Markdown convention for exactly that: each note (a concept) starts with a small header of facts, and the tools check that the whole folder is well formed. It is the only format with the full toolset: lint, fix, cite, provenance, status, move, rename and the rest.

What OKF is#

Open Knowledge Format (OKF) is a way of writing down what you know so that people and AI assistants can both use it. The whole format is this: a folder of Markdown files, each starting with a short block of facts about the file. The specification calls that block frontmatter and writes it in YAML. That is the entire technology. There is no database, no server, no registry of allowed types and no required software. In the specification's own words: if you can cat a file you can read OKF, and if you can git clone a repository you can ship it.

OKF is published as a specification (this site follows version 0.2) in the knowledge-catalog repository on GitHub. Bowerbird is one tool that implements it: it writes, checks and searches OKF folders. Nothing in the format depends on this tool, which is the point.

Why a format at all?#

A pile of Markdown notes is already easy to read. The trouble starts when the pile grows, other people add to it, and AI assistants begin to write parts of it. Then readers need answers a plain note does not give:

  1. Where did this come from? (provenance)
  2. Has anyone checked it, and was it a person or a script? (trust)
  3. Is it still true? (freshness)
  4. Is this the current version, or an old draft? (lifecycle)

Without a convention, every team invents its own answers, and no tool can rely on them. OKF fixes a small set of conventions for exactly these questions and leaves everything else to you.

The pieces#

A collection is a folder of bundles; a bundle is a folder of concepts, one Markdown file each.

kb/
  kbmcp.yaml               format: okf (the default)
  index.md                 lists the bundles
  eng/                     a bundle: its index.md declares okf_version "0.2"
    index.md
    log.md                 what changed, newest first
    db.md
    runbooks/ship.md
    refs/pg.md
  mkt/
    index.md
    log.md
    launch.md

Each concept is frontmatter (what kind of thing it is, where its facts came from, who checked it) over an ordinary Markdown body. Here is eng/db.md:

---
type: Reference
title: Database
description: The PostgreSQL cluster behind every service.
sources:
  - id: pg
    resource: refs/pg.md
verified: { by: human:you, at: 2026-10-27T14:00:00Z }
---

We run PostgreSQL 16.4.[^pg] Deploys follow [the ship runbook](/runbooks/ship.md).

[^pg]: PostgreSQL release notes

The header fields#

Only one is required. type says what kind of thing the file is (Playbook, Reference, Metric and so on). Types are not registered anywhere: pick words that explain themselves, and readers must cope with ones they have not seen. A file with nothing but type is fully valid.

The others are recommended or optional, in three families:

Family Fields Answers
Describing title, description (one sentence), tags, resource (a URI for the thing it describes) What is this, for indexes and search results
Provenance and trust sources (what it was built from), generated (who or what wrote the current text, and when), verified (who confirmed it, and when) Where it came from and how far to trust it
Lifecycle status (draft, stable, deprecated; absent means stable), stale_after (a date after which the content counts as stale) Is it current

Every timestamp is ISO 8601 with an explicit UTC offset, such as 2026-11-13T15:00:00Z. Anything else you add is yours: tools should keep keys they do not understand and must not reject a file for having them.

Trust tiers#

The tier is derived, never typed in. Look at who is in verified:

  • nobody: unverified;
  • only scripts, processes or agents: machine-confirmed;
  • at least one person: human-reviewed.

Who is who is decided by a naming convention for actors: human:<id> for a person (human:ann), process:<id> for an automated process (process:finance-nightly), and <producer>/<version> for an agent or tool (reference_agent/gemini-2.5-pro). Because the tier keys off the human: prefix, anything a person wrote or confirmed must use it. Two things to keep in mind: generated and verified are kept apart on purpose, because who wrote a note need not be who checked it; and tiers are advisory labels, not access control.

Concepts point at each other in two ways: a Markdown link in the body, and a citation in sources, which records where a fact came from. web output=mermaid draws both for the whole collection:

graph LR
  subgraph eng
    db["db.md"]
    ship["runbooks/ship.md"]
    pg["refs/pg.md"]
  end
  subgraph mkt
    launch["launch.md"]
  end
  db -.->|cites| pg
  db -->|links| ship
  ship -->|links| db
  ship -->|links| launch
  launch -->|links| db

Solid arrows are links; dotted ones are citations. The boxes are bundles, so an arrow that leaves its box crosses into another bundle. That is allowed, but lint flags it, because the link breaks if one bundle is published alone.

Links are ordinary Markdown, either relative ([the rollback steps](rollback.md)) or from the bundle root with a leading slash (/runbooks/rollback.md, which survives moving files around inside a folder). A link says "these are related"; the sentence around it says how. A broken link is allowed by the format: it may simply be knowledge nobody has written yet (status lists the pages that links ask for and nobody has written). A citation is different: the claim in the text points at its entry in sources with a Markdown footnote ([^pg]). Links are for navigation, citations are for lineage.

Bundles, index.md and log.md#

A bundle is a folder of concepts, with subfolders as you like. Two filenames are reserved at any level:

  • index.md lists what is in a folder, with each concept's one-line description, so a reader (or an assistant) can see what is available before opening anything. The spec calls this progressive disclosure. At the top of a bundle it may carry one frontmatter key, okf_version. OKF makes it optional; Bowerbird uses it to recognise a folder as a bundle. Tools may generate index.md, and Bowerbird's index does.
  • log.md is the history of changes to that folder, newest first, grouped by date.

A bundle can travel as a git repository (recommended, for the history and the diffs), a zip, or a subfolder of a bigger repository. The word collection, as this site uses it, is not part of OKF: it means a bundle, or a folder of bundles, that Bowerbird manages together.

Try it#

In an empty folder:

kb init holds=okf about="Team runbooks." apply=true
kb create deploy type=Playbook title="Deploy" description="How we ship a release." \
   body='Run the deploy script, then check the dashboard.' output=text
kb cite deploy.md resource=https://example.com/runbook title="Ops runbook" output=text
kb lint output=text

create writes a file with its header, cite records a source and prints the footnote tag ([^runbook]) to put next to the claim it backs, and lint checks the whole collection:

bowerbird-mcp lint: ok: 1 concept(s) in 1 bundle(s) checked, 0 finding(s), conformant: True

A file with no header, a broken link or a fact with no source is a finding, each naming the file, what is wrong and how to fix it, and kb fix apply=true repairs the mechanical ones.

Reviewing#

kb seal writes a verified entry into the concept itself, with a sha256 of the note. The trust tier comes only from who verified: nobody means unverified, a script or agent means machine-confirmed, and a person means human-reviewed. Hits show the tier and whether the note has gone stale. See The tiers are explained above.

Why it is good#

These are the properties that follow from the format itself.

  • Readable with no tools. It is text. Open a file, read it. If this project vanished tomorrow, you would keep every note, in a form any editor shows you. The way out of the format is "stop using the tool".
  • Diffable and reviewable. Because it is plain text in a folder, git shows exactly what changed, who changed it and when, and a pull request can review a knowledge change like a code change.
  • Portable. No schema registry or central authority, so a bundle moves between teams, tools and years without a conversion step.
  • Written for agents without a special SDK. An assistant can read the files directly, and the structure (headings, a one-line description, tags, a type) is what a retrieval tool needs to cut a note into useful pieces and rank them.
  • Honest about trust. Provenance, verification and freshness are part of the file, not a separate system. A reader, human or machine, can tell a checked fact from an unchecked one, and a current one from an expired one, at the moment of reading.
  • Minimal on purpose. Only type is required, unknown fields are tolerated, and there is no fixed list of concept types. You can start with a few notes and add structure as you need it.

What it does not do#

It is worth being plain about the limits.

  • It does not check that anything is true. verified records that someone or something said they checked. The format makes the claim visible; it cannot make it correct.
  • It does not control access. Trust tiers and statuses are signals for readers, not permissions.
  • It is not a database or a search engine. It prescribes no storage, serving or query system. Finding things is up to the tool you use on top.
  • It does not define your vocabulary. Concept types, tags and structure are yours to choose and keep consistent. (vocab in Bowerbird lists what you actually use, so spellings do not drift.)
  • It will not replace domain schemas. Where an asset already has a precise schema (an API description, a table definition), OKF points at it with resource; it does not copy it.

Read on#

  • Getting started: build one in ten minutes.
  • The specification: the exact rules, including attested computations, which this page leaves out.
  • Tools: every tool, by role. The guide: layout, the archive, several bundles, CI and settings.