Skip to content

LearnGraphs & hierarchy

RAPTOR

Recursive abstractive processing for tree-organized retrieval

A retrieval index built as a tree: chunks are clustered and summarized, the summaries are clustered and summarized again, and search runs over every level at once.

In DocSlurpIllustrated explainer

On this page
A RAPTOR tree: chunks cluster into summaries, summaries into a root, all searched togetherLevel 0 holds six original chunks: growth-plan-2027, revenue $48.2M, 12% ahead of plan; growth-plan-2027, operating margin 24% vs a 20% target; board-update-2026, a record year funds the expansion; launch-review, London opens in Q2 2027; board-update-2026, the board approved a $12M budget; expansion-forecast, $6.5M first-year bookings forecast. The first three cluster into a level-1 summary, "Earnings outlook: revenue $48.2M, 24% margin vs 20%; record year." The last three cluster into "London expansion: opens Q2 2027, $12M approved, $6.5M bookings." The record-year chunk also joins the second cluster, shown dashed. Both summaries are summarized into a root: earnings of $48.2M revenue at a 24% margin in a record year; growth from a London office opening in Q2 2027 on a $12M budget. All nine nodes are in one index. Q1, "How far above margin target?", matches the leaf about the 24% margin against a 20% target. Q2, "Summarize our FY2027 growth story", matches the root and both level-1 summaries.Q1How far above margin target?Q2Summarize our FY2027 growth storyone index, all 9 nodesEarnings: $48.2M revenue, 24% margin, record year.Growth: London opens Q2 2027 on a $12M budget.level 2summary of summariesEarnings outlookRevenue $48.2M, 24% margin vs 20%; record year.London expansionOpens Q2 2027, $12M approved, $6.5M bookings.level 1summariesgrowth-plan-2027Revenue $48.2M,12% ahead of plangrowth-plan-2027Operating margin24% vs 20% targetboard-update-2026Record year fundsthe expansionlaunch-reviewLondon opensin Q2 2027board-update-2026Board approved$12M budgetexpansion-forecast$6.5M first-yearbookings forecastlevel 0 original chunks · the dashed line is soft clustering: one chunk, two clustersQ1Q2Q2Q2
Each question finds its own altitude. The detail question Q1 matches a leaf, because only the original chunk says "24% vs 20% target." The broad question Q2 matches the summaries, which no single chunk resembles; flat chunk search would hand the model three unrelated fragments instead. Searching every level at once lets both work.

The problem: chunks are the wrong size for half your questions

Chunking picks one granularity for the whole index. Choose 500-token chunks and “How far above our margin target are we?” works well: one chunk of growth-plan-2027.pdf p. 14 says “operating margin 24% against a 20% target”. But “Summarize our FY2027 growth story” has no chunk-sized answer. The best chunks for it are fragments: the revenue forecast from one page, the margin plan from another, the London budget from a third. Retrieval returns a handful, probably not the right handful, and the model stitches a summary from whatever arrived.

Bigger chunks help broad questions and hurt detail questions. There is no single right size, because questions come in different sizes.

The idea: index every level of a summary tree

RAPTOR (Recursive Abstractive Processing for Tree-Organized Retrieval, Sarthi et al., 2024) builds a tree on top of the chunks and puts every node of the tree in the index.

  1. Embed the leaves. Split the corpus into ordinary chunks and embed them. These are level 0.
  2. Cluster. Group chunks whose embeddings are close. RAPTOR uses Gaussian mixture models after reducing dimensions with UMAP, and allows soft membership: a chunk can belong to more than one cluster.
  3. Summarize each cluster. A language model writes a summary of the chunks in each cluster. The summaries are level 1, and they get embedded too.
  4. Repeat. Cluster the level-1 summaries and summarize again, until clustering no longer splits the nodes. The top is the root.

In the figure, six chunks become two level-1 summaries: “earnings outlook” (the $48.2M revenue forecast, the 24% margin against a 20% target, the record year) and “London expansion” (the Q2 2027 opening, the $12M budget, the $6.5M bookings forecast). The record-year chunk from the board update joins both clusters, since it is about earnings and about funding the expansion. A root summarizes the two.

Retrieval picks its own altitude

The paper tries two ways to search the tree:

  • Tree traversal. Start at the top, pick the best-matching nodes, descend into their children, and repeat to the leaves. This forces a fixed mix of levels.
  • Collapsed tree. Flatten all nodes, leaves and summaries alike, into one pool, and run ordinary similarity search over it until a token budget is filled.

The collapsed tree did better in the paper’s experiments, and it is the version worth remembering. A detail question matches a leaf, because only the original text has the exact wording (“24% against a 20% target”). A broad question matches summaries, because a summary is the kind of text that answers it, the same way HyDE exploits the resemblance between answers. Nobody routes the question; the similarity scores do it.

Compared with neighbors

  • GraphRAG also writes summaries at ingest, but it clusters an extracted entity graph and answers global questions by asking every community summary (map-reduce). RAPTOR clusters text embeddings and treats summaries as ordinary search results.
  • Small-to-big retrieval searches small units and returns their larger parent. RAPTOR goes the other way: summaries are searchable on their own, not just containers.
  • A document summary is a one-level tree per file. RAPTOR’s clusters cross document boundaries, so a summary can join the growth plan and the board update.

Where it breaks

  • Ingest cost. Every cluster at every level needs a summary call. The tree must be rebuilt, at least partly, when documents change, and clusters shift as the corpus grows.
  • Summaries can be wrong. A summary that merges two clusters’ facts, or drops a qualifier (“in most cases”), is now retrievable on equal footing with the source text. If the model reads a summary instead of the page, mistakes propagate into answers.
  • Citations get indirect. A summary node has no page of its own. To cite, the system must map it back to the leaves beneath it, which may be dozens of chunks.
  • Clustering is a guess. Topics in an embedding space don’t always match how people think about a corpus. A cluster that mixes two unrelated subjects produces a summary that serves neither.
  • Summaries crowd the results. In the collapsed tree, summaries compete with leaves for the same top-k slots. A broad-sounding detail question can return three summaries and miss the one leaf with the number.

When to reach for it

RAPTOR suits corpora with long documents and a mix of question sizes: books, long reports, manuals, where users ask both “what is section 4 about?” and “what is the torque spec?” It is harder to justify for collections of short, independent documents, where chunks already match questions, or for fast-changing corpora, where the tree would need constant rebuilding.

In DocSlurp

DocSlurp builds a summary tree per document and calls it section summaries. It keeps RAPTOR’s central idea, summaries as first-class search targets at more than one altitude, and changes the part that ages worst: the clustering.

  • Sections, not clusters. Groups are contiguous runs of passages. A heading always starts a new group, and a long section is cut where neighboring passages are least alike (core/worker/src/summary-tree/grouping.ts). Upper levels summarize the summaries below them until one root covers the document. A summary therefore always describes a page range you can point at.
  • One tree per document. No node crosses a file boundary, so the growth plan and the board update each get their own tree. Deleting a document deletes its summaries with it.
  • Opt-in, per project. The switch lives in project settings and saves through its own endpoint (PATCH /v1/projects/:projectId/summary-tree). New uploads get summaries after they are already searchable; documents that were there first get them from a build you start, with an estimate and a required spend cap. Short documents, spreadsheets and recordings get none.
  • Two ways to search with it (core/packages/shared/src/summary-tree.ts):
    • Guide. A summary that matches the question points search at its range of passages. Results and citations are still the original passages, so “Summarize our FY2027 growth story” lands on the outlook section of growth-plan-2027.pdf and cites its pages.
    • Include. The matching summaries also come back, in a separate summaries list with kind: "summary". They carry no quote and no citation, and they are capped to a share of the context, which is the guard against summaries crowding out the one passage with the number.
  • Never slower than plain search. The summary lookup runs beside the passage search with a deadline tied to it. When it runs out of time the search answers from passages alone and says so: summaryTree: { requested, applied, skipped, ms } in the response.

Measured on a 2,304-page development corpus (core/docs/evals/summary-tree/phase0-2026-11-14.md): the build ran at 8,800 to 10,400 pages per $1 of model cost and 39 to 56 pages per minute per concurrent call, about 310 pages per minute with eight calls in flight. That is one corpus on one day’s list prices, not a customer price.

Where it stops short of RAPTOR: no soft clustering, no cross-document level, and the tree is rebuilt for a document when its text changes (unchanged sections reuse their summary, a re-read with a different extractor reuses almost none). A deployment can also keep the feature switched off entirely; the project settings then show it as unavailable.

In DocSlurp

In DocSlurp

DocSlurp builds a summary tree per document, called section summaries, when a project turns it on: contiguous sections cut at headings instead of clusters, no cross-document nodes (core/worker/src/summary-tree/grouping.ts). Search uses it as guide (summaries pick passage ranges; citations stay passages) or include (labeled summaries are returned too) (core/packages/shared/src/summary-tree.ts).

Sources

Jump to