OKF (Open Knowledge Format): Durable, structured memory for AI agents.
> /plugin marketplace add serradura/okf> /plugin install okf@okfgem
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.
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.
Notes decay because keeping them current is a separate act from doing the work. Here it isn't:
okf validate and okf lint return exit codes,
so a stale or malformed bundle breaks CI the same way a broken test does.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.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.
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.
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.
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:
validate and lint answer with
exit codes CI already knows how to fail on;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.
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:
View @serradura’s profileOKF (Open Knowledge Format): Durable, structured memory for AI agents. Author, validate, consume, and maintain portable knowledge bundles through an ecosystem of Skills, MCP, an interactive graph, TUI, CLI, Docker, and a Claude Code plugin. 100% local.
@serraduraserradura-okf-2 is a Claude Code plugin with 3 hand-picked skills, indexed on Flowy in the Documentation category. Install it with the command on its page. It includes okf-pro, okf, okf-principles. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it