Open Knowledge Format vs RAG: Why Your Agent Should Read a Wiki

Most agent stacks reach for a vector database the moment the model needs a fact it was not trained on. That instinct is reasonable when the answer is buried in years of tickets and leftover wiki pages. It is a strange instinct when the answer is a definition your team already agreed on, wrote down, and still argues about in Slack whenever someone "improves" it.

Take weekly active users. Someone asks the agent how you compute it. You already know the answer lives in a metric doc that points at the orders table and a freshness playbook for the days the warehouse is late. The agent does not know that. If you have wired it the usual way, it never gets a chance to. The docs go into a chunker, the chunker cuts the WAU paragraph away from the schema it depends on, and at query time a retriever returns a few fragments that look related. The model infers the join. Sometimes it gets the join right. Sometimes it counts sign-ins because an onboarding page used the words "active user." You cannot tell, from the fluent paragraph it returns, whether the model reasoned badly or the retriever handed it the wrong slice.

That is retrieval-augmented generation doing the job it was built for, which is search. You have a haystack. You do not know which document matters. You embed the pile, rank by similarity, and let the model stitch something together. The trouble starts when you use that same machinery to store a fact you can already name. Splitting a known definition into chunks and hoping the right slice comes back is wasted work, and it throws away the links between the metric, the table, and the playbook.

In April 2026, Andrej Karpathy wrote down a different pattern. Instead of rediscovering the same facts from raw documents on every question, you keep a wiki the model can read and maintain. When a new source arrives, the model does not just index it. It files the useful parts into pages that already exist, updates the cross-references, and notes where the new material contradicts the old. The knowledge compiles once and stays current. Google Cloud picked that pattern up on 12 June 2026, when Sam McVeety and Amir Hormati published the Open Knowledge Format. OKF is the shared contract for the wiki. It is a format. You do not install it, and you do not need a vector product to use it.

What the folder actually is

An OKF bundle is a directory of markdown files. Each file is one concept, and a concept can be a table, a metric, an API, a policy, or a runbook. The path is the identity. metrics/weekly_active_users.md is both the filename on disk and the address other files use when they point at it.

Every concept file starts with YAML frontmatter. The v0.2 spec requires one field, type. Title, description, tags, and a resource URI are recommended. Everything else is optional, including whatever extra keys your team wants to hang on the document. Concepts link to each other with ordinary markdown links, so the folder is a graph sitting on top of the directory tree. Two reserved names handle navigation. index.md lists a directory so an agent can skim one level without loading the whole bundle into context. log.md is the changelog. You can ship the directory as a git repo, a tarball, or a folder on disk. If you can cat a file, you can read OKF.

Google Cloud’s Knowledge Catalog, the catalog that used to be called Dataplex, can ingest a bundle and serve it to agents. That is one consumer among many. The format does not care whether the reader is Knowledge Catalog, Obsidian, GitHub, MkDocs, or a file-read tool in an agent loop.

A morning question and four files

Suppose you sell a product and someone asks the agent how you compute weekly active users. The bundle that answers that question can be this small.

sales/
  index.md
  tables/orders.md
  metrics/weekly_active_users.md
  playbooks/orders_freshness.md

index.md is the map. The spec keeps frontmatter off index files, except an optional version key at the bundle root.

# Sales

* [Orders](tables/orders.md) - One row per completed customer order.
* [Weekly active users](metrics/weekly_active_users.md) - Unique customers with a delivered order in the last 7 days.
* [Orders freshness](playbooks/orders_freshness.md) - What to do when `orders` lags the SLA.

The metric file states the fact and points at the table it depends on.

---
type: Metric
title: Weekly active users
description: Unique customers with a delivered order in the last 7 days.
tags: [sales, activation]
verified:
  - { by: human:finance@acme, at: 2026-07-01T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
---

# Definition

A weekly active user is a distinct `customer_id` on [orders](/tables/orders.md) with `order_status = 'delivered'` and `order_ts` in the last 7 days.

# Notes

Do not count accounts that only signed in. Activity here means a completed order. If `orders` is late, stop and follow the [freshness playbook](/playbooks/orders_freshness.md).

The table file holds the grain and the join. The playbook holds the triage steps. None of that is buried in a long Confluence page.

The agent reads index.md, opens the metric, follows the link to orders, and only opens the playbook if freshness is in doubt. Path resolution is the traversal. There is no embed step and no ranking step, because the relationships are already written down as links. A foreign key, a metric’s source table, and the runbook that uses both are sitting in the files. Vector retrieval would have flattened those same relationships into disconnected text and asked the model to guess the structure it should have been handed.

Now run the same morning the RAG way. You dump the warehouse docs, the finance policy, and last year's incident notes into a vector store. The splitter cuts the WAU paragraph away from the orders schema and cuts the "delivered only" rule away from the notes sitting two headings down. The retriever returns fragments. The model writes a confident paragraph. If the paragraph is wrong, you have two suspects, the reasoner and the retriever, and no clean way to tell them apart. A direct file read leaves one.

The same files work for people. You can cat them, preview them on GitHub, open them in Obsidian, and run git blame on the day someone changed "active" to mean "signed in." There is no SDK between you and the fact. A stale WAU definition becomes a pull request instead of a silent re-index. Rollback is git revert. Review is the same habit you already have for code.

Cost follows that shape. For a small set of facts the agent reads on almost every task, you skip embeddings, a vector database, and a reranker, and you pay file-read tokens for the concept it actually opens. index.md is how you keep that bill from turning into "load the whole wiki." If you pour thousands of concept files into context you will rebuild the haystack on purpose. The curated core has to stay small, or you have invented a second search problem and called it a knowledge base.

When agents write the wiki

v0.1 was the folder and the links. v0.2, published 24 July 2026, is the part that treats the folder as a knowledge base that machines will keep writing. A page a person wrote comes with an implicit guarantee. You can walk down the hall. Ten thousand concepts minted overnight do not give you that, so the spec puts the trust questions in frontmatter, where a consumer can read them without spending tokens on the body.

The new fields are optional, and their absence means something. An unverified concept is distinguishable from a verified one. sources records what a concept was built from. generated records who wrote the current text and when. verified is a separate list of confirmations, human or machine, and from that list a consumer derives a trust tier of unverified, machine-confirmed, or human-reviewed. status moves a concept through draft, stable, and deprecated. stale_after is an absolute date, so staleness is a comparison you can run in code.

OKF records those signals. It does not compute a credibility score, because a score is subjective, does not travel between consumers, and goes stale the moment you write it down. Whoever reads the bundle decides what the signals are worth.

The other addition is Attested Computation, and it exists for a nastier moment than "where did this sentence come from." An agent reports a dollar figure. Did it produce that number the way finance said it must, or did it invent its own SQL? An attested computation is its own concept. It carries the sanctioned query or API call, the parameters the agent may fill, an executor, and a deterministic attester with no language model in it. The agent supplies values. It does not edit the computation. The executor returns a receipt, and the attester checks that the thing that ran matches the thing on disk. A swapped table name fails the check. That is a different job from retrieving a similar query out of a vector index.

Bare RAG can bolt some of this on as chunk metadata. Every team invents its own schema, and the next consumer has to learn it. OKF writes the fields once so any reader interprets them the same way.

The haystack is still a haystack

OKF does not replace retrieval. Google did not claim that, and the spec is explicit about the jobs it refuses. It does not prescribe storage, serving, or a query engine. It does not swallow OpenAPI or your warehouse catalog. It points at those things.

Use RAG when the corpus is large and you cannot predict which document matters. Support tickets, Slack threads, years of Confluence, and stray PDFs belong in retrieval because you cannot curate what you cannot name, and you should not try to hand-shape a pile that changes faster than you can read it. The hard problem just moves. RAG’s hard problem is retrieval quality. A knowledge base’s hard problem is staleness. If nothing rewrites the file when the warehouse or the finance policy changes, OKF becomes a confident wrong answer. Pick the approach whose hard problem you can actually solve.

Two questions help. Do you already know when this fact changes? Is a wrong answer expensive? If both are yes, curate it. If either is no, retrieve it. Most production agents need both. Named, high-stakes facts go to the bundle. "It's in there somewhere" goes to the vector store. You can even index the bundle, because one-concept markdown makes cleaner chunks than raw source dumps, but the source of truth for weekly active users is still the markdown file, not the index.

The failure mode on the OKF side is over-curation. If you pour everything into the bundle and call it a platform, you get a second unmaintained wiki. A fact earns a concept file when the agent reads it on nearly every task and a wrong answer causes real damage. Everything else stays in retrieval.

Start with the files you already have

You do not need Google Cloud to try this. Put one concept in each file, give it a type, a title, and a one-line description, and link the files the way a human would click through them. Keep the bundle in git. If your docs already live as versioned markdown with stable paths, you are most of the way there. If the same fact lives on three pages with no links between them, no producer can turn that mess into a clean bundle. Fix the docs first.

The spec is short. The repo ships sample bundles for GA4 e-commerce, Stack Overflow, Bitcoin public data, and a fictional retailer named acme_retail, plus a static HTML visualizer that turns any bundle into a graph in one file. Recheck the spec before you treat those names as frozen. The older copy under knowledge-catalog/okf is a snapshot. Build against the current repo.

If you can name the fact, write it down and let the agent read the file. Stop asking a retriever to rediscover it.

Thank You!

Thank you for taking the time to read my article and I hope you found it useful (or at the very least, mildly entertaining). For more great information about web dev, systems administration and cloud computing, please read the Designly Blog. Also, please leave your comments! I love to hear thoughts from my readers.

If you want to support me, please follow me on Spotify or SoundCloud!

Please also feel free to check out my Portfolio Site

Looking for a web developer? I'm available for hire! To inquire, please fill out a contact form.