STOP RE-DERIVING APIs.
START LOOKING THEM UP.

HOW IT WORKS, IN DEPTH.

• 1 · The prompt resolves to llms.txt. The one-liner points the agent at xerj.org/llms.txt — ordered machine-readable steps: install from xerj.org/get, start the single binary, index, query over the Elasticsearch wire, and the reference-coding rules (retrieve before writing, cite what you use, respect licences).
• 2 · The corpus is chosen by problem domain, not language. The agent reads the project's dependencies and domains, picks the open-source repos that already solve those problems, and xc-corpus.sh shallow-clones them into a named corpus. Each repository's licence is recorded in corpus.json; GPL/AGPL entries are approach-only — read the design, never copy the code.
• 3 · Indexing is AST-aware. xc-index.sh runs xerj autoindex: every file is sniffed by content, and source files go through tree-sitter grammars (13 languages) that emit the language, every symbol with its kind and line number, a searchable defs field, and the full body. One index per dataset, incremental on re-runs — re-index when the references change.
• 4 · Retrieval is hybrid, with a stated fallback. xc.py runs BM25 multi_match over body, defs and title — with a measured (not hand-picked) boost on defs so exact symbol names outrank prose — RRF-fused with a vector arm where an index supports it. When no index does, it degrades to BM25-only and says so; a silently lexical-only "hybrid" would be a lie. The default embedder is lexical feature-hashing — vocabulary overlap, not neural understanding.
• 5 · The loop has discipline. Before writing non-trivial code against an unfamiliar API the agent retrieves, reads the returned definition with its file:line, adapts it, cites the source, and checks the licence. If nothing relevant comes back it says so and falls back to normal work — forcing a bad match in is worse than not retrieving.
• 6 · Why the tokens collapse. A retry loop on an unmemorised API burns output tokens — the kind priced 5× above input on Claude models. Grep recovery pulls source into context: up to 1.06M input tokens on one corpus in this study. A retrieved passage is a few hundred tokens and carries the one thing a compiler can never leak — the runtime contract. The per-task table below shows the collapse: thousands of tokens from memory, hundreds with retrieval.

EVERYTHING WE BUILT TO TEST IT.

You cannot measure retrieval on code the model has memorised — it reproduces even a 256-value table from memory. So the unfamiliar corpus is 13 real libraries written for this study (each compiles and passes its own tests), each carrying a runtime contract the compiler cannot warn about. Each task returns the library's own type, so a hand-rolled workaround cannot pass. bare = from memory; XERJ = same model, reference retrieved.

* bare "passes" some cases by recovering an API name from a compiler/runtime error at 20–150× XERJ's tokens, or because the task spec necessarily stated the one non-obvious rule — never by recalling a genuine runtime contract. On the two memorised cases (quill varint, garner trie) the model already knows the algorithm and retrieval saves nothing — which is the point of including them. Source for every library: docs/case-studies/reference-coding →

THE LINE IS SHARP.

Two controls on real, public code the model has trained on — valkey + memcached (a KV server), and tantivy (a search engine) — pin down exactly where retrieval stops paying. The value is gated by memorization.

EVERY LANGUAGE, SAME SHAPE.

Median output tokens to solve, XERJ vs answering from memory. Verdict is the real toolchain in each language (python3, node, cc, javac).

THE SAME TASK, TWO WAYS.

One Java task: build an append-only ledger that must be sealed before replay, truncated to a checkpoint. bare cannot read the library, so it reinvents the whole thing — 503 lines — and still fails the seal contract. XERJ, handed the reference, writes it in four lines and cites the rule it learned:

// reinvented an entire append-log + checkpoint + seal
// state machine from memory, guessing the API surface …
// 503 lines … wrong truncation semantics
// → hidden test FAILED.

public static Ledger upTo(long[] vals, long seq) {
    Ledger l = Ledger.open();
    for (long v : vals) l.append(v);
    l.checkpoint(seq);   // keep 0..seq
    l.seal();            // required before replay
    return l;
}

CAPTURED VERBATIM · docs/case-studies/reference-coding/generated →

VERIFIED: THE PROMPT WORKS.

We ran the opener above verbatim on a fresh task — implement a top-3 heavy-hitters function using the unfamiliar sift crate (whose API is not new()/push()/top_k()). Following the prompt, Claude Code indexed the reference, retrieved sift's real API, and wrote code that compiles and passes a hidden test — using furnish / absorb / seal / crest, the seal-before-read contract a from-memory attempt cannot recover. The full transcript and the generated program are in the repo.

REPRODUCE THE VERIFICATION ITSELF · docs/case-studies/reference-coding →

DO IT YOURSELF.

The whole study reproduces from the repo. The method works on any repository — including your own private code, which is the real use case.

1. Start XERJ. xerj -d ./.xerj-data --insecure — the ES-compatible API comes up on :9200.
2. Build a corpus. xc-corpus.sh async-rust https://github.com/tokio-rs/tokio https://github.com/hyperium/hyper — group by problem domain, not language.
3. Index it. xc-index.sh async-rust — runs xerj autoindex; a 100k-record tree indexes in ~10 s.
4. Retrieve before you write. xc.py async-rust "graceful shutdown with a broadcast channel" — returns the matching definition with file:line.
5. Measure it honestly. The 3-arm harness (csrun.py, csmulti.py) runs bare / native / XERJ, one hidden-test verdict, real tokens from claude -p --output-format json — no API key. Full recipe in MEASURE / CASE_STUDY.md.

WHAT WE WON'T OVERCLAIM.

POINT IT AT YOUR CODE.