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

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:

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 , 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 . Issues and PRs welcome.