Author(s): Kushal Banda

Originally published on Towards AI.

Your AI Agents Keep Forgetting Everything. Google Just Changed How They Remember.

Every team building AI agents hits the same wall. The model can write code, query a database, or debug a pipeline. It doesn’t know your schemas, your business definitions, your runbooks, or why last quarter’s revenue metric excludes refunds. That knowledge sits in wikis, Slack threads, and three senior engineers’ heads. So every team writes a custom context pipeline, and every pipeline is locked to one agent framework.

Google Cloud shipped a fix: the Open Knowledge Format (OKF), via the knowledge-catalog repository. Not a product, a runtime, or an SDK. A spec for writing knowledge as plain markdown files with YAML frontmatter, built for any agent, any framework, any storage backend.

The problem OKF targets

Foundation models can already reason, write code, analyze data. They can’t show up already knowing your business. Context about your systems and decisions sits scattered across tools that don’t talk to each other, so every team builds a bespoke ingestion layer: parser → transform → agent. Rebuild it for the next project. Rebuild it again on the next framework switch.

The OKF authors call this the “Karpathy problem”: wikis fail because humans forget to update them and let links rot. LLMs don’t get bored maintaining a knowledge base. They don’t skip files, they touch fifteen documents at once, they keep structure consistent automatically. The bottleneck was never model capability. It was the missing shared format agents could write into and read from, without a custom pipeline per team.

What OKF actually is

An OKF bundle is a directory of markdown files. Nothing else. Authored by people, generated by agents, exchanged across organizations, consumed by both. No schema registry, no central authority, no required tooling. If you can cat a file, you can read OKF. If you can git clone a repo, you can ship it.

Three concepts make the format work:

• One concept, one file. A BigQuery table, an API endpoint, a metric definition, an incident runbook each gets its own markdown file.
• YAML frontmatter as structured metadata. The only required field is type a short string like BigQuery Table, API Endpoint, Metric, Playbookused for routing and filtering; unknown types must be tolerated gracefully. Recommended fields: title, description, resource (a canonical URI), tags, timestamp.
• Markdown links as the knowledge graph. A link asserts a relationship; the kind of relationship lives in the surrounding prose, not the link syntax. Graph-view consumers treat all links as directed, untyped edges.

Here’s a concept file describing a BigQuery orders table:

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
---

# Schema

| Column | Type | Description |
|---------------|-----------|-------------------------------|
| order_id | STRING | Unique order identifier. |
| customer_id | STRING | FK to customers.md. |
| total_usd | NUMERIC | Order total in USD. |

# Joins

Joined with customers.md on customer_id.

That’s a full, conformant OKF concept. No SDK call produced it. No database write happened. It’s a file you could open in a text editor, drop into Obsidian, or hand to any agent as context.

The conformance bar is deliberately low

A bundle is conformant if:

• Every non-reserved markdown file has parseable YAML frontmatter.
• Every frontmatter block has a non-empty type field.
• Reserved filenames (index.md, log.md) follow their expected structure when present.

That’s it. Three rules. Everything else is soft guidance: consumers must not reject a bundle over missing optional fields, unknown type values, unknown extra keys, broken cross-links, or missing index files. A broken link isn't a bug; it might just be knowledge nobody's written yet. Bundles are meant to stay useful mid-refactor, mid-growth, mid-agent-edit.

index.md lists a directory's contents for progressive disclosure. log.md records a dated, newest-first change history per directory, so agents can spot what changed recently without diffing the whole bundle.

Why this is a break from how agent context works today

Most agent context pipelines look the same: docs, wikis, and databases feed a custom parser, which feeds a transform layer, which feeds the agent. Change agents or frameworks, rebuild the chain. OKF collapses it to two boxes: knowledge sources produce a bundle once, any agent reads it. Write once, use everywhere.

That portability comes from picking established primitives over new ones. OKF sits close to LLM “wiki” repositories, to Obsidian/Notion-style hierarchical markdown, and to “metadata as code” that stores catalog metadata next to source. It differs mainly in being specified: it pins down the small rule set interoperability needs without dictating tooling.

Practical wins fall out of that: bundles are git native, so they version alongside code with clean diffs; tool agnostic, so any editor, framework, or model reads and writes them; and portable, so moving a bundle between teams is a directory copy, not a migration.

Here’s the shift in concrete terms:

Custom context pipeline OKF bundle Format Proprietary per project Markdown + YAML frontmatter Tooling to read it Custom parser required cat, any editor, any agent Switching agent frameworks Rebuild the ingestion layer No change.

What ships alongside the spec

The repository isn’t just a spec. It includes a reference agent that auto-generates OKF bundles, plus a bundled graph viewer for browsing a bundle’s cross-links. Google frames both as proof of concept; the format is the actual contribution.

Worked samples pair a recipe with the bundle it produces:

• GA4 Google Merchandise Store — seeded from canonical BigQuery Export docs.
• Stack Overflow — mirrors the community’s schema references; exercises multi-concept enrichment.
• Bitcoin — public crypto dataset.

Third-party tooling is already building on the spec: okc reads a Postgres schema and emits a cross-linked bundle, treating foreign keys as graph edges. claude-okf goes further and turns the spec into a slash command.

Generating a bundle with Claude: /okf

Adds a /okf command to Claude Code. Run it inside a project and Claude reads the live spec, walks the codebase, and writes a conformant bundle next to your source. No config file, no separate service.

What happens after you run it:

• Fetches the current spec from the repo rather than a cached copy, since the format is still moving.
• Scans the repo for concepts worth documenting: tables, API routes, core modules, deploy runbooks.
• Writes one markdown file per concept, each with a type field and cross-links to related concepts.
• Generates index.md per directory so the bundle is browsable before opening individual files.
• Runs a companion audit agent against the three conformance rules, flagging missing type fields or malformed frontmatter.
• On future sessions, a hook checks if the bundle has drifted behind the code and nudges you to update it.

The output for a small API service might look like this:

docs/okf/
├── index.md
├── endpoints/
│ ├── index.md
│ ├── create-order.md
│ └── get-order.md
└── runbooks/
 └── deploy-rollback.md

endpoints/create-order.md, generated straight from the route handler:

---
type: API Endpoint
title: Create Order
description: POST /orders - creates a new order and reserves inventory.
resource: /api/v1/orders
tags: [orders, checkout]
timestamp: 2026-07-26T00:00:00Z
---

# Request

| Field | Type | Required |
|-------------|--------|----------|
| customer_id | string | yes |
| items | array | yes |

Calls inventory reservation. See [deploy-rollback.md](/runbooks/deploy-rollback.md) for rollback steps if reservation fails downstream.

That file didn’t come from a database export or a schema registry. Claude read the handler code and the deploy runbook, then wrote both a spec-conformant concept file and the link between them.

Where the format is headed

Google Cloud calls OKF v0.1 a starting point, not a finished standard, expected to evolve as more producers and consumers emerge. That’s already visible: the live spec has moved to v0.2, adding provenance, trust, lifecycle, and attestation as first-class concerns while keeping the core format just as unopinionated. Minor bumps add backward-compatible fields; major bumps can rename required fields or change reserved filenames.

If you’re building or maintaining agent context today: stop writing a bespoke pipeline per project. Write knowledge once, as markdown with a type field, link concepts together, let any agent read it. Three conformance rules mean you can start with a single concept file and grow the bundle from there.

Thanks for reading! If you have any questions or feedback, please let me know on Medium or LinkedIn

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI