OKF for Claude Code: structured, portable memory your agent (and team) can read

The problem: agents forget your project every session

If you pair with a coding agent, you have lived this: a new session starts and the context is gone. The agent re-discovers your auth flow, re-guesses why a decision was made, re-reads the same files to rebuild a mental model you already explained yesterday. Project knowledge — the why behind your systems, the runbooks, the "don't touch this, here's the reason" — lives scattered across wikis, code comments, and people's heads. None of it travels with the code, and none of it survives a fresh context window.

CLAUDE.md helps, but it's for standing instructions, and it gets loaded wholesale into every prompt. Auto-memory captures what an agent picked up, but it's implicit, per-agent, and not reviewed. A wiki is for humans and needs exporting. There's a gap: curated team knowledge that's structured, versioned with the code, and readable by any agent or person.

What OKF is

Open Knowledge Format is an open, vendor-neutral format (announced by the Google Cloud Data Cloud team in June 2026, Apache-2.0) that represents knowledge as a directory of markdown files with YAML frontmatter. That's the whole idea. No schema registry, no runtime, no SDK. If you can cat a file you can read it; if you can git clone a repo you can ship it.

A bundle looks like this:

.okf/
├── index.md                  # progressive disclosure (root carries okf_version)
├── log.md                    # ISO-dated change history, newest first
├── services/auth-api.md      # one concept = one file; path is its ID
├── datasets/orders-db.md
├── decisions/use-okf.md
├── runbooks/payment-failures.md
└── metrics/checkout-conversion.md

Each concept needs exactly one thing to be conformant: YAML frontmatter with a non-empty type. Everything else is optional.

---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---

# Endpoints
| Method | Path     | Description               |
|--------|----------|---------------------------|
| `POST` | `/token` | Exchange creds for a JWT. |

Concepts link to each other with plain markdown links, which makes the bundle a graph of typed, cross-referenced knowledge — diffable, reviewable in PRs, and portable across tools because it's just text.

What okf-skills adds

OKF is the format. okf-skills is the Claude Code-native toolchain that teaches your agent to actually use it, driven by the verbatim v0.1 spec. It ships as a Claude Code plugin and as agent skills (installable on Cursor, Codex, and 20+ agents via skills.sh). Three pieces:

Skill	What it does
/okf:okf	Produce, maintain, and consume bundles, applying the spec and templates. Auto-triggers when a repo already has an OKF bundle.
/okf:validate	Deterministic §9 conformance check — a real Python checker, not an eyeball pass.
/okf:visualize	Render a bundle to a self-contained interactive HTML graph.

The validator and visualizer are standalone scripts too (uv run, PyYAML via PEP 723), so they work the same whether installed as a plugin or as skills. The visualizer output is a single viz.html — concepts as nodes, links as edges, a wiki-style detail panel with rendered markdown and "Links to / Cited by" backlinks. No backend; nothing leaves the page. There's a live demo of a real bundle, and the repo documents itself in OKF, with CI validating that bundle on every push.

Honest scope

A few things worth being straight about:

• OKF is curation, not magic. It's a place to put knowledge deliberately, not a system that captures it automatically. Someone (you, or the agent on request) still writes the concepts. The payoff is durability and portability, not zero effort.
• It's complementary, not a replacement. Use CLAUDE.md for how to behave, auto-memory for what the agent picked up, and an OKF bundle for what the team knows. They stack.
• No hooks by design. The plugin won't silently rewrite your repo. Automatic upkeep is opt-in (see below).
• The format spec is Google's, vendored verbatim with attribution; this plugin's own code is MIT © Marco Boffo.

Install and try it

As a Claude Code plugin:

/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

As agent skills (Claude Code, Cursor, Codex, 20+ agents):

npx skills add scaccogatto/okf-skills

Then capture, validate, and visualize:

/okf:okf produce .okf          # or just ask: "document the auth service in OKF"
/okf:validate .okf --strict
/okf:visualize .okf            # opens a shareable viz.html

Every concept gets a deep link — viz.html#services/auth-api loads the graph with that concept already selected.

To turn on automatic upkeep (consult .okf/ before tasks, write knowledge back after changes), paste templates/CLAUDE-okf.md into your project's CLAUDE.md. It's soft mode and entirely opt-in. The scripts need uv (or python3 + pyyaml).

Why bother

The pitch is small and concrete: give your project's knowledge one durable, diffable, portable home, versioned next to the code it describes — instead of re-explaining it to a fresh agent every morning. It's plain markdown, so worst case you've written some good docs your team can read. Best case your agent stops forgetting.

Repo, demo, and spec: github.com/scaccogatto/okf-skills. Issues and PRs welcome.