Your AI Agent Doesn't Need More Context. It Needs a Brain It Can Trust

Imagine a pager going off at 02:14. You open the runbook and it looks wonderful, with numbered steps, a diagram, clear signs that someone cared. You follow step 4 and it fails. At the bottom of the page you spot the last-edited date: fourteen months ago.

Every sentence in it was correct on the day it was written. But there was no signal anywhere that it had expired.

That is the real bug. It isn't missing docs or bad docs. It's docs that look just as trustworthy on their worst day as on their first. For forty years software shipped under the rule that documentation is prose and the reader judges it. Then repositories were handed to agents that can't judge anything and that read every word with total confidence.

What changed

An AI agent has no memory of its own. It is stateless, and on every turn the whole conversation is sent again from the start. Anthropic's documentation puts it bluntly: send the full conversation history each time.

So a 4,000-token architecture doc pasted into the file an agent always loads isn't read once. In a forty-turn session it's read forty times. And loading it can make the agent worse.

Chroma's context-rot research tested 18 frontier models, among them GPT, Claude, Gemini and Qwen, and reported that accuracy drops as the input gets longer, in some cases from 95% down to 60%. The part that should change your habits is that this isn't a near-the-limit effect. Degradation showed up at every length step they measured. If those findings hold, even a million-token window starts to suffer at fifty thousand, because the enemy is noise and not capacity.

Anthropic describes this as an attention budget: context is a finite resource with diminishing marginal returns, and the aim is the smallest possible set of high-signal tokens. That leaves two bad options.

• Load everything. The agent knows the system but is measurably duller on every task, and each doc edit invalidates the whole prompt cache and re-bills it.
• Load nothing. The agent stays sharp but knows nothing, so it improvises. It makes up a deploy step, or runs a command that was retired back in March.

Teams pick one, feel the pain, and swing to the other. That's roughly where the industry sits today.

A one-sentence diagnosis already exists

In April 2026 Andrej Karpathy published a short gist he called an idea file. It wasn't a product or a library. It sketched one approach: the model digests raw material into a tidy, structured Markdown wiki, and from then on questions go to that wiki instead of the originals.

The line in it that matters has nothing to do with AI: humans abandon wikis because the maintenance burden grows faster than the value.

Anyone who has watched a Confluence space die will recognise that. People didn't quit because writing was hard. They quit because upkeep was hard, and upkeep is mostly clerical: refresh the link, update the summary, flag that this page now contradicts that one, fix the index. That is exactly the work that stopped being expensive, because an LLM doesn't get bored, doesn't forget a cross-reference, and can touch fifteen files in one pass. His division of labour is brief: you read it, the LLM writes it.

The gist spread quickly. Two months later Google Cloud released a specification that, by its own announcement, formalises the LLM-wiki pattern into a portable, interoperable format. The diagnosis underneath is still Karpathy's, and it's why any of this works now and didn't in 2019.

OKF in half a minute

OKF, the Open Knowledge Format, was published by Google Cloud's Data Cloud team in June 2026 as a draft (v0.2) and is explicitly a formalisation of that pattern. Technically it's a directory of Markdown files with YAML frontmatter, and that's all.

The spec sums up its pitch like this: anything that can cat a file can read OKF, and anyone able to git clone a repository can distribute it.

Only one field is mandatory: type. A file with nothing but type already counts as conformant. No schema registry, no database, no embedding pipeline, no vendor lock, no SDK is involved.

okf/
  index.md                  ← table of contents
  billing/
    index.md
    invoice-retries.md      ← one file, one answerable question
  flows/
    customer-offboarding.md

If your reaction is "so, a folder of Markdown," that's accurate. The format isn't the interesting part, and a fair objection is that a folder doesn't need a specification. Google's announcement has an answer: Karpathy's wiki, a team's wiki and a vendor's catalog export may all look alike, with Markdown, frontmatter and cross-links, but none was designed to cooperate. That is the whole case for a spec. Everyone converged on one shape independently, which usually means the shape is right, and then each implementation invented its own field names. A format turns several private conventions into one thing an agent can read anywhere.

The core idea: documentation becomes state

Here's a sample document:

---
type: Playbook
title: Invoice retry policy
status: stable                      # draft | stable | deprecated
stale_after: 2026-11-01             # stale when today >= this date
generated: { by: "human:dana", at: 2026-08-10 }
verified:  [{ by: "human:sam",  at: 2026-08-11 }]
sources:
  - resource: services/billing/retry.go
    last_modified: 2026-07-15
not:
  - term: "restart the worker to clear the queue"
    why: "in-flight jobs are lost, they are not re-queued"
    instead: "drain first, then restart"
---

Five of the fields shown come from the specification. The sixth is the most valuable, and it comes up again below.

A filing cabinet simply stores documents. A brain also knows what it holds, how confident it is and which mistakes taught it something. The pieces below map onto that:

Now read that frontmatter as a machine would. stale_after is an expiry date. It isn't a "last updated" stamp that people have to interpret. It's an absolute date, which turns staleness into a plain comparison, today >= stale_after. Anything can run that check: the agent reading the file, a scheduled job, your CI.

Pause on that. Documentation rot has been a cultural problem since wikis were invented. Nagging, doc days, quarterly audits, plus a "Documentation Standards" page that has itself gone stale. It all runs on social pressure, and none of it can be enforced. With stale_after, rot becomes a failing test, the same category as a broken build. It passes or it doesn't, and nobody has to feel bad.

Other fields work the same way. sources lists the code paths a document describes, so a script can finally answer a question wikis never could: this pull request changed a file that three documents claim to explain, so did anyone update them? verified records who confirmed a document, separately from who wrote it, because, in the spec's words, whoever wrote a concept needn't be whoever confirmed it. A draft by an agent and a sign-off from a senior engineer are two separate events, a distinction most documentation tools never record. Trust tiers are derived from the actor prefix and not stored, since a stored score is subjective, unportable across consumers and goes stale.

status: deprecated lets you keep an old definition instead of deleting it. When two dashboards disagree about "revenue," the cause often isn't bad data. It's two definitions, one quietly replaced, neither labelled. Keep both, mark one, and last quarter's numbers still reproduce.

That's the shift: not a nicer format for prose but prose plus queryable state. Docs can be interrogated, tested and failed.

The token arithmetic

These figures were measured against Google's published example bundle, so they can be checked:

Following one fact end to end costs about 950 tokens, charged only on prompts that need it. The always-on part is tier 0: sixty tokens, one sentence.

Compare it with the typical approach: a guide of 1,600 tokens injected into every prompt although perhaps one prompt in ten needs it. The knowledge is the same, the average bill is around a tenth, and the document is free to grow, because extra length no longer weighs on unrelated conversations in the repo. The spec built index.md around that goal and gives it a name, progressive disclosure: look at what exists first and open documents afterwards.

What OKF isn't

OKF doesn't work as a guardrail. A Markdown file can't prevent an agent from running something destructive. Actual enforcement has to be code, such as deny-lists and pre-execution hooks that block an action no matter what the model chose. Whatever else you remember, don't conclude that having written the danger down means you're protected.

What OKF really gives you is an agent that knows. The spec additionally defines an Attested Computation type in which an agent can pass parameters but must never write or modify the computation itself, which is about as close as it gets to forbidding a rewrite of the safety check. Keep an eye on it, but don't build on it yet: the spec says that interface is explicitly deferred to a later revision.

Remember too that this is a draft. The jump from v0.1 to v0.2 already renamed two constructs, so adopt only the eight fields you need. Then any later rename is a find-and-replace.

Start small, add enforcement when it pays

This isn't a project. It's one file.

1. Write one document about whatever most recently cost someone an afternoon, with type, title, description and stale_after.
2. Write an index.md that lists it, with a "when to read this" column, and add okf_version: "0.2". The root index is the one place that field belongs, and per the spec it's the only frontmatter an index may carry.
3. Add the pointer to your always-on file. It costs around sixty tokens and holds a path plus a trigger, never a summary, because a summary both adds to the always-on cost and still sends the agent to open the file.

That's enough to get going. Since today >= stale_after is just a comparison, the agent can evaluate it as soon as the file is open. What to do about a stale document is up to you, which the spec leaves open deliberately.

Add automation once a second person can invalidate your document without reading it. That's the real threshold, and it concerns team size more than correctness. Alone with five documents, you'll notice, and agent-side expiry checking is enough. On a team, whoever breaks your document is by definition someone who never opened it, so good intentions can't reach them and something in the pull-request path has to. The cheap version is a scheduled job that reports expired documents. The strong version is a pull-request gate that blocks on an expired document and raises a warning if the code a document describes was modified. Begin at the cheap end.

The short version

What an agent needs isn't more context window. It needs to know where to look, and whatever file it opens must be honest about its age. Sixty tokens up front, everything else on demand, and a document that can break a build once it stops being true, which hasn't been possible before.

Further reading: the OKF v0.2 specification and example bundles, Google Cloud's post on the format, Anthropic's pieces on context engineering, agent skills and prompt caching, and Chroma's context-rot study.