Description
Graph-Expanded Search finds useful connected knowledge that does not contain the query terms and may not be close in embedding space. After hybrid retrieval and reranking establish strong seed hits, the pipeline can ask an injected graph service for neighbors, choose edge types appropriate to the classified intent, apply hop-based score decay, and merge those candidates into the ranked set.
Expansion is bounded and best-effort. Intent controls the default hop count and eligible relationships; hop budgets prevent a dense graph from overwhelming the result pool. A candidate already present from keyword or vector retrieval keeps its stronger score, while graph-only discoveries are labeled as graph matches. Per-seed neighbor failure is dropped without failing successful search streams.
Selling Points
- Surfaces supporting evidence and connected context that literal and semantic similarity alone can miss.
- Intent-aware edge selection makes exploratory queries behave differently from action or lookup queries for a reason.
- Score decay preserves the priority of direct evidence while still making nearby knowledge discoverable.
- Bounded hop and candidate budgets prevent graph fan-out from turning one query into an unbounded traversal.
- Failure isolation keeps search usable when one graph neighborhood is unavailable.
User Story
An engineer searches for a service method while investigating a change. Direct file and symbol matches rank first, but Graph-Expanded Search also returns a caller, an implementing file, and a related artifact connected through the knowledge graph. The engineer gains the surrounding impact context without issuing a second graph-specific query.
Extension Surface
Extensible is the first true rung because packages/search/src/internal/contracts/graph-service.ts defines the injected GraphServiceLike neighbor seam, while packages/search/src/internal/stages/graph-expand.ts keeps intent matrices, decay, and merge behavior search-owned. A composition root can supply a different graph implementation without editing the stage; adding new edge semantics still requires in-repo configuration.
Capabilities & Limits
- Selects edge types and default traversal depth from the query intent.
- Applies deterministic hop decay and merges graph candidates without weakening stronger direct hits.
- Degrades per seed when graph lookup fails, preserving the rest of the ranked response.
- Limits: expansion depends on a composed graph service; the package default is no graph expansion.
- Limits: a closed Playbook row scope suppresses this ordinary stage because authority-safe expansion must happen during scope materialization.
Implementation Map
packages/search/src/internal/stages/graph-expand.tspackages/search/src/internal/contracts/graph-service.tspackages/search/src/internal/pipeline.tspackages/search/src/internal/scope/playbook-scope-resolver.tsapps/web/src/composition/search-service.ts