OKF + RAG: A Hybrid Architecture for Reliable AI Agents

Ask an AI agent a widely known fact and it answers fluently. Ask it for your company's exact churn formula, the schema of an internal API or the runbook for a database failover, and it may produce something that sounds right and is entirely invented. That's the hallucination problem, and it is a major reason enterprises hesitate to hand real work to agents.

The standard response of the last two years has been RAG: connect the model to a vector database of company documents, retrieve whatever looks relevant and paste it into the prompt. For large piles of unstructured text, it works. Its weakness is that it is probabilistic. It returns passages that are semantically similar to the question, which is a different thing from passages that are authoritative. When the question is about the official revenue formula or the contract of a payment endpoint, similar isn't good enough.

In June 2026, Google Cloud introduced the Open Knowledge Format (OKF), a vendor-neutral specification for curated knowledge stored as Markdown files. Combine its exact lookups with RAG's broad reach and you get an architecture worth considering for agents that must be both precise and exploratory.

Two memories

Picture a new hire on their first day. Two things are put in front of them.

The first is a curated internal wiki: canonical definitions, API docs, metric formulas and runbooks, all reviewed, approved and version-controlled. When they need the official answer, they look there. That plays the role of OKF.

The second is a search engine over everything else: thousands of chat messages, email threads, support tickets and meeting transcripts. When they want to know what people said about a topic, or dig through unstructured archives, they search there. That's RAG.

Neither is enough on its own. Together they cover the whole range of what an organization knows.

What OKF is

OKF is deliberately plain. A bundle is a directory of Markdown files kept in Git. Each file describes one concept, such as a table, a metric, an API endpoint or a runbook, and starts with a block of YAML frontmatter for machine-readable metadata. The spec asks very little of producers, and tools like Obsidian, Notion or MkDocs already handle the same file shape. The project lives in a public repository.

A file for a business metric might carry a type, title, description, owner, tags and timestamp in the frontmatter. The body then gives the official formula, a few rules (for instance, exclude trial accounts from the denominator and don't count plan downgrades as churn), the table that serves as the source of truth and links to related concepts.

---
type: metric
title: "Monthly Churn Rate"
description: "Official formula for calculating monthly customer churn."
owner: "data-engineering"
tags: [revenue, kpi, board-report]
timestamp: 2026-06-20T10:00:00Z
---

# Monthly Churn Rate

The official churn rate formula used in all board reports and investor decks:

    Churn Rate = (Customers Lost During Month / Customers at Start of Month) × 100

### Rules
- **Do NOT** use trial accounts in the denominator.
- **Do NOT** count plan downgrades as churn.
- Source of truth: `analytics.monthly_churn_summary` table.

### Related
- [Monthly Active Users](mau.md)
- [Revenue Dashboard](revenue_dashboard.md)

Why bother with this?

• No vector math. When the agent needs the churn formula, it reads that file directly. There's no embedding, no similarity score and no top-k, just the approved answer every time.
• Native to Git workflows. Changes go through pull requests, reviews and commit history, so there's an audit trail showing who changed the formula, when and why.
• No infrastructure. No vector store, embedding pipeline, chunking strategy or re-indexing job. Files in a folder.

What RAG is

RAG connects a model to large, unstructured data in six steps:

1. Ingest documents such as PDFs, emails, wiki pages and chat messages.
2. Chunk them into smaller segments.
3. Embed each chunk as a vector with an embedding model.
4. Store the vectors in a database like Pinecone, Weaviate or pgvector.
5. At query time, embed the question into the same space and fetch the most similar chunks.
6. Add those chunks to the prompt so the model can answer with context.

RAG's strength is reach. It can surface relevant material from thousands of documents that nobody could organize by hand. Its weakness is precision. Because similarity drives retrieval, it can return text that's related without being authoritative. If three different threads define churn slightly differently, RAG may well pick the wrong one.

The hybrid design

The combined architecture puts a router in front of both memories. The router looks at each incoming query and decides where it should go: toward the curated bundle when the question is about an official definition, or toward vector search when it's open-ended and exploratory.

A simplified Python version of that router does four jobs. It loads every Markdown file in the bundle and indexes them by the title in the frontmatter. It tries a deterministic keyword match of the query against those titles. If that finds a concept, the content is passed along labeled as coming from the official knowledge base. Otherwise it falls back to a vector search, labeled as document search, and then sends the chosen context to the model with an instruction to answer only from what it was given. Labeling the source in the prompt matters, since it tells the model, and later the reader, how much weight the context deserves.

from openai import OpenAI
import os
import glob
import yaml

client = OpenAI()

# 1. Load the OKF knowledge bundle from the local directory
def load_okf_bundle(bundle_path: str) -> dict:
    """Reads all Markdown files in the OKF directory into a searchable dict."""
    knowledge = {}
    for filepath in glob.glob(f"{bundle_path}/**/*.md", recursive=True):
        with open(filepath) as f:
            content = f.read()
            # Extract the title from YAML frontmatter
            if content.startswith("---"):
                _, frontmatter, body = content.split("---", 2)
                meta = yaml.safe_load(frontmatter)
                title = meta.get("title", os.path.basename(filepath))
                knowledge[title.lower()] = body.strip()
    return knowledge

# 2. Search OKF (deterministic, keyword-based)
def search_okf(query: str, okf_knowledge: dict) -> str | None:
    """Simple keyword match against OKF titles."""
    for title, content in okf_knowledge.items():
        if title in query.lower():
            return content
    return None

# 3. Search RAG (probabilistic, vector-based)
def search_rag(query: str) -> str:
    """Placeholder for your vector DB search (Pinecone, Weaviate, etc.)."""
    # results = vector_db.similarity_search(query, top_k=5)
    return "RAG context: [retrieved chunks would appear here]"

# 4. The Intelligent Router
def answer_query(query: str, okf_bundle_path: str) -> str:
    okf_knowledge = load_okf_bundle(okf_bundle_path)

    # Try OKF first (deterministic path)
    okf_result = search_okf(query, okf_knowledge)

    if okf_result:
        context = f"[SOURCE: Official Knowledge Base (OKF)]\n{okf_result}"
    else:
        # Fall back to RAG (probabilistic path)
        context = f"[SOURCE: Document Search (RAG)]\n{search_rag(query)}"

    # Send to LLM with the retrieved context
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer using ONLY the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {query}"}
        ]
    )
    return response.choices[0].message.content

The matching here is deliberately crude, a title lookup, to keep the idea visible. A production system would use better routing, such as a classifier or a metadata filter, and would handle the case where both sources return something relevant.

The takeaway

For enterprise agents, it isn't a choice between OKF and RAG. The strongest design uses both. A deterministic, Git-controlled knowledge base protects the facts that must never be wrong: KPIs, API contracts and operational runbooks. A probabilistic vector search covers the large archive of unstructured material no one can curate. The result is an agent that's exact when exactness matters and exploratory when discovery matters.