Open Knowledge Format (OKF): Why Google Thinks AI Needs a Git for Knowledge

Most organizations have no shortage of data.

What they lack is accessible knowledge.

Ask an AI model to explain a Kafka topic, troubleshoot a production incident, identify the owner of a dataset, or calculate a business metric, and you’ll quickly discover the real problem:

The knowledge exists, but it’s scattered.

• Some of it lives in Confluence.
• Some in Notion.
• Some in data catalogs.
• Some in Git repositories.
• Some in runbooks.
• And a surprisingly large amount exists only in the heads of senior engineers.

As AI agents become more capable, the biggest bottleneck is no longer model intelligence.

It is context.

To address this problem, Google recently introduced the Open Knowledge Format (OKF) — an open specification designed to make organizational knowledge portable, interoperable, human-readable, and AI-friendly.

At first glance, OKF looks almost too simple.

In reality, it may become one of the foundational building blocks of the AI-native software ecosystem.

Full story for non-members | E-Books on Java/Microservices/Springboot | Whatsapp Group

The Problem: AI Has Intelligence But Lacks Context

Modern foundation models can:

• Generate code
• Analyze datasets
• Summarize documents
• Build applications
• Answer questions

Yet they frequently fail when asked questions specific to your organization:

• What does the order_created Kafka topic contain?
• How is Weekly Active Users calculated?
• Which service owns customer onboarding?
• What is the recovery process when consumer lag exceeds thresholds?
• Which DynamoDB table stores payment transactions?

The information exists.

The problem is that it is fragmented across multiple systems.

According to Google, every AI agent builder today is solving the same context-assembly problem repeatedly because knowledge is distributed across incompatible systems and formats.

As a result:

• Knowledge becomes vendor-locked
• Agent builders reinvent integrations
• Organizations duplicate effort
• AI systems struggle to access institutional knowledge

Google’s Observation: Teams Are Already Building AI Wikis

An interesting pattern has emerged over the last year.

Engineering teams have started creating repositories filled with:

AGENTS.md
CLAUDE.md
README.md
architecture.md
runbooks/
playbooks/

These repositories act as shared memory for AI coding assistants and agents.

Google references the “LLM Wiki” concept popularized by Andrej Karpathy, where knowledge is stored in markdown files that both humans and AI systems can understand.

The pattern works.

The problem is that every implementation is slightly different.

• Different structures.
• Different metadata.
• Different conventions.

None of them are intentionally interoperable.

Google’s answer is simple:

Instead of creating another platform, create a format.

What Is Open Knowledge Format (OKF)?

OKF is an open specification for representing organizational knowledge using:

• Markdown files
• YAML frontmatter
• Standard directory structures
• Standard markdown links

That’s it.

No database.

No proprietary runtime.

No SDK.

No special storage engine.

Google describes OKF as:

A human- and agent-friendly format for representing knowledge, metadata, context, and curated insight surrounding data and systems.

The philosophy behind OKF is refreshingly straightforward:

If you can clone a Git repository, you can consume OKF.

If you can read a markdown file, you can understand OKF.

The Core Structure

An OKF bundle is simply a collection of markdown files organized into directories.

Example:

knowledge/
├── datasets/
│   ├── customers.md
│   └── orders.md
│
├── apis/
│   ├── payment-api.md
│   └── user-api.md
│
├── runbooks/
│   └── kafka-outage.md
│
└── metrics/
    └── weekly-active-users.md

Each file represents a single concept.

The path itself becomes the concept’s identity.

For example:

datasets/orders.md

becomes:

datasets/orders

Anatomy of an OKF Document

Every concept document contains two parts:

1. YAML Frontmatter

---
type: Kafka Topic
title: Order Created Event
description: Published when a new order is successfully created.
resource: kafka://order-created
tags:
  - kafka
  - orders
  - events
timestamp: 2026-06-22T10:00:00Z
---

The only required field is:

type

Everything else is optional.

Google intentionally keeps the format minimally opinionated.

2. Markdown Body

# Purpose

Published by Order Service whenever a new order is created.
# Schema
| Field | Type |
|---------|---------|
| orderId | String |
| userId | String |
| amount | Decimal |
# Consumers
- Payment Service
- Notification Service
# Examples
{
  "orderId": "ORD-123"
}

The body is ordinary markdown.

No proprietary syntax required.

Why This Matters

The most important design decision is that OKF separates:

Knowledge Producers From Knowledge Consumers

A producer may be:

• Human authors
• Metadata catalog exports
• Documentation generators
• AI enrichment agents

A consumer may be:

• AI assistants
• Search engines
• Visualizers
• Developer portals
• Knowledge graphs

Neither side needs to know how the other works.

The format becomes the contract.

Example: A Spring Boot Microservices Platform

Imagine a system containing:

• User Service
• Order Service
• Payment Service
• Notification Service
• Kafka
• DynamoDB
• AWS infrastructure

Today, documentation might be scattered across:

Confluence
Jira
GitHub
Slack
Runbooks
Architecture diagrams

With OKF:

knowledge/

services/
├── user-service.md
├── order-service.md
├── payment-service.md
kafka/
├── order-created.md
├── payment-completed.md
runbooks/
├── consumer-lag.md
├── payment-failure.md
aws/
├── dynamodb-orders.md
├── eventbridge.md

Now an AI agent can answer questions such as:

• Which service publishes Order Created events?
• What happens if payment processing fails?
• Which DynamoDB table stores orders?
• How do we recover from Kafka consumer lag?

without requiring custom integrations into multiple enterprise systems.

Three Design Principles Behind OKF

Google’s specification is built around three important principles.

1. Minimally Opinionated

The specification standardizes only a small interoperability surface.

It does not dictate:

• Taxonomies
• Business domains
• Knowledge models
• Storage systems

Organizations remain free to model knowledge however they choose.

2. Producer and Consumer Independence

Knowledge creators and knowledge consumers evolve independently.

A knowledge bundle created by:

• Humans
• Metadata systems
• LLMs

can be consumed by:

• Other LLMs
• Search systems
• Visualization tools
• Future AI agents

without modification.

3. Format, Not Platform

This may be the most important principle.

Google explicitly positions OKF as:

A format, not a service.

The specification is:

• Open
• Vendor-neutral
• Tool-independent
• Cloud-independent

The value comes from adoption rather than ownership.

The Missing Layer in the AI Stack

Many people compare OKF with MCP (Model Context Protocol).

They solve different problems.

MCP standardizes:

Agent → Tool

Examples:

• Databases
• GitHub
• AWS
• Jira

OKF standardizes:

Knowledge → Agent

Examples:

• Runbooks
• Data catalogs
• Metrics
• APIs
• Architecture

A useful mental model is:

MCP = Actions

OKF = Context

Future AI systems will likely require both.

What Google Is Shipping Alongside OKF

To help organizations adopt the format, Google has released:

Reference Enrichment Agent

An agent capable of:

• Scanning BigQuery datasets
• Creating OKF concept documents
• Enriching metadata
• Adding citations and relationships

Static Visualizer

A browser-based visualization tool that converts an OKF bundle into an interactive graph.

Sample Knowledge Bundles

Including examples built from:

• Google Analytics 4 datasets
• Stack Overflow datasets
• Bitcoin public datasets

These examples demonstrate how large knowledge collections can be represented using the specification.

Link to github — https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf

Why Developers Should Pay Attention

Every major shift in software engineering eventually gets standardized.

We already have:

Git          → Source Code
OpenAPI      → APIs
Dockerfile   → Containers
Terraform    → Infrastructure
Kubernetes   → Deployments

But we still lack a universal format for organizational knowledge.

Today every company stores knowledge differently.

Tomorrow organizations may exchange knowledge bundles the same way they exchange source code.

That is the opportunity OKF is targeting.

My Take

The brilliance of OKF is not in its complexity.

It is in its simplicity.

Google could have introduced:

• A new database
• A new catalog
• A new graph engine
• A new AI platform

Instead, they chose markdown files and YAML.

That decision dramatically lowers adoption barriers.

Whether OKF becomes the industry standard remains to be seen.

But the problem it addresses is real.

As AI agents become part of daily engineering workflows, organizations will need a portable, structured, AI-friendly representation of knowledge.

OKF may end up becoming what OpenAPI became for APIs:

A common language that allows knowledge to move freely between tools, organizations, and AI systems.

And if that happens, future repositories may contain not only source code but also a dedicated knowledge layer sitting beside it:

src/
tests/
docs/
knowledge/

The organizations that build this layer first will likely gain the greatest advantage from the next generation of AI agents.

References

1. Google Cloud Blog — Introducing the Open Knowledge Format https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
2. Open Knowledge Format (OKF) Specification v0.1 https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
3. Google Cloud Knowledge Catalog Repository https://github.com/GoogleCloudPlatform/knowledge-catalog