Agentic retrieval: grep beats embeddings

Definition: Inside agent harnesses, retrieval shifted from frozen embedding indexes to lexical, live, self-correcting search loops — because a grep that misses fails loudly (and the agent reformulates), while an embedding that misses fails silently with plausible wrong neighbours.

Predicate: the same shift that put accessibility snapshots in front of agents put grep and glob tools in their hands. The widely deployed agent stack reads structure and searches lexically — so pages that grep well are found, and pages that don't aren't.

Failure behavior is the whole argument#

Contextual-retrieval work was the high-water mark of the embeddings paradigm: pre-chunk, pre-contextualize, pre-index, then similarity-search a frozen corpus. It's elegant, and for fuzzy recall over a huge static corpus it still wins.

What actually took over inside agent harnesses is different: grep and glob loops that are lexical, live, and self-correcting.

The reason isn't accuracy. It's failure behavior.

An embedding search that misses returns plausible wrong neighbours — a silent failure. The agent doesn't know it missed; it confidently proceeds on bad context.

A grep that misses returns nothing — a loud failure the agent immediately reformulates around.

Loud failure is worth more than marginal precision when there's a reasoning loop attached.

A forensics chain in miniature#

The clearest example I have was a debugging session that never touched an embedding:

1. The UI showed nothing where reasoning output should have been.
2. Application logs were clean — no error to chase.
3. Grepped the event store and found a single reasoning.appended event with deltaLength: 0.
4. Grepped a minified provider bundle for the schema and found display: "omitted" | "summarized".
5. One-line fix.

No index, no embeddings, five self-corrections, and unforgeable ground truth at every hop. Each failure named its own cause and the next query wrote itself.

The counter-example is just as instructive: I've had documentation, repository HEAD, and the artifact a CLI actually pulled all be three different things at once. Only the file on disk could be grepped — and only the file on disk was true.

The consequence for content#

This is the quietly funny part. Exact-match keywords are back, because agents grep.

Consistent literal terminology. Stable headings and anchors. Greppable identifiers. The discipline that "semantic search" told everyone to abandon matters again, because the retrieval layer in front of your content is doing string matching, not cosine similarity.

Three things follow:

Write pages that grep well. Consistent literal terminology, stable headings and anchors, exact-match phrasing for the queries that actually matter. Kebab-case, exact-match URL slugs are the cheapest version of this — an agent grepping "agent serp" or "four consumers" should land on the right page without opening anything.

Default to lexical-first loops in your own tooling. Reach for embeddings only for fuzzy recall over large static corpora — as a tool inside the loop, never as the architecture.

Name things once, the same way, everywhere. Files, headings, UI labels. Greppability compounds, and inconsistency is invisible until an agent reformulates three times and gives up.

This is one of four claims in Machine legibility: one discipline, four readers. The naming-consistency thread connects directly to the synthesizer consumer in One discipline, four consumers.