A Standard for AI Agent Context

The Context Problem in Agentic Systems

In the current era of generative AI, the primary bottleneck for enterprise adoption is no longer the model’s raw intelligence, but its lack of relevant, internal context. While foundation models excel at general reasoning, they operate in a vacuum without specific organizational knowledge. To address this, Google Cloud provides the Knowledge Catalog (formerly Dataplex), an AI-powered platform designed to provide semantics and business context to agents. However, the industry at large still struggles with a “fragmented context landscape.”

Essential “atoms of knowledge” are typically scattered across three incompatible surfaces:

• Metadata Catalogs: Technical schemas locked behind proprietary APIs.
• Wikis and Shared Drives: Unstructured documents designed for human consumption, often disconnected from the systems they describe.
• Code and Comments: Documentation embedded in docstrings and notebook cells, or siloed in the minds of senior engineers.

Currently, every AI architect must solve the context-assembly problem from scratch. This leads to “bespoke” solutions where knowledge is trapped in silos, forcing developers to reinvent data models and preventing interoperability across the agentic ecosystem.

Core Philosophy: Knowledge as a Living Wiki

The Open Knowledge Format (OKF) addresses these challenges by formalizing the “LLM-wiki pattern” into a portable, interoperable format. This philosophy is rooted in an insight from AI researcher Andrej Karpathy: LLMs are uniquely suited for maintaining their own documentation.

The traditional “Knowledge Rot” seen in enterprise wikis occurs because humans find the “bookkeeping” of cross-referencing and updates to be tedious drudgery. LLMs, conversely, do not get bored; they can update dozens of cross-linked files in a single pass. OKF v0.1 is a vendor-neutral open specification designed to solve this maintenance problem through three core principles:

1. Minimally Opinionated: OKF requires only a type field. It defines the interoperability surface, not the specific content model, allowing producers to define their own sections.
2. Producer/Consumer Independence: The format is the contract. Whether a bundle is hand-authored by a human or synthesized by an automated pipeline, any OKF-compliant agent can consume it.
3. Format—Not Platform: OKF is not tied to a specific cloud, database, or SDK. It is designed to survive transitions between different models and infrastructure providers.

The Bundle Architecture: How OKF Works

An OKF Bundle is a directory of Markdown files where each file represents a “concept” (e.g., a table, metric, API, or runbook). Crucially, the directory path acts as the concept’s identity (e.g., sales/tables/orders.md).

Sample Directory Structure:

sales/
├── index.md
├── datasets/
│ ├── index.md
│ └── orders_db.md
├── tables/
│ ├── index.md
│ ├── orders.md
│ └── customers.md
└── metrics/
    ├── index.md
    └── weekly_active_users.md

The Anatomy of a Concept File

Each file uses YAML frontmatter for queryable metadata and a Markdown body for descriptive content. Concepts link to one another using standard Markdown syntax, transforming the directory into a traversable knowledge graph.

---

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, revenue] timestamp: 2026-05-28T14:30:00Z

---

Schema

Column	Type	Description
order_id	STRING	Globally unique order identifier.
customer_id	STRING	FK to customers.

Joins

Joined with customers on customer_id.

Related Concepts

• Customers
• Weekly Active Users

To support agent navigation, OKF utilizes reserved filenames:

• index.md: Enables “progressive disclosure,” allowing an agent to understand a directory’s contents before deep-diving.
• log.md: Provides a chronological history of changes to the knowledge base.

Implementation: From Static Files to Automated Pipelines

Architects can implement OKF via two primary paths:

1. Manual/Static Creation: Hand-authoring files for “Source of Truth” documentation like business playbooks.
2. Automated Generation: Using the enrich command to automatically extract metadata from systems like BigQuery and convert them into bundles.

Reference Implementation Components:

Component	File Location	Role
enrich command	src/reference_agent/tools/bundle_tools.py	Handles data extraction and frontmatter formatting.
synthesizer.py	src/reference_agent/bundle/synthesizer.py	Uses LLMs to generate one-sentence index descriptions.
index.py	src/reference_agent/bundle/index.py	Scans directories to generate index.md files automatically.
visualizer	src/reference_agent/viewer/generator.py	Generates a static HTML graph for human/architect review.

Comparative Analysis: Why OKF is Not Just RAG or Prompting

In AI strategy, we distinguish between “Brain” (Knowledge) and “Skills” (Tools/APIs). While Prompting and RAG act as sensory inputs, OKF serves as the Knowledge Graph (Mental Map).

The difference is best summarized by the following verdict: You use OKF when you want the AI to behave like an expert employee who knows your business, rather than a smart intern who just has access to your files.

Dimension Standard Prompting RAG Open Knowledge Format (OKF) Discovery Parametric: Relies on model weights. List-based: Retrieves a blob of data. Graph-based: Navigates via explicit cross-links. Persistence Ephemeral: Context lost after the turn. Ephemeral: Retrieval is per-query. State Machine: Persistent, version-controlled layer. Logic Internal: Limited to training data. Sensory: Raw data requires interpretation. Mental Map: Pre-structured concepts and logic.

OKF is superior for Complex Reasoning and Multi-step Workflows because it allows the agent to track state and navigate relationships that list-based retrieval (RAG) often misses.

Getting Started and the Future of OKF

The reference implementations currently provide an enrichment agent, a static visualizer, and sample bundles to jumpstart development. To adopt OKF, we recommend the following four actions:

1. Read the SPEC.md: Understand the core conformance criteria.
2. Write a Producer: Create a script to export your internal knowledge into the OKF structure.
3. Write a Consumer: Build an agent or search index that reasons over OKF bundles.
4. Try the Reference Implementation: Run the provided tools against your own data.

The vision for OKF is to serve as the “Lingua Franca” of AI context—a persistent knowledge layer that remains valuable even as underlying models or tools evolve.

Resources and Community

• Google Cloud Knowledge Catalog Tools GitHub
• OKF Specification (SPEC.md)
• Sample Bundles:
  • GA4 E-commerce
  • Stack Overflow Public Dataset
  • Bitcoin Blockchain Data

We welcome open-source contributions, alternative implementations, and adoption across all platforms to build a truly vendor-neutral ecosystem for AI knowledge.