Back to Journal
•4 min read

Pragmatic RAG: Testing Google's Open Knowledge Format (OKF)

Vector embeddings alone don't solve the context-assembly problem for AI agents. Here is how I structured a repository's documentation as a navigable markdown graph using Google's OKF spec.

Google CloudAI AgentsRAGMarkdown
Pragmatic RAG: Testing Google's Open Knowledge Format (OKF)

If you’ve built or integrated LLM agents inside a real-world codebase, you've likely hit the limits of naive vector search.

You ask an agent to refactor an API endpoint, and it retrieves the endpoint function body via vector lookup. But it misses the database schema, the authentication middleware logic, and the deployment runbook because they didn't share enough semantic overlap in the embedding space to pass the retrieval threshold.

The agent fails because it is operating in a context vacuum.

To solve this "context-assembly" problem, Google Cloud published the Open Knowledge Format (OKF) specification. It's a vendor-neutral standard for turning a flat directory of text files into a semantic knowledge graph that AI agents can navigate recursively.

Here is how it works under the hood, and my practical take on implementing it.

The Concept: What is OKF?

OKF formalizes what many platform teams were already doing: structuring internal documentation as a clean directory tree of plain Markdown files with YAML frontmatter.

Instead of introducing proprietary graph databases or complex vector indexing pipelines, OKF relies on two web standards:

  1. YAML Frontmatter for file-level metadata (declaring what a file is).
  2. Standard Markdown Links to declare relationships between files (pointing the agent to the next node).

By linking files directly inside the text, you turn your documentation directory into a knowledge graph. Any LLM agent parsing a file can follow these links exactly like a web crawler traverses HTML anchors.

A Concrete Example

In a shared UI component library or design system repository, you might structure your OKF knowledge base like this:

/knowledge-base
  ├── components/
  │   └── interactive-modal.md
  ├── compliance/
  │   └── wcag-checklist.md
  └── tokens/
      └── theme-palette.md

Using OKF, each of these files starts with a minimal frontmatter block. The spec is lightweight; the only strictly required field is type.

Here is the YAML header for interactive-modal.md:

---
type: "ui-component"
title: "Interactive Modal Dialog"
description: "Accessibility-compliant overlay specification supporting dynamic focus trapping and theme tokens."
timestamp: "2026-07-06T12:00:00Z"
tags: ["react", "wcag", "accessibility", "design-system"]
---

And inside the markdown content, we define explicit relationships to other documents using standard relative links:

The Modal component manages overlays and traps keyboard focus internally. 
For semantic HTML and ARIA attribute rules, refer to the [WCAG AA Compliance Checklist](../compliance/wcag-checklist.md).
To style backdrop filters and component states, import design tokens from the [Theme Palette Config](../tokens/theme-palette.md).

How Agents Traverse the Graph

Traditional RAG searches for keywords or semantic vectors, fetching the top 5 chunks and dumping them in the prompt.

OKF allows a traversal RAG strategy:

  1. Entry Point Selection: The agent runs a lightweight vector search or keyword query to find the initial relevant document (e.g., interactive-modal.md).
  2. Recursive Parsing: The agent parses the document, reads the YAML header to identify the document type, and extracts all relative links.
  3. Context Assembly: Depending on the task (e.g., refactoring the modal for a new dark mode layout), the agent recursively loads the linked files (fetching the WCAG guidelines and design tokens config) to build a complete dependency context before writing any React code.

This eliminates context window overflow because the agent only pulls in files that are explicitly relevant, completely bypassing generic search noise.

The Trade-offs: Is it Worth It?

Like any standard, OKF isn't a silver bullet. Here is my honest assessment:

The Wins:

  • Zero Vendor Lock-in: It is just Markdown. You can view it in VS Code, host it on GitHub, or index it with any LLM provider (Gemini, Claude, OpenAI).
  • Git-Compatible Versioning: Because the knowledge base lives in the repository, documentation updates go through standard Pull Requests and merge reviews.
  • Agent Independence: Agents don't need a custom database driver; they just need a markdown parser.

The Gotchas:

  • Link Rot: As files get renamed or moved, relative markdown links break. You need to run a linter (like markdown-link-check) in your CI pipeline to catch broken links before they reach production.
  • Maintenance Overhead: Engineers must commit to updating YAML headers and links alongside code changes, or the graph quickly becomes stale.

OKF is a pragmatic approach to context assembly. If you are struggling with hallucinations or incomplete agent context, structuring your repository's /docs or /knowledge directory to match OKF is a low-cost, high-return architecture decision.

Share this article