Graph Search

The GraphSearchEngine combines pgvector similarity search with k-hop graph traversal to retrieve semantically relevant subgraphs. This hybrid approach finds entities that are not only textually similar to the query but also structurally connected to them - bridging isolated vector matches into coherent architectural context.

Search modes

The engine supports five search modes, each suited to different use cases:

Scoring

The scoreTriplets function assigns each triplet an importance score based on:

• Node distance: lower cosine distance from the query embedding → higher score
• Node importance_weight: extraction-time importance from the store
• Edge feedback_weight: EMA-updated from session outcomes (adjusted by feedbackInfluence, default 0.3)

Triplets involving nodes that weren't directly found by vector search (i.e. reached only via graph traversal) receive a distance penalty since no per-edge embedding vector is stored. The feedbackWeight on edges counterbalances this for frequently-used relationships.

Wiring the engine

The engine is dependency-injected. Production wiring:

import { GraphSearchEngine } from '@/lib/graph/search/engine'
import { GraphTraversal } from '@/lib/graph/search/traversal'

const store = new PgGraphStore(db).withScope({ orgId, projectId })
const traversal = new GraphTraversal(store)

const engine = new GraphSearchEngine({
  store,
  traversal,
  embedder: (text) => voyageEmbed(text),  // optional but required for GRAPH_COMPLETION
  llm: { ask: (q) => callLlm(q) },       // optional, required for NATURAL_LANGUAGE/SUMMARY
})

For tests, substitute InMemoryGraphStore for store - the engine is backend-agnostic.

Context budget

The search results feed directly into context injection with a default token budget of 500 tokens for the graph block. Triplets are added in order of importance score until the budget is exhausted - over-budget triplets are skipped, never truncated mid-line.

Cedar authorization

All search modes check Cedar access at the calling layer (buildGraphContextBlock) before triplets reach a prompt. Direct use of the engine bypasses this check; always enforce access when surfacing results to agent prompts.

Related pages

• Knowledge Graph Store - searchByEmbedding and IGraphStore API
• Context Injection - how search results become prompt blocks
• Graph Feedback - how session outcomes update feedbackWeight
• MCP Tools - graph_query, graph_neighbors, graph_path