Open Knowledge Format (OKF): Standardizing Context for AI Agents

As AI agents shift from conversation partners to autonomous engineers, a major architectural challenge has emerged: context fragmentation.

In any enterprise workspace, knowledge is scattered. It lives in database schemas, YAML configs, API definitions, internal wiki pages, source code comments, and runbooks. Feeding this entire corpus to a large language model is impossible due to token limits, cost, and the risk of context dilution. Traditional vector-based Retrieval-Augmented Generation (RAG) is powerful, but it adds indexing overhead, latency, and hosting costs.

To bridge this gap, Google Cloud introduced the Open Knowledge Format (OKF) in June 2026. OKF is a vendor-neutral, open specification designed to standardize how organizational knowledge is stored and served to AI agents. It formalizes a minimalist, directory-based approach—sometimes called the "LLM-wiki" pattern—which optimizes context window usage and enables seamless agent reasoning.

The Design Philosophy of OKF

OKF is built around three core design principles:

Human Legibility: The format does not use binary indexes or proprietary database formats. Knowledge is stored entirely in plain text files using standard Markdown and YAML frontmatter. If a human can read and edit a text file, they can inspect and maintain the agent's knowledge base.
Partial Disclosure Architecture: Rather than dumping a massive repository of information into the context window, OKF structures information into highly modular, decoupled chunks. AI agents navigate the directory structure, dynamically loading only the specific files relevant to their current reasoning step.
Git-Ops Friendly: Because OKF repositories are simple directories of text files, they can be version-controlled in Git. Knowledge updates can be PR-reviewed, tracked, linted, and rolled back using standard developer workflows.

Anatomy of an OKF Document

Each file in an OKF repository represents a single discrete concept (a schema, a runbook, a metric definition, etc.). The files use standard Markdown with a YAML header containing metadata.

Here is an example of an OKF document defining a database schema:

markdown.SNIPPET

---
type: schema
title: Users Table Schema
description: The PostgreSQL database schema for the application's users table.
resource: database.users
tags: [auth, database, schema]
timestamp: 2026-06-25T22:53:00Z
---

# Users Schema

This table tracks authenticated users and their roles.

## Columns

| Column Name | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `id` | UUID | PRIMARY KEY | Unique identifier for each user |
| `email` | VARCHAR(255) | UNIQUE, NOT NULL | Primary login email address |
| `role` | VARCHAR(50) | DEFAULT 'user' | Access control level (admin, user, auditor) |
| `created_at` | TIMESTAMP | DEFAULT NOW() | Timestamp when record was created |

## Relations

- One-to-many relationship with the `sessions` table on `sessions.user_id`.

Under the OKF specification, the only mandatory field in the YAML frontmatter is type. All other fields (such as title, description, resource, and tags) are optional but highly recommended to help agents classify and filter knowledge.

How Agents Traverse OKF Directories

Rather than loading everything upfront, an autonomous agent handles OKF knowledge through a tiered discovery loop.

Index Scan: The agent reads an index.md or scans the directory structure to get a lightweight list of available knowledge files and their types.
Intent Routing: The agent classifies the user's intent (e.g., "Find the user login schema") and maps it to specific files matching the query type or resource identifier (e.g., database.users).
Focused Read: The agent reads only the target files, keeping its active context window minimal, fast, and accurate.

Here is a simple example of how a TypeScript-based agent tool reads and parses OKF files:

TS.SNIPPET

import fs from 'fs';
import path from 'path';
import matter from 'gray-matter'; // Standard YAML frontmatter parser

interface OKFDocument {
  type: string;
  title?: string;
  description?: string;
  content: string;
  metadata: Record<string, any>;
}

export function loadOKFFile(filePath: string): OKFDocument {
  const rawContent = fs.readFileSync(filePath, 'utf-8');
  const { data, content } = matter(rawContent);

  if (!data.type) {
    throw new Error(`Invalid OKF document at ${filePath}: 'type' is required.`);
  }

  return {
    type: data.type,
    title: data.title,
    description: data.description,
    content: content.trim(),
    metadata: data
  };
}

When to Use OKF vs. Vector RAG

OKF is not a replacement for massive-scale semantic searches (such as scanning millions of customer support transcripts). Instead, it excels in scenarios where accuracy, version control, and structure are critical.

Feature	Open Knowledge Format (OKF)	Vector RAG
Best Used For	Structured schemas, developer runbooks, business metrics	Unstructured documentation, large PDFs, chat history
Precision	100% (Direct file-based mapping)	Approximate (Vector similarity scoring)
Verification	Simple Git diff / PR approvals	Complex embedding pipeline validation
Setup Cost	Zero (Standard file directory)	Requires hosting an vector database
Latency	Sub-5ms (Local disk read)	50ms - 200ms (Database roundtrip)

OKF and the Future of Agentic Tooling

By standardizing knowledge representation as a plain-text convention, OKF complements other emerging standards like the Model Context Protocol (MCP). While MCP allows an agent to connect to remote databases or local folders, OKF defines how the files inside those folders should be formatted so that any agent, built on any model, can immediately understand them.

By adopting a simple, vendor-neutral structure, OKF makes context clean, portable, and easily maintainable by both human engineers and autonomous agents.

Open Knowledge Format (OKF): Standardizing Context for AI Agents

The Design Philosophy of OKF

Anatomy of an OKF Document

How Agents Traverse OKF Directories

When to Use OKF vs. Vector RAG

OKF and the Future of Agentic Tooling

Related Research

The Agent Loop: Engineering the Cognitive Heartbeat

The Agent Observability Stack: Tracing Intent, Tools, Policy, and Outcomes

Agent Skills: From Monolithic Tools to Atomic Capabilities

Read more articles