Open Knowledge Format: Portable Memory for AI Coding Agents

The Open Knowledge Format is a standard meant to make agent memory portable, versioned and readable by every tool in a developer's stack.

The problem with starting over every morning

Anyone using an AI coding agent has met the same wall. The session closes, and the next day the agent knows nothing. It rediscovers the auth flow, guesses again at the reasoning behind a three-year-old architecture decision and rereads the same five files to rebuild context that took an hour to explain the day before.

The common workaround is a CLAUDE.md or AGENTS.md file, a context document read in at the beginning of each session. Those are crude tools. They pull in everything on every run whether it matters or not, they're written for a single agent on a single platform and they don't move well. They also mix behavioral instructions like "always write tests" with facts like "the orders table joins to customers on customer_id", which gets disorderly fast.

On June 12, 2026, Google Cloud published a specification aimed at this gap, called the Open Knowledge Format, or OKF. It's the tidiest answer to the agent memory problem so far.

Where knowledge lives today

Suppose an agent has to answer how weekly active users are computed from an event stream. The answer is spread across at least four places:

+-----------------------+--------------------------------------------+
| WHERE IT LIVES        | WHAT'S THERE                               |
+-----------------------+--------------------------------------------+
| Metadata catalogs     | Table schemas (but vendor-locked APIs)     |
| Wiki / Notion         | Runbooks, metric definitions               |
| Code comments         | Docstrings, inline notes                   |
| People's heads        | Join paths, deprecation warnings           |
+-----------------------+--------------------------------------------+

Nothing here moves along with the code and nothing outlives a new context window. Each agent builder works out the same context-assembly puzzle again, and each catalog vendor makes up its own schemas.

OKF bets that what's missing is a format and not one more platform.

What the format is

Version 0.1 of the Open Knowledge Format is an open, vendor-neutral spec licensed under Apache 2.0. Knowledge is stored as a directory of markdown files, each with YAML frontmatter. It sounds simple because it is simple, and that's intentional.

There's no schema registry, no runtime engine and no required SDK. Anything that can cat a file can read it, and anything that can git clone a repo can ship it. The whole spec fits on a single page and has exactly one required field, with everything else optional or left to the producer.

Anatomy of a bundle

A bundle is just a folder, and a file's path serves as the identity of its concept.

.okf/
+-- index.md                      <- progressive entry point
+-- log.md                        <- dated change history, newest first
+-- services/
|   +-- index.md
|   +-- auth-api.md               <- one concept = one file
|   +-- payments-service.md
+-- datasets/
|   +-- index.md
|   +-- orders-db.md
+-- metrics/
|   +-- index.md
|   +-- weekly-active-users.md
+-- decisions/
    +-- index.md
    +-- why-we-use-postgres.md

Two filenames are reserved in every bundle:

• index.md handles progressive disclosure. Agents move through a bundle by reading the index at each level and descending only when the task calls for it. That's the same staged loading that keeps Claude Skills economical with tokens.
• log.md is a change history with ISO dates, newest entry first. Humans and agents who maintain the bundle both add to it when concepts change.

Every other file is a concept document, identified by its path. The only frontmatter a concept must have is a non-empty type field.

---
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
---

The body then holds ordinary markdown, tables included.

## Endpoints| Method | Path     | Description               |
|--------|----------|---------------------------|
| POST   | /token   | Exchange creds for a JWT. |
| GET    | /verify  | Validate a token.         |## Why This ExistsSee the decision at [decisions/why-we-separated-auth.md](../decisions/why-we-separated-auth.md).
Joins with [datasets/orders-db.md](../datasets/orders-db.md) for user scoping.

The key design move comes next. Concepts link to one another through standard markdown links. That makes the directory a graph, a set of typed, cross-referenced knowledge with explicit relationships you can traverse, instead of a flat pile of documents.

[auth-api.md]
                    /            \
                  links          links
                  /                \
[decisions/why-separated-auth.md]  [datasets/orders-db.md]
                                        |
                                      links
                                        |
                                [datasets/customers-db.md]

A tool able to follow a markdown link can traverse the graph, and an agent with file access can both read and write it.

Since only type is required, the producer chooses which types exist (Service, Dataset, Metric, Decision, Runbook and so on), which optional fields to use and what body sections to include. OKF defines interoperability and not content models.

Producers and consumers

The format works the same at both ends, so swapping a producer or consumer doesn't break the knowledge.

PRODUCERS                       CONSUMERS
---------                       ---------
Human authors       ---->       AI agents
BigQuery pipelines  ---->       HTML visualizers
LLM-generated       ---->       Search indexes
Wiki exports        ---->       Other agents / tools

There's no proprietary account, no SDK and no central registry. Value grows with the breadth of adoption and not through vendor lock-in. That follows the philosophy behind git, markdown and JSON, formats that lasted because they demanded nothing to use.

How it relates to CLAUDE.md and MCP

Most confusion starts here. OKF doesn't replace tools already in use. It fills a particular gap.

+---------------------+---------------------------+---------------------------+
| TOOL                | PURPOSE                   | SCOPE                     |
+---------------------+---------------------------+---------------------------+
| CLAUDE.md           | How the agent behaves     | Per-project, one agent    |
| AGENTS.md           | Repo instructions         | Per-repo, tool-specific   |
| Karpathy LLM wiki   | Agent-maintained notes    | Pattern, not a spec       |
| MCP                 | Live tool access          | Runtime connections        |
| OKF                 | What the team knows       | Cross-project, any agent  |
+---------------------+---------------------------+---------------------------+

A clean mental model separates three questions:

• CLAUDE.md says how the agent should behave.
• OKF says what the team knows about this system.
• MCP says which live tools the agent can call at this moment.

They stack. A CLAUDE.md line might say to read .okf/metrics/ before any analytics task. The OKF bundle then supplies the structured knowledge CLAUDE.md points to, and MCP connections supply the live data sources that OKF documents describe.

The wiki idea it echoes

Andrej Karpathy, who coined "vibe coding" and now favors the phrase "agentic engineering", published an LLM wiki gist that picked up more than 5,000 stars. His argument is simple. People drop wikis when upkeep becomes a chore, but agents don't tire of it, forget a cross-reference or struggle to edit 15 files in one pass.

The same pattern kept turning up independently, in Obsidian paired with coding agents, in repos full of AGENTS.md and in index.md and log.md artifacts across dozens of projects. People were reinventing one thing. What OKF adds is agreement on which fields each document carries and what filenames mean, so separate wikis and even a BigQuery catalog export can cooperate without translation.

The mapping between the two has three layers:

KARPATHY LAYER              OKF EQUIVALENT
--------------              --------------
Raw sources (immutable) --> External datasets, docs, APIs
                            (OKF bundles are the compiled layer)

Wiki (LLM-maintained)   --> OKF bundle (*.md + frontmatter)
                            (OKF adds type, resource, tags, timestamp)Schema (CLAUDE.md)      --> Producer/consumer conventions + okf/SPEC.md
                            (org-wide spec replaces per-vault bespoke rules)

Both Karpathy's gist and OKF set aside index.md and log.md for the same jobs, and that convergence wasn't an accident.

What Google shipped with it

OKF is a spec, yet Google released three practical pieces alongside it:

1. A BigQuery enrichment agent. Pointed at a dataset, it drafts an OKF concept doc for each table and view, then makes a second LLM pass that adds citations, schemas and join paths drawn from documentation. The output for a data warehouse is a filled-in .okf/ directory.
2. A static HTML visualizer. It converts any OKF bundle into an interactive graph in one self-contained HTML file, with no backend and nothing leaving the page. Concepts appear as nodes and markdown links as edges, and clicking a node opens a wiki-style panel with rendered markdown and backlinks labeled "Links to / Cited by".
3. Sample bundles. Three real bundles on GitHub use public BigQuery datasets:

+--------------------+----------------------------------+
| BUNDLE             | WHAT IT DOCUMENTS                |
+--------------------+----------------------------------+
| GA4 e-commerce     | Analytics tables and metrics     |
| Stack Overflow     | Public dataset concepts          |
| Bitcoin            | Blockchain dataset structure     |
+--------------------+----------------------------------+

They work both as starter templates to copy and as proof the format holds up across domains.

When OKF is the right choice

It fits when the knowledge problem looks like one of these:

• The same explanations repeat in every new agent session. If one context block keeps getting pasted into CLAUDE.md, it belongs in OKF.
• Knowledge spans several projects or teams. CLAUDE.md is tied to one project and one agent, while OKF bundles move between repos, agents and tools.
• Project docs should be versionable. OKF sits in git beside the code it describes, every change shows up in a diff and a pull request can carry knowledge updates with code changes.
• The stack is Google Cloud and BigQuery. There's a direct integration with Google's Knowledge Catalog, which takes in bundles and hands them to GCP agents.
• A knowledge graph is wanted and not a flat wiki. The markdown link graph gives typed relationships between concepts with no graph database.

It's the wrong choice in a few cases:

• Real-time data is needed, which calls for MCP.
• Behavioral rules need encoding, which is CLAUDE.md's job.
• The project is small and fits one session, where CLAUDE.md alone is enough.

Getting started

Setup is minimal by design.

With Claude Code

The okf-skills plugin bundles three skills. /okf:okf creates and maintains bundles, /okf:validate checks that a bundle conforms and /okf:visualize builds the interactive graph. Install it with:

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

Any agent, including Claude Code, Cursor, Codex and over twenty others, can instead use npm:

npx skills add scaccogatto/okf-skills

Then run the skills:

/okf:okf produce .okf        # create your first bundle
/okf:validate .okf --strict  # check conformance
/okf:visualize .okf          # generate viz.html

To keep things current automatically, so Claude reads .okf/ ahead of tasks and records what it learned afterward, copy the templates/CLAUDE-okf.md template into the project's CLAUDE.md. Nothing forces this step.

Writing it by hand

Create a .okf/ directory and add an index.md. Then add one concept file for each important thing the system does. A decision record looks like this:

---
type: Decision
title: "Why we use Postgres over MySQL"
description: "JSONB support and row-level security were decisive."
timestamp: 2026-03-01T00:00:00Z
tags: [infrastructure, database]
---

The body follows:

## ContextIn early 2026 we evaluated both options. MySQL's JSON support was insufficient for our metadata schema...## DecisionPostgres 16. See [datasets/primary-db.md](../datasets/primary-db.md) for schema docs.

That's all it takes. Any agent with file access can read the file at once, and it can be reviewed in a PR and diffed in git.

The whole stack

Here's how OKF sits next to everything else in a session:

+--------------------------------------------------+
|              AGENT SESSION                       |
+--------------------------------------------------+
|  CLAUDE.md / AGENTS.md                          |
|  (behavioral rules - how agent acts)            |
+--------------------------------------------------+
|  OKF BUNDLE (.okf/)                             |
|  (curated team knowledge - what we know)        |
|  - index.md: entry points per domain            |
|  - concepts/*.md: services, datasets, decisions |
|  - log.md: change history                       |
+--------------------------------------------------+
|  AUTO-MEMORY (memory.md)                        |
|  (what the agent picked up implicitly)          |
+--------------------------------------------------+
|  MCP CONNECTIONS                                |
|  (live tool access - what the agent can do)     |
+--------------------------------------------------+
|  SKILLS (.claude/skills/)                       |
|  (reusable SOPs - how to do specific tasks)     |
+--------------------------------------------------+

Each layer answers its own question. They don't overlap, they compose.

What v0.1 leaves open

Google openly calls v0.1 a starting point, with interoperability solved first. Several design questions remain:

• Contradictions. When two OKF docs disagree about one fact, no merge semantics exist yet.
• Stale knowledge. Because OKF is file-based, a doc left unchanged when the system moved on is a process failure and not a format one.
• Typed relationships. Today's spec uses plain markdown links, and richer edge types such as contradicts, extends or supersedes are being worked out by the community.
• Faceted search. Some practitioners want more tagging than the minimal spec offers.

A v0.2 will probably address several of these based on feedback, and the spec repo is public and accepting issues and PRs.

Why boring formats win

Formats that become infrastructure tend to be dull. JSON won because it was the simplest thing that worked and cost nothing to adopt, not because it was clever. Markdown won the same way.

OKF fits that description. It takes nothing to read, nothing to write and it runs with any tool that handles files. Value grows with the count of producers and consumers, and a single vendor's decisions don't steer it. It also writes down a pattern people had already reached on their own, through Karpathy's gist, AGENTS.md habits and hand-built index.md hierarchies, which is the best evidence that a genuine problem is being solved.

Karpathy's point was that agents maintain wikis better than humans because they don't get bored. OKF's point is that a wiki compounds in value only if it can travel. Together, those two ideas could look like a foundational piece of agent-assisted development in a few years. Building it now, while it's new, will pay off for later you and for every agent you brief.