How Graph Expansion Improves Search Results in LLM Wiki

Graph expansion enhances search by traversing the knowledge graph to surface semantically related pages that share communities or high-relevance edges with the query node, regardless of exact keyword matches.

LLM Wiki (nashsu/llm_wiki) constructs a semantic knowledge graph that links every markdown page based on shared entities and concepts. Rather than relying solely on literal text matches, the system leverages graph expansion to map queries into this graph and retrieve neighboring nodes that are contextually relevant. This approach significantly increases recall and supports exploratory research by revealing conceptual connections that traditional search would miss.

The Graph Expansion Pipeline

The implementation spans several modules that work together to build, analyze, and query the graph. According to the source code in nashsu/llm_wiki, the pipeline operates through four distinct stages.

Building the Retrieval Graph

The process begins in src/lib/wiki-graph.ts, where the system constructs a retrieval graph for the current project. The buildRetrievalGraph function loads a cached graph or builds a fresh one, then adds edges representing semantic relevance through the calculateRelevance helper. This graph is stored in graphCache (lines 3‑6, 40‑55, 165‑189) to avoid expensive recomputation on subsequent searches.

Weighting Edges by Relevance

Once the graph structure exists, src/lib/graph-relevance.ts assigns weights to each edge based on two factors: LLM-generated similarity scores and structural cues such as community membership. These weights determine how "close" a node is to the query node, enabling the search engine to prioritize conceptually similar content over randomly connected pages.

Community Detection via Louvain Algorithm

To identify topic clusters, src/lib/wiki-graph-analysis.ts runs the Louvain community-detection algorithm via the detectCommunities function (lines 14‑24, 24‑36). Nodes residing within the same community are considered strongly related, allowing the search to broaden its scope to "topic-wise" results rather than limiting results to lexical matches.

Merging Graph and Text Results

The final stage occurs in src/lib/search.ts. The main search function accepts an optional graphHits parameter (line 27). When provided, the function merges traditional text hits with the highest-scoring graph neighbors, then sorts the combined result list by relevance score. This yields a result set that includes pages semantically related to the query even if they do not contain the exact search term.

Implementing Graph-Expanded Searches

You can invoke graph expansion programmatically through the search API or toggle it via the UI state store.

Programmatic Search with Graph Hits

To execute a graph-expanded search, pass the graphHits option to the search function. This specifies how many related nodes to include from the graph traversal:

// Import the search helper
import { search } from "@/lib/search";

// Run a plain text search
const plain = await search("large language models");

// Run a graph-expanded search – include top 5 related nodes
const expanded = await search("large language models", {
  graphHits: 5,
});

// Results combine text matches and graph neighbors
const combined = [...plain.results, ...expanded.graphResults];

Controlling Graph UI State

The wiki-store module preserves user preferences for graph visualization across view switches. Use useWikiStore to modify expansion parameters and spacing:

import { useWikiStore } from "@/stores/wiki-store";

// Activate graph view and set expansion parameters
useWikiStore.getState().setActiveView("graph");
useWikiStore.getState().setGraphUiState({ 
  graphSpacingDraft: 1.2 
});

The graphUiState (lines 426‑447, 669‑694 in src/stores/wiki-store.ts) maintains filters, spacing, and last-used expansion settings, ensuring the expanded view retains context when toggled on or off.

Summary

• Graph expansion maps search queries into a knowledge graph to retrieve semantically related pages beyond literal keyword matches.
• The pipeline uses src/lib/wiki-graph.ts to build a cached retrieval graph and src/lib/graph-relevance.ts to weight edges by LLM similarity and structural cues.
• Community detection in src/lib/wiki-graph-analysis.ts groups related nodes using the Louvain algorithm, enabling topic-wise search broadening.
• The search function in src/lib/search.ts merges text hits with graph neighbors when the graphHits parameter is provided.
• UI state persistence in src/stores/wiki-store.ts allows users to toggle graph views without losing expansion context.

Frequently Asked Questions

What is graph expansion in LLM Wiki?

Graph expansion is a search enhancement technique that traverses the knowledge graph to find pages connected to the query through shared entities, community membership, or weighted edges. Instead of returning only pages containing the exact keywords, the system returns neighbors that are semantically related, significantly improving recall for exploratory research.

How does the Louvain algorithm improve search relevance?

The Louvain algorithm, implemented in src/lib/wiki-graph-analysis.ts, detects communities of densely connected nodes within the knowledge graph. When a query matches a node within a specific community, the search engine prioritizes other nodes in that same community, ensuring results stay within the same conceptual topic even when individual pages use different terminology.

Can I disable graph expansion for specific queries?

Yes. Graph expansion is optional and controlled via the graphHits parameter in src/lib/search.ts. If you omit this parameter or set it to zero, the search function returns only traditional text-based matches without traversing the knowledge graph.

How are relevance scores calculated between graph nodes?

Relevance scores are calculated in src/lib/graph-relevance.ts by combining LLM-generated semantic similarity scores with structural metrics such as community co-membership. These weighted edges determine the distance between nodes, with higher weights indicating stronger conceptual relationships that should appear higher in the result list.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}