{"slug": "okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read", "title": "OKF for Claude Code: structured, portable memory your agent (and team) can read", "summary": "A developer released okf-skills, an open-source toolchain that implements the Open Knowledge Format (OKF) for Claude Code and other coding agents. OKF provides structured, versioned, and portable project knowledge that agents can read and maintain, addressing the problem of lost context across sessions. The toolchain includes a producer, validator, and visualizer, and is available as a Claude Code plugin or via skills.sh for 20+ agents.", "body_md": "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.\n\n`CLAUDE.md`\n\nhelps, 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.**\n\n[ Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) is an open, vendor-neutral format (announced by the Google Cloud Data Cloud team in June 2026, Apache-2.0) that represents knowledge as\n\n`cat`\n\na file you can read it; if you can `git clone`\n\na repo you can ship it.A bundle looks like this:\n\n```\n.okf/\n├── index.md                  # progressive disclosure (root carries okf_version)\n├── log.md                    # ISO-dated change history, newest first\n├── services/auth-api.md      # one concept = one file; path is its ID\n├── datasets/orders-db.md\n├── decisions/use-okf.md\n├── runbooks/payment-failures.md\n└── metrics/checkout-conversion.md\n```\n\nEach concept needs exactly one thing to be conformant: YAML frontmatter with a non-empty `type`\n\n. Everything else is optional.\n\n```\n---\ntype: Service\ntitle: \"Auth API\"\ndescription: \"Issues and verifies short-lived access tokens.\"\nresource: https://github.com/acme/auth\ntags: [auth, platform]\ntimestamp: 2026-06-14T10:00:00Z\n---\n\n# Endpoints\n| Method | Path     | Description               |\n|--------|----------|---------------------------|\n| `POST` | `/token` | Exchange creds for a JWT. |\n```\n\nConcepts 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.\n\nOKF 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:\n\n| Skill | What it does |\n|---|---|\n`/okf:okf` |\nProduce, maintain, and consume bundles, applying the spec and templates. Auto-triggers when a repo already has an OKF bundle. |\n`/okf:validate` |\nDeterministic §9 conformance check — a real Python checker, not an eyeball pass. |\n`/okf:visualize` |\nRender a bundle to a self-contained interactive HTML graph. |\n\nThe validator and visualizer are standalone scripts too (`uv run`\n\n, 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`\n\n— 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](https://scaccogatto.github.io/okf-skills/) of a real bundle, and the repo\n\nA few things worth being straight about:\n\n`CLAUDE.md`\n\nfor As a Claude Code plugin:\n\n```\n/plugin marketplace add scaccogatto/okf-skills\n/plugin install okf@scaccogatto\n```\n\nAs agent skills (Claude Code, Cursor, Codex, 20+ agents):\n\n```\nnpx skills add scaccogatto/okf-skills\n```\n\nThen capture, validate, and visualize:\n\n```\n/okf:okf produce .okf          # or just ask: \"document the auth service in OKF\"\n/okf:validate .okf --strict\n/okf:visualize .okf            # opens a shareable viz.html\n```\n\nEvery concept gets a deep link — `viz.html#services/auth-api`\n\nloads the graph with that concept already selected.\n\nTo turn on automatic upkeep (consult `.okf/`\n\nbefore tasks, write knowledge back after changes), paste `templates/CLAUDE-okf.md`\n\ninto your project's `CLAUDE.md`\n\n. It's soft mode and entirely opt-in. The scripts need [ uv](https://docs.astral.sh/uv/) (or\n\n`python3`\n\n+ `pyyaml`\n\n).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.\n\nRepo, demo, and spec: ** github.com/scaccogatto/okf-skills**. Issues and PRs welcome.", "url": "https://wpnews.pro/news/okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read", "canonical_source": "https://dev.to/scaccogatto/okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read-4ocn", "published_at": "2026-06-28 12:44:50+00:00", "updated_at": "2026-06-28 13:04:14.419318+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents", "ai-products"], "entities": ["Claude Code", "Open Knowledge Format", "okf-skills", "Google Cloud Data Cloud", "Cursor", "Codex", "skills.sh", "scaccogatto"], "alternates": {"html": "https://wpnews.pro/news/okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read", "markdown": "https://wpnews.pro/news/okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read.md", "text": "https://wpnews.pro/news/okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read.txt", "jsonld": "https://wpnews.pro/news/okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read.jsonld"}}