Install GNO

Guides

How search works

The GNO retrieval pipeline end to end — BM25, vector, opt-in graph expansion, fusion, and reranking.

GNO’s hybrid search is not magic. It’s a deliberate pipeline of proven retrieval techniques composed to give you accurate results whether you search for exact terms or conceptual matches.

The pipeline

  1. Query expansion — optionally expand the query with HyDE (hypothetical document embeddings) and lexical variants. GNO skips expansion when it has a strong signal.
  2. BM25 retrieval — classical full-text search over the inverted index. Fast and precise for exact terms, technical identifiers, and quoted phrases.
  3. Vector retrieval — cosine similarity over dense embeddings. Handles synonyms and conceptual matches.
  4. Reciprocal rank fusion — merges BM25 and vector results by rank position, not raw score. Robust to different score distributions.
  5. Optional graph expansion — when --graph is passed, bounded one-hop neighbors from top seeds are added as candidates after initial fusion. Active filters still apply, existing chunk positions are preserved, and explicit links are weighted above inferred, ambiguous, or similarity edges.
  6. Second fusion pass — graph candidates join the BM25/vector ranked inputs before reranking, so linked evidence can boost the right chunk instead of duplicating a document-level hit.
  7. Cross-encoder reranking — the fused top-N is rescored by a cross-encoder that looks at query and document together. Slow but highly accurate for the top few results.
  8. Return — the reranked top-K is returned with scores, snippets, and optionally the retrieval pipeline trace.

Speed modes

gno query "topic" --fast
gno query "topic" # balanced
gno query "topic" --thorough
gno query "topic" --graph

Benchmark fixtures

For repeatable retrieval checks, create a fixture with queries and relevant document URIs, then run gno bench <fixture>. The command evaluates BM25, vector, and hybrid modes against the same corpus and prints metrics that make model or pipeline regressions visible before you switch defaults.

gno bench docs/examples/bench-fixture.json
gno bench fixture.json --modes bm25,vector,hybrid --json

--explain

Pass --explain to any query command to see exactly what happened: expansion output, BM25 hits, vector hits, graph expansion status, fusion order, rerank scores, and stage timings including graphMs. Use it to tune your prompts or to debug unexpected results.

gno query "topic" --explain

Strong signal detection

When your query contains exact identifiers or quoted phrases, the pipeline recognizes the strong signal and skips expansion — no point hallucinating a HyDE document when the user already told you exactly what they want.