Skip to main content

The six search modes

GRAIL has six distinct ways to answer a question. Five use an LLM, one doesn't. Learning which to use for what kind of question is the core skill to use GRAIL well.

Quick table​

ModeBest forLLM costCommand
localNamed concepts ("who is X?", "what does Y do?")1 callgrail query <proj> "..." --mode local
cascadeSpecific facts ("what dosage does protocol X cite?")1 call--mode cascade
globalBroad thematic questions ("what is this all about?")several (map-reduce)--mode global
documentSingle source ("summarise law-21250.pdf")1 call--mode document -d file.pdf
agentCompound questions ("compare X and Y")1–N calls--mode agent
recallMemory by structural filter0 calls--mode recall --since 7d --tag X

When to pick which​

local — entities as anchor​

Embed the question, find the most similar entities in the graph, bring their linked text, relationships, and reports, answer.

grail query my-project "Who is the Ricarte Soto Law?" --mode local

Works well when your question names things that are likely to be entities in the graph. If the question is vague or has no clear nouns, consider cascade.

cascade — entities + text rescue​

Vanilla GraphRAG's big problem: sometimes the fact you want lives in a text chunk whose main entity wasn't extracted. cascade solves this by adding BM25/cosine text rescue and combining both rankings.

grail query my-project "How many months does chemotherapy coverage last?" --mode cascade

This is usually the best option for specific factual questions. If you come from traditional RAG, cascade is the mode that will pleasantly surprise you.

global — bird's-eye view​

Map-reduce over community reports. Each report contributes a thematic perspective; the reduce synthesises them.

grail query my-project "What are the central themes of the corpus?" --mode global

Expensive for large corpora (one LLM call per report above N tokens), but unique for synthesis questions.

document — a single file​

Scope the entire search to one document. Useful for "summarise X" or "what does Y say about Z" when you already know which file to point at.

grail query my-project "Summarise this" --mode document -d law-21250.pdf

agent — let the LLM decide​

The agent receives the question and has local, cascade, global, document as tools. It decides which to call, repeats if needed up to 5 iterations, then synthesises a final answer.

grail query my-project "Compare AUGE vs Ricarte Soto Law coverage" --mode agent

Best option for compound or ambiguous questions. More expensive but more robust.

recall — no LLM​

Pure filter over the structural columns: observed_at, category, tag, entity, confidence. No embedding, no LLM, no cost. Memory only.

# Last week's decisions
grail query my-memory --mode recall --since 7d --tag decision

# Everything for one client, any date
grail query my-memory --mode recall --category "work/clients/acme/**"

The same filter flags also combine with other modes as a candidate modifier:

# Cascade but only over the last month's observations tagged "decision"
grail query my-memory "What did we decide about the migration?" \
  --mode cascade --since 30d --tag decision

Question shape matters​

For local and cascade, a well-shaped question matches ~3× better than a poorly shaped one. The formula that works in our benchmarks:

[WHO does it] + [WHAT is the process] + [SPECIFIC TERMS from the domain]

Compare:

  • ❌ "How much does treatment cost" — vague, no named entities.
  • ✅ "How much does FONASA cover for oncological chemotherapy treatment" — names the entity (FONASA), the process (cover treatment), and specific terms (oncological chemotherapy).

Next step​