Markdown files an agent can trust --- an introduction to LLM Wiki and the Open Knowledge Format

2026-08-01· 8 min read· series Agent-Ready Knowledge

Before we start, here is a complete, valid knowledge file. It belongs to a fictional retailer’s returns desk.

---
type: procedure
title: Return an item without a receipt
description: Steps for a return when the customer has no receipt. Store credit only.
tags: [returns, no-receipt, store-credit]
status: draft
generated: { by: wiki_agent/example-model, at: 2026-07-28T14:00:00Z }
sources:
  - resource: https://intranet.example.com/returns-policy-2026.pdf
    author: human:ops-lead
---

1. Ask for photo ID and scan the item tag.
2. If the item is inside the [return window](../policies/return-window.md), issue store credit.
3. If it is outside the window, decline and offer a repair quote.

In summary : a short header, a short body, and one link to another file. The spec that defines the format puts it this way : “If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.”

In this post I want to explain two things I kept thinking about while researching how a small agent should get its knowledge : the LLM Wiki pattern and the Open Knowledge Format (OKF).

Goal

Explain LLM Wiki and OKF in plain terms.
Show how little machinery a curated-knowledge agent needs.

Working assumption

You know what an LLM agent is, you have met RAG (retrieval-augmented generation), and you have not read the spec or the gist. I am also assuming an agent with a narrow job. That assumption matters when I get to where this fits.

The artifact, annotated

The file above is a concept : one idea per file. Reading it top to bottom :

type : the only required field. You choose the vocabulary (procedure, policy, glossary).
title, description, tags : recommended. The description is what an agent reads to decide whether the file is worth opening.
status, generated, sources : optional. Where the page is in its life, what wrote it, and what it was written from.
The body : plain Markdown. The link to return-window.md is the map.

Around it sits a bundle, which is just a folder :

bundle/
  index.md                      # table of contents, one line per item
  log.md                        # what changed, and when
  returns/
    index.md
    return-without-receipt.md
    return-online-order.md
  policies/
    index.md
    return-window.md

Where this came from : a pattern, then a format

LLM Wiki (April 2026). Andrej Karpathy published a gist describing a set of interlinked Markdown files that an LLM builds and maintains. His complaint about the usual document setup is that the model “is rediscovering knowledge from scratch on every question.” The pattern has three layers and three jobs :

Raw sources : documents you curate. The model reads them and never edits them.
The wiki : Markdown pages the model writes and keeps current.
The schema : an instruction file (in the style of CLAUDE.md or AGENTS.md) that tells the model how the wiki is organized.
The jobs : ingest a new source, query the wiki, and lint it for contradictions, stale claims and orphan pages.

OKF (June 2026). Two Google Cloud tech leads, Sam McVeety and Amir Hormati, published a format, not a platform. Their framing : “What’s missing is a format, not another service.” The post points to Karpathy’s gist as the clearest statement of the idea, and calls v0.1 a starting point, not a finished standard. A second version followed in July. It added ways for a page to say where it came from and whether anyone has checked it.

LLM Wiki in practice

The pattern splits the work between a person and a model.

Who	Does what
The person	Chooses the sources, reviews the pages, tunes the schema
The model	Summarizes, cross-links, updates, lints

The difference from RAG is when the work happens. RAG re-derives an answer from raw chunks on every question. A wiki compiles the knowledge once and keeps it current (though I’m starting to wonder if caching changes this difference).

There are also the following aspects :

Scale. The gist reports this working well at moderate scale : roughly a hundred sources and hundreds of pages. Not millions.
The main risk. If the model writes a wrong page, every later answer inherits it. Review and linting carry real weight here.

This could be helpful for an intermediate AI builder, who might have little time and resources for database runtimes, and simply needs to curate knowledge for a focused agent.

OKF in plain terms

What it is. A folder of Markdown files. Each file describes one thing and starts with a short header. Links between files form the map, index.md files act as a table of contents an agent can walk through level by level, and log.md says what changed. The spec adds very little else, on purpose.

What v0.2 added. Five optional fields : sources, generated, verified, stale_after and status. Together they let a page say what it was written from, who or what wrote it, who checked it, and whether it is still current. In my read, this is the part that matters most once agents start writing the files.

What it leaves out. Storage, serving and query infrastructure are stated non-goals. The format also does not decide whether the content is right. A file can be perfectly valid and wrong.

Everything else is in the spec and the repository, which also holds sample bundles and a reference agent.

How an agent uses a bundle

The spec does not define retrieval. In practice I see three patterns :

Load it into context. Works for a small bundle. Costs tokens on every turn.
Navigate. Read the index, follow links, read the concept. Cheap, and it depends on good descriptions.
Look up through tools. A few functions the agent can call : list the index, search, read a concept. The search can be plain keyword matching, or vectors if you add them. The format does not care.

Which one fits depends mostly on the size of the bundle and on how well its descriptions are written.

Why a small ADK agent and a bundle fit together

In this case I used Google’s Agent Development Kit (ADK). An ADK agent is a model, an instruction and a list of tools, and a tool is a plain Python function. Here is the whole agent for the returns bundle :

from pathlib import Path
from google.adk.agents import Agent

BUNDLE = Path(__file__).parent / "bundle"

def _safe(path: str) -> Path:
    p = (BUNDLE / path).resolve()
    if BUNDLE.resolve() not in p.parents or p.suffix != ".md":
        raise ValueError("outside the bundle")
    return p

def list_index(folder: str = "") -> str:
    """Return the index.md for a folder. Start with the bundle root."""
    try:
        return _safe(str(Path(folder) / "index.md")).read_text()
    except Exception:
        return "No index found for that folder."

def search(words: str) -> list[str]:
    """Return paths of concepts whose text contains every word."""
    terms = words.lower().split()
    return [str(f.relative_to(BUNDLE)) for f in sorted(BUNDLE.rglob("*.md"))
            if f.name not in ("index.md", "log.md")
            and all(t in f.read_text().lower() for t in terms)][:5]

def read_concept(path: str) -> str:
    """Return one concept file, header included."""
    try:
        return _safe(path).read_text()[:8000]
    except Exception:
        return "That concept could not be read."

root_agent = Agent(
    name="returns_helper",
    model="gemini-2.5-flash",
    instruction=(
        "Answer only from the bundle. Start at the index, follow links, "
        "read the concept, and cite its path. If a concept has no "
        "`verified` field, say the answer is unverified. If the bundle "
        "does not cover the question, say so."
    ),
    tools=[list_index, search, read_concept],
)

What I like about this shape :

The knowledge ships with the agent. Same repository, same pull requests, diffable. No database to run.
The whole knowledge surface is three functions and an instruction. That is small enough to read in one sitting.
Trust fields can shape behavior. The instruction tells the agent to say when an answer rests on unverified content.
Guardrails are ordinary code. _safe confines paths to the bundle and serves only Markdown. Responses are capped, and a failed tool returns a safe message.

If you want to run it yourself, the bundle and the agent are in this zip file.

Where it fits, and where it does not

Fits : a narrow agent, knowledge that someone owns, and procedural or reference content shaped like tasks.
Does not fit by itself : very large corpora nobody can curate, and fuzzy questions across thousands of documents. The format records trust signals, but it does not settle contradictions between pages.
Maturity : the spec is v0.x and small on purpose. Expect change.

What I take from it, as a practitioner

Even if you never use Google’s tooling, the format is a good house style for agent knowledge : typed concept files, an index per folder, a change log, and a note on where each page came from.

One practical lesson : add the trust fields early. Adding them later means going back through every file. In this case that is a design lesson, not a verdict on the format.

Risk or limitation (for now)

I read the spec at v0.2, the current version as I write this. It will move.
I have not benchmarked OKF against anything.
The returns agent is a toy. It shows the shape, not the quality.