Cairn — How structure-aware retrieval works

State of the art

Three research strands, each got part of it right.

Cairn isn't novel science. It's an opinionated synthesis of three lines of retrieval research, packaged as a real, agent-ready product.

Baseline · 2022→present

Naive vector RAG

Split the document into fixed-size chunks, embed each, store in a vector DB. At query time, embed the query and return the top-k nearest chunks.

Fast to build, easy to ship — the default in every framework
Chunks have no awareness of headings, sections, or document tree
Cross-references and entities are pulverized at chunking time
"Why was this chunk returned?" is a hard question

Verdict. Works on Q&A over flat knowledge. Falls apart on structured documents where context comes from where a paragraph sits, not just what it says.

Structure → uniform chunks → vector search → context-free hits

ICLR 2024 · arXiv:2401.18059

RAPTOR — recursive summarization tree

Take naive chunks, then recursively cluster + summarize bottom-up. The result is a tree where higher nodes are abstractions of their children. Retrieval can hit any level of the tree.

First widely-adopted hierarchical retrieval — +20% on QuALITY
Multi-granularity retrieval: thematic queries → high nodes
But the tree is built from vector clusters, not the document's own structure
Summaries can hallucinate (~4% in the paper's audit)

Verdict. Proved hierarchy works. But the hierarchy it builds is statistical, not authorial — it ignores the TOC the author already wrote.

Tree built bottom-up by clustering chunks, not from the document's TOC

Dec 2025 · arXiv:2512.03413

BookRAG — structure-aware index + entity graph

For books, manuals, handbooks: the author already gave you a TOC. Use it. BookIndex = (T, G, M): a hierarchical Tree of the actual TOC, an entity Graph, and a Mapping from every entity back to where it lives in the tree.

Tree T mirrors the document's own headings — pseudo-TOC reconstruction
Entity graph G traces concepts across sections
Mapping M tells you exactly where each concept lives
Agent loop inspired by Information Foraging Theory: scent → patch → forage
SOTA on three benchmarks · lower token consumption than baselines
No public reference implementation

Verdict. The right vision for structured documents. The paper is 6 months old; the code never landed.

BookIndex = Tree (T) + Entity Graph (G) + Mapping (M)

Feb 2026 · arXiv:2602.03442 · MIT licensed

A-RAG — agent with multi-granularity tools

The agent isn't a passive recipient of retrieved chunks. Expose three retrieval tools at different granularities — keyword, semantic, chunk-read — and let a ReAct-style agent decide what to call and when.

Truly agentic: autonomous strategy + iterative execution + interleaved tool use
94.5% HotpotQA, 89.7% 2WikiMultiHop with GPT-5-mini
Test-time scaling: better with more compute
But "hierarchy" here is granularity, not document structure
Designed for multi-document corpora, not single large docs

Verdict. The right interface for agents. The wrong index for structured documents.

Agent calls retrieval tools iteratively, deciding strategy on the fly

Synthesis

Cairn — repo graph + document index + MCP tools.

BookRAG's vision of a document-native index, A-RAG's discipline of agentic multi-granularity tools, RAPTOR's idea of multi-level summaries — shipped as a local repository workflow. Cairn discovers docs, builds one structured index per source, then exposes repo search and per-document drilldown over MCP.

01 · REPO INDEX

Documents stay separate

docsgraph sync discovers README files, docs, specs, ADRs, PDFs, and optional MarkItDown sources. Each source gets its own Tree, Summaries, Entities, Cross-references, and Vectors.

02 · TOOLS

Repo first, then drill in

Repo mode adds list_documents and search_documents, then routes the eight document tools with optional doc. The agent composes; Cairn never speaks for it.

03 · DISCLOSURE

Progressive by default

Outlines return gists. Searches return synopses, short heads, and evidence snippets. Full text is opt-in through get_section, expand, or read_range.

04 · INTEROP

MCP-native

Works with Claude Code, Cursor, Codex, Goose, and other MCP clients. Fake providers support offline smoke tests; production embedders and summarizers stay pluggable.

Repo search is hybrid

search_documents searches every indexed repo document and returns globally ranked section hits with doc, source, section id, stable anchor, evidence, score breakdown, and explanation. repo_context composes those hits into an agent-ready context pack.

The ranker blends dense vector similarity, field-supported lexical evidence, BM25-style sparse score, document/path identity, and graph propagation from tree, xref, and entity-neighborhood edges. repo_graph and repo_impact expose that docs graph without reimplementing CodeGraph's source-code symbol graph.

Document tools stay explicit

search_semantic is dense vector search inside one document. search_keyword is exact case-insensitive lexical scan, not BM25. get_related returns tree and xref neighbors.

That separation is intentional: repo discovery gets the hybrid ranker; follow-up tools stay predictable so an agent can inspect, expand, and cite exactly what it selected.

Side by side: same question, two strategies

Asking a 200-page handbook: "How do I handle timeouts in the retry middleware?"

// Naive vector RAG

embed(query) + top-10 chunk search— · k=10

return 10 chunks of ~512 tokens each — most unrelated5,120 tok

agent reads them all to figure out which is relevant5,120 tok

agent realizes context is missing — needs surrounding sections+ retry

second pass: another 10 chunks5,120 tok

still no cross-references; answer is guessedlow trace

Total tokens consumed ≈ 15,360

Traceability low

// Cairn (repo-scoped)

list_documents() — see indexed docs and freshnessmetadata

search_documents("retry middleware timeouts")620 tok

get_section(doc="handbook", id="middleware/retry")280 tok

get_related(doc="handbook", kinds=["xref","parent"])240 tok

expand(doc="handbook", id="middleware/retry", to="full")1,200 tok

cites cairn://handbook/middleware/retry#timeout-handlingstable anchor

Total tokens consumed ≈ 2,340

Traceability high

Flow numbers are illustrative. The benchmark harness ships now; README has starter-suite numbers and reproduction commands.

Comparison at a glance

	Naive RAG	RAPTOR	BookRAG	A-RAG	Cairn
Primary index	Vector chunks	Clustered tree	Doc TOC + graph	Vector chunks	Repo catalog + doc TOC + 4 overlays
Respects authorial structure	no	partial	yes	no	yes
Multi-granularity	no	yes	yes	yes	yes
Agentic tool interface	no	no	yes	yes	yes
Progressive disclosure default	no	partial	yes	partial	implemented
MCP-native	no	no	no	no	yes
Local-first by default	depends	no	no	depends	yes
Citations / stable anchors	no	weak	yes	weak	mandatory
Public implementation	many	yes	none yet	yes (MIT)	this repo

Stop dumping documents into AI.
Give it a map instead.

Large structured documents break every existing AI workflow.

// Dump it all in

// Naive vector RAG

// GraphRAG-style pipelines

Three research strands, each got part of it right.

Naive vector RAG

RAPTOR — recursive summarization tree

BookRAG — structure-aware index + entity graph

A-RAG — agent with multi-granularity tools

Cairn — repo graph + document index + MCP tools.

Documents stay separate

Repo first, then drill in

Progressive by default

MCP-native

Repo search is hybrid

Document tools stay explicit

Side by side: same question, two strategies

// Naive vector RAG

// Cairn (repo-scoped)

Comparison at a glance