serradura-okf

Your coding agent works out how your system fits together — why the service exists, what the metric actually measures, which line of the schema is load-bearing — and then the session ends and all of it is gone. Next session it works the same things out again, from the same code, and reaches slightly different conclusions.

okf gives that reasoning somewhere to live. Plain Markdown files in your repo, next to the code they explain, written and kept current by the agent itself rather than by you.

It adds nothing to your stack. No database, no service, no new place to keep knowledge — just files, reviewed in the same pull request as the code. If you stop using okf tomorrow, everything it wrote is still Markdown your team can read.

See it in sixty seconds

This repository documents itself in OKF, so you can walk a real bundle before installing anything:

gem install okf
git clone https://github.com/serradura/okf && cd okf
okf server .okf          # the whole ecosystem as an interactive graph

No Ruby on the machine? The published image runs the same commands — docker.okfgem.com. Or skip the clone entirely and open demo.okfgem.com.

Why it doesn't rot

Notes decay because keeping them current is a separate act from doing the work. Here it isn't:

• The agent writes it, not you. An Agent Skill ships with the gem, so curation happens inside the work rather than after it.
• Drift is a failing build. okf validate and okf lint return exit codes, so a stale or malformed bundle breaks CI the same way a broken test does.
• The agent reads only what it needs. okf index reads the map and okf search pulls the handful of files a task touches, so the knowledge outgrows the context window instead of filling it.

How it compares

Knowledge already has several homes near an agent, and each holds something different. None of the others is built for curated, durable team knowledge:

	OKF bundle (this)	CLAUDE.md / AGENTS.md	Agent auto-memory	Wiki / Notion
Holds	curated team knowledge	standing instructions	what one agent picked up	human docs
Versioned with the code	✅	✅	❌	❌
Portable across agents	✅ plain Markdown + YAML	⚠️ per-harness conventions	❌ per-agent store	⚠️ export needed
Typed and queryable	✅ frontmatter + graph	❌ prose	❌	⚠️ partially
Reviewed in PRs	✅	✅	❌ implicit	⚠️ rarely
Scales past one context window	✅ progressive disclosure(okf index + search)	❌ loaded whole	⚠️ partially	n/a
Checked by tooling	✅ exit codes for CI(okf validate + lint)	❌	❌	❌

The last two rows are this gem's job.

OKF is an open, vendor-neutral format (Google Cloud, 2026). This repository is a complete implementation of it, distributed as four gems, a Docker image, and a Claude Code plugin.

What a bundle looks like

A bundle is just a directory; each concept is one Markdown file whose path is its id. This repo documents itself in OKF, so the tree below is real:

.okf/
├── index.md                       # progressive-disclosure map (root carries okf_version)
├── log.md                         # ISO-dated change history, newest first
├── overview.md
├── gems/okf-mcp.md                # one concept = one file
├── decisions/monorepo-layout.md
└── format/frontmatter.md

The only hard requirement is YAML frontmatter with a non-empty type; everything else is optional and tolerated when missing. A concept reads as below — this is the real capabilities/graph-server.md from the baseline gem's own bundle, gems/okf/.okf/, with its body trimmed:

---
type: Capability
title: Interactive graph server (server)
description: A self-contained HTML knowledge graph — served over HTTP as a mountable Rack app, one bundle or many behind a hub, or written to a single static file.
resource: gems/okf/lib/okf/server/app.rb
tags: [server, graph, rack, diagram]
generated:
  by: human:maintainer
  at: 2026-08-13T12:00:00Z
---

# Overview

`okf server` boots an interactive view of the [graph](../model/graph.md) …

The .okf/ above is the ecosystem's map — a concept per gem, per plugin item, per skill — and each gem carries its own bundle beside its code. Clone the repo and run okf server .okf to browse the map as an interactive graph, or okf server gems/okf/.okf for the baseline gem's.

Trust, provenance, and lifecycle — OKF v0.2

Knowledge written continuously by agents raises questions a static corpus never had to answer: who wrote this, who checked it, is it still current? OKF v0.2 makes them frontmatter — generated (who produced the content, and when), verified (who confirmed it, deriving the trust tier every surface shows: unverified · machine-confirmed · human-reviewed), sources with per-claim footnote attribution, status, and stale_after — and this gem reads all of it: as catalog columns and --status/--trust filters, as the graph page's third visual channel, and as lint's provenance, attestation and migration findings. Every family is optional, and a v0.1 bundle keeps reading forever — two lint findings tell you exactly what a migration would change, and never fail you for not having done it.

The whole ecosystem

Knowledge an agent writes dies in four places, and a tool that fixes one of them only gets to watch it die in the next. It never gets written, because writing it up is a separate act from doing the work. It rots, and nothing says so until someone acts on a claim that stopped being true. It cannot be found, because the corpus outgrew the person who would have to read it all. And it is stuck in whichever tool wrote it, so the next tool starts over.

The pieces below are one answer per failure. They are separate gems because they install separately, not because they are separate products: every one of them reads the same folder of Markdown, none of them is required by any other, and what you would lose by dropping all of them is tooling, never the knowledge.

One install — gem install okf — carries three pieces:

• an Agent Skill, so the knowledge gets written at all: your agent curates inside the work rather than promising to write it up afterwards, and you stay the editor;
• a CLI and Ruby library, so you can ask the corpus a question instead of reading it — what is in here, which types and which tags, what links to what, what nothing links to, where the term you half-remember appears — and so drift is a failing build rather than a feeling: validate and lint answer with exit codes CI already knows how to fail on;
• a Graph, so the shape of what the team knows is a thing you can look at — live on your machine, or one self-contained HTML file you can host anywhere or hand to someone who will never install this.

Three sibling gems extend that same command rather than adding another one:

• okf mcp (okf-mcp), so the knowledge is not stuck in whichever terminal wrote it: any MCP host reads it with no shell and nothing pasted into context — fourteen read tools, over stdio or Streamable HTTP;
• okf tui (okf-tui), so looking around costs a keystroke instead of four commands: six views over one bundle or every registered one, and you can read one while searching all of them;
• okf pro (okf-pro), so the practice holds on the days nobody is watching: it writes an agent's knowledge repository and then refuses to let it rot, at three doors that each fail closed.

gem install okf-pro and you type okf pro. Packaging multiplies; the interface does not, and a sibling ships no second binary to learn.

The second bundle costs nothing

Nobody stops at one. The service you documented last month, the team handbook, the gem you maintain on the side — each is its own bundle in its own repository, and that is the right answer rather than a filing problem to clean up later.

So a bundle gets a name. okf registry set ./handbook makes it @handbook, and anywhere a directory goes a @slug goes: okf lint @handbook, okf render @handbook -o graph.html. Groups collect the ones you think about together, and @all reaches every one you have registered — so the same four commands hold your whole corpus at once instead of one bundle of it: