Your agent is reading four times more than it needs to

The complaint is always a version of the same sentence. "After a point I'm not coding anymore, I'm doing context maintenance." "Every new session feels like hiring the same junior dev again." The agent forgets, so you paste the project back in, and you pay for all of it on every turn.

The usual fix is to hand it more up front: a big instructions file, a repository overview, the whole doc set stuffed into the prompt so the agent has everything it might need. That does make the answer more likely to be in context. It also means every question pays for the whole project, even the ones that touch one corner of it.

There is another way to do it, and this post is a measurement of how much it saves. The worked example is okf, a small command-line tool (gem install okf, or Docker, or a Claude Code plugin) that keeps a project's knowledge as a folder of Markdown files: one file per topic, which it calls a concept, and the folder as a whole a bundle. Your coding agent reads from that bundle the way you would from a terminal. The only question here is how much of it the agent has to read to answer something.

The dump

Call the usual approach the dump. You serialize all of the knowledge and put it in front of the model before it has been asked anything. The cost scales with the size of the project, not the size of the question. Ask where the invoice dedup key lives and you pay the same as asking for a full architecture review, because the context was assembled before either question existed. You could pick the few relevant files by hand instead, and a careful engineer does. Retrieval is that selection made automatic, done by the search and held to a budget by a test.

okf answers the other way. It retrieves. When the agent needs something from the bundle, it runs okf the way you would at a terminal, through the Claude Code plugin or by shelling out to the CLI, and only the last step reads a whole file:

1. Orient. okf index --no-body prints the map: the directories, how many concepts each holds, nothing else. On okf's own bundle that map is 374 bytes.
2. Find. okf search <terms> ranks the concepts by where the terms land and hands back a few rows, not bodies.
3. Read one. Open the winning file. That is the only full concept anyone reads.

Ask okf's own bundle "which concept covers conformance?" and those three steps come to about 1,200 tokens: the 374-byte map, a 2,300-byte ranked result, and the one 2,000-byte concept the answer was in.

Handing that same bundle over whole is 194 KB of Markdown, around 48,000 tokens (call it four bytes each). (Serialized as a graph with okf graph --json, the form the test below uses, it is 208 KB, near enough the same: the concept bodies are the weight, not the wrapper.) The question was answered on 2% of the project, a fortieth of it.

the question	retrieved	handed over whole	read
"which concept covers conformance?"	~1,200 tok	~48,000 tok	2% (41x less)
"how does ranking work?"	~4,400 tok	~48,000 tok	9% (11x less)

The second row is the worst case in this bundle: its answer is one of the largest concepts, and reading the map, the search, and that whole file still comes to under a tenth.

One thing the table leaves out: whether the search returns the right concept in step two. It counts the cost of an answer, not the odds of finding it. Recall is a real question, and a separate one.

The part that matters is where the number lives

A favorable measurement is easy to run once. What makes this one worth a post is that it is not a measurement at all. It is an assertion in okf's test suite, in test/integration/cli/by_dir/cli_search_test.rb:

progressive = orient.bytesize + search.bytesize + one_body.bytesize
assert_operator progressive, :<, dump / 4   # under a quarter of the whole

It builds a bundle, asks it a question the ordinary way, serializes the same bundle whole, and fails the build if retrieval costs more than a quarter of the dump. It has been green on every commit since version 1.5.0, and the gem is open source, so you can read the assertion rather than take my word for it.

So "okf answers in under a quarter" is not a claim the project made once and moved on from. It is a claim the project cannot quietly stop being true about, because the day it stops, the build goes red. And a quarter is the floor, not the typical case: the test builds a deliberately unfriendly bundle, wide and shallow, where the map is proportionally large, so the guarantee holds even at the bad end. On a real project the number is the 41x and 11x above. The test promises a quarter; real bundles come in at a tenth to a fortieth.

What a leaner context does not buy

There is a line this does not cross. A smaller context is cheaper to send and it fills the window more slowly. It is not a fix for whether the model does what the file says. An agent can read a rule, quote it back to you accurately, and violate it on the next turn, and no retrieval budget changes that. Instruction-following does decay as the context fills, and a leaner context keeps you on the good end of that curve for longer, but that is a contributing factor and nothing more. No document format makes a model obey, and okf does not claim to.

What retrieval fixes is the arithmetic, not the model.

Stop dumping

If your knowledge is a pile you hand over whole, every question pays for the pile. If it is a bundle the agent can orient over, search, and read one file from, every question pays for the question.

None of that is special to okf. It is what a map, a search, and a filesystem have always been for. What okf adds is the parts you would otherwise build for yourself: a format that makes project knowledge take the shape those three things work on, the CLI that does the orienting and searching, and the test in the suite that keeps the quarter honest. Point your agent at a bundle and every question starts paying for the question.

Your agent is probably reading four times more than it needs to. It does not have to.