Meta Retrieval Programs: Teaching an LLM to Write Its Own Search Code

A new repository from Meta's research org, facebookresearch/retrieval-programs, is the official code for the paper Learning to Program Retrievals: Composing Search Primitives via Reinforcement Learning by Kyuyoung Kim, Zilin Xiao, Zhiyuan Wang, Avinash Atreya, Ke Yang, Jinwoo Shin and Kecheng Hao. The idea is simple to state: rather than having a model emit a search query and read what comes back, let it write a small Python program that runs the search for it.

The authors call the framework Retrieval Program Learning, or RPL. Their reported headline, from the abstract, is that a 4B model trained with RPL outperforms all 8B baselines on open-domain question answering. At the time of writing the repo is brand new with a single star, so this is a release to read and evaluate, not a viral project. It qualifies as coverage because it comes from a top lab and tackles a problem every RAG builder has: how an agent should search.

TL;DR: RPL at a glance

What does "programming a retrieval" actually mean?

Most retrieval-augmented systems come in two shapes. In a fixed pipeline, a retriever fetches the top documents and the model reads them. In an agentic loop such as the Search-R1 family, the model issues one search call per turn and reads the results before deciding the next call. Both limit how much the model can do between a search and the moment documents land in its context.

RPL changes the unit of action. The policy emits a program that can call several search primitives, keep local variables, branch, loop, and print only what it wants to keep. The README's example program fuses dense and sparse retrieval results, reranks them with a cross-encoder, and prints the top documents. The abstract frames the payoff this way: the program can retrieve broadly, process intermediate results, and selectively build the model's context, so retrieval breadth no longer limits how much context is consumed.

That is the part builders should notice. Context is expensive and noisy. A program that pulls 100 candidates, filters them in code, and hands the model five is doing work that a one-query-per-turn agent spends many turns, and many tokens, on.

Why is training this hard?

Reinforcement learning gives sparse feedback: you only learn at the end whether the final answer matched. A useful program needs several coordinated decisions (which primitives, in what order, with what filters), so random sampling rarely finds a good one. The authors' fix is program mutation.

According to the abstract and the README, the pipeline is:

1. Run RL on the policy.
2. For rollouts whose program failed to retrieve the gold answer, harvest a nearby program that does retrieve it. The mutations are local and grammar-constrained, and each candidate is verified by execution.
3. Measure, against a resample control, how much answering from the repaired evidence helps.
4. Fine-tune the policy on the repaired programs (supervised fine-tuning).
5. Continue RL from the fine-tuned policy.

In effect the model learns from edited versions of its own mistakes, with execution as the judge. That mirrors a pattern seen elsewhere in recent work: Anthropic's auditor training with reinforcement learning leaned on verifiable signals, and Amazon's SageMaker multi-turn RL walkthrough shows how costly that loop becomes in practice.

What results are reported, and what is not?

From the abstract: RPL consistently improves open-domain QA across model sizes and across in-domain and out-of-domain benchmarks, with especially large gains on multi-hop tasks. A 4B model trained with RPL beats all 8B baselines. On corpus-level reasoning, RPL gets the highest answer F1 and document-coverage F1 for both model sizes while substantially reducing context consumption and retrieval turns.

What the README adds is the evaluation protocol rather than numbers. Checkpoints are chosen by the best unweighted mean exact match on held-out NQ and HotpotQA between steps 50 and 1000. The reported average is the unweighted mean over seven benchmarks: NQ, TriviaQA, PopQA, HotpotQA, 2WikiMultihopQA, MuSiQue and Bamboogle. Baselines include Direct, chain-of-thought, RAG, IRCoT and Search-o1, and the repo references Search-R1, AutoRefine and MARAG-R1 as comparison methods. It also supports GlobalQA as a second corpus.

What we could not find on the repo page: per-benchmark scores, the 8B baselines, or released checkpoints (the README's evaluation commands use Qwen/Qwen3-4B). Check the paper's tables before quoting any figure beyond the abstract.

How would you try it?

The README lays out a research-grade setup, not a pip install:

pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install flash-attn --no-build-isolation
pip install -r requirements.txt
pip install -r requirements-retrieval.txt
java -version   # JDK 21 needed for the BM25 retriever

Then download the 2018 Wikipedia corpus and prebuilt indices with scripts/download_index.sh --out indices --what corpus,bm25,flat, prepare data with scripts/prepare_data.sh, start the retriever and reranker services, and train with scripts/train_rpl.sh --data data/nq_hotpotqa_rpl --rerank-gpus 4 --gpu-mem-util 0.55 --out runs/rpl. Evaluation uses scripts/eval.sh and tools/qa_report.py, and scripts/run_mutation_round.sh drives the harvest, verify and SFT steps.

One gotcha from the README is worth repeating: if the retriever service is unreachable, the policy silently falls back to answering from memory, and accuracy drops without an error. Start and health-check the services first.

Is it safe and can you use it commercially?

Two things to note. First, the policy writes code that runs in a sandbox. The repo has a sandbox module and a search SDK, but anyone adapting this to production should treat model-written code as untrusted and verify the isolation themselves. Second, licensing is mixed: the README says the majority of the project is CC BY-NC 4.0, which forbids commercial use, while the vendored Search-R1 and verl v0.8.0 code is Apache 2.0. GitHub's sidebar shows "Apache-2.0 licenses found", which understates the non-commercial part. For a company, the safe reading is: study the method, reimplement if needed, and ask counsel before shipping the repo's code.

How does this compare with other retrieval-agent ideas?

Fixed RAG is cheap and predictable but cannot adapt. One-call-per-turn agents adapt but burn turns and context. RPL sits in between: the model decides the retrieval procedure, yet executes it in one shot, so adaptation happens inside a program. Related explainx.ai coverage looks at neighbouring trade-offs: Apple's plan-or-retrieve-first tool discovery architectures and its selection-based reasoning for multimodal search agents, the browser RAG faithfulness evaluation with small models, and the managed route in Bedrock's agentic knowledge base retrieval guide.

Where does it fit in the history of agentic search?

The path to RPL is short. Early retrieval-augmented generation fetched documents once and pasted them into the prompt. Prompting methods such as IRCoT interleaved reasoning with retrieval, letting the model search again after each thought. RL-trained agents like Search-R1 then learned when and what to search from answer-level reward, which the README treats as a baseline family. RPL's contribution is to widen the action: a single step is no longer one query but a whole procedure, with the model deciding how many sources to hit, how to merge them and what to discard.

For practitioners, the useful framing is cost per answer. Every extra retrieval turn adds latency and tokens, and every raw document pasted into context adds noise. The abstract says RPL reduces both context consumption and retrieval turns on corpus-level reasoning, so the efficiency argument, not just accuracy, is the reason to follow this line of work.

What should builders take from it?

• Let code do the filtering. Even without RL, giving an agent a sandbox to merge, dedupe and rerank results before they reach the context window saves tokens.
• Small models can win with the right action space. The reported 4B result is about the interface the model acts through, not only its size.
• Use execution as a verifier. Program mutation works because a mutated program can be run and checked.
• Mind the evaluation. Seven QA benchmarks on a 2018 Wikipedia snapshot is a clean research setting; your corpus and queries will differ.

Limits and open questions

The repo is days old, with one star, one fork and one open pull request. No independent reproduction exists yet. Gains on Wikipedia QA may not carry to enterprise documents, code search or messy PDFs. The training pipeline needs several GPUs plus a reranker service, which puts it out of reach for most hobbyists. And the licence blocks direct commercial use.

Bottom line

RPL is an interesting answer to a practical question: what if the model wrote the retrieval procedure instead of picking from a menu? The abstract's claim that a 4B model beats 8B baselines is the authors' own, and the repo does not yet show the numbers. Read the paper, run the small config if you have the GPUs, and watch for checkpoints and third-party results.

Related reading

• Anthropic: training alignment auditors with reinforcement learning
• Amazon SageMaker multi-turn reinforcement learning
• David Silver's Ineffable and reinforcement learning beyond LLMs
• Apple: plan or retrieve first
• Browser RAG with small language models
• Bedrock agentic retrieval guide
• Primary sources: GitHub repo and the arXiv paper

Details reflect the repo README and arXiv abstract as of October 26, 2026 and may change.