{"slug": "open-knowledge-format-vs-rag-why-your-agent-should-read-a-wiki", "title": "Open Knowledge Format vs RAG: Why Your Agent Should Read a Wiki", "summary": "Google Cloud and Andrej Karpathy have proposed a new pattern for AI agents that replaces retrieval-augmented generation with a wiki-like knowledge base stored in markdown files. The Open Knowledge Format (OKF), published by Google Cloud in June 2026, defines a directory of concept files that agents can read and maintain, preserving links between metrics, tables, and playbooks. This approach aims to avoid the errors caused by chunking and similarity search in RAG when answering questions about known facts.", "body_md": "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.\n\nTake 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`\n\ntable 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.\n\nThat 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.\n\nIn April 2026, [Andrej Karpathy](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 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](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing). 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.\n\nAn 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`\n\nis both the filename on disk and the address other files use when they point at it.\n\nEvery concept file starts with YAML frontmatter. The [v0.2 spec](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) requires one field, `type`\n\n. Title, description, tags, and a `resource`\n\nURI 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`\n\nlists a directory so an agent can skim one level without loading the whole bundle into context. `log.md`\n\nis the changelog. You can ship the directory as a git repo, a tarball, or a folder on disk. If you can `cat`\n\na file, you can read OKF.\n\nGoogle Cloud’s Knowledge Catalog, the catalog that used to be called Dataplex, can ingest a bundle and [serve it to agents](https://docs.cloud.google.com/dataplex/docs/ai-overview). 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.\n\nSuppose 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.\n\n```\nsales/\n  index.md\n  tables/orders.md\n  metrics/weekly_active_users.md\n  playbooks/orders_freshness.md\n```\n\n`index.md`\n\nis the map. The spec keeps frontmatter off index files, except an optional version key at the bundle root.\n\n```\n# Sales\n\n* [Orders](tables/orders.md) - One row per completed customer order.\n* [Weekly active users](metrics/weekly_active_users.md) - Unique customers with a delivered order in the last 7 days.\n* [Orders freshness](playbooks/orders_freshness.md) - What to do when `orders` lags the SLA.\n```\n\nThe metric file states the fact and points at the table it depends on.\n\n```\n---\ntype: Metric\ntitle: \"Weekly active users\"\ndescription: \"Unique customers with a delivered order in the last 7 days.\"\ntags: [sales, activation]\nverified:\n  - { by: human:finance@acme, at: 2026-07-01T09:00:00Z }\nstale_after: 2026-12-31T00:00:00Z\n---\n\n# Definition\n\nA 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.\n\n# Notes\n\nDo 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).\n```\n\nThe table file holds the grain and the join. The playbook holds the triage steps. None of that is buried in a long Confluence page.\n\nThe agent reads `index.md`\n\n, opens the metric, follows the link to `orders`\n\n, 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.\n\nNow 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`\n\nschema 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.\n\nThe same files work for people. You can `cat`\n\nthem, preview them on GitHub, open them in Obsidian, and run `git blame`\n\non 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`\n\n. Review is the same habit you already have for code.\n\nCost 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`\n\nis 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.\n\nv0.1 was the folder and the links. [v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals), 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.\n\nThe new fields are optional, and their absence means something. An unverified concept is distinguishable from a verified one. `sources`\n\nrecords what a concept was built from. `generated`\n\nrecords who wrote the current text and when. `verified`\n\nis 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`\n\nmoves a concept through draft, stable, and deprecated. `stale_after`\n\nis an absolute date, so staleness is a comparison you can run in code.\n\nOKF 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.\n\nThe other addition is `Attested Computation`\n\n, 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.\n\nBare 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.\n\nOKF 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.\n\nUse 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.\n\nTwo 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.\n\nThe 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.\n\nYou do not need Google Cloud to try this. Put one concept in each file, give it a `type`\n\n, 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.\n\nThe 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](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) before you treat those names as frozen. The older copy under `knowledge-catalog/okf`\n\nis a snapshot. Build against the current repo.\n\nIf you can name the fact, write it down and let the agent read the file. Stop asking a retriever to rediscover it.\n\nThank 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](https://blog.designly.biz). Also, please leave your comments! I love to hear thoughts from my readers.\n\nIf you want to support me, please follow me on [Spotify](https://open.spotify.com/album/2fq9S51ULwPmRM6EdCJAaJ?si=USeZDsmYSKSaGpcrSJJsGg) or [SoundCloud](https://soundcloud.com/jaysudo1/tracks)!\n\nPlease also feel free to check out my [Portfolio Site](https://jay.yaa.bz)\n\nLooking for a web developer? I'm available for hire! To inquire, please fill out a [contact form](https://designly.biz/contact).\n\n*This story was originally published at blog.designly.biz on August 22, 2026.*", "url": "https://wpnews.pro/news/open-knowledge-format-vs-rag-why-your-agent-should-read-a-wiki", "canonical_source": "https://dev.to/designly/open-knowledge-format-vs-rag-why-your-agent-should-read-a-wiki-4kb1", "published_at": "2026-08-23 02:47:11+00:00", "updated_at": "2026-08-23 03:13:14.367496+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "ai-infrastructure", "developer-tools"], "entities": ["Google Cloud", "Andrej Karpathy", "Open Knowledge Format", "Sam McVeety", "Amir Hormati", "Knowledge Catalog", "Dataplex"], "alternates": {"html": "https://wpnews.pro/news/open-knowledge-format-vs-rag-why-your-agent-should-read-a-wiki", "markdown": "https://wpnews.pro/news/open-knowledge-format-vs-rag-why-your-agent-should-read-a-wiki.md", "text": "https://wpnews.pro/news/open-knowledge-format-vs-rag-why-your-agent-should-read-a-wiki.txt", "jsonld": "https://wpnews.pro/news/open-knowledge-format-vs-rag-why-your-agent-should-read-a-wiki.jsonld"}}