# How Graph Expansion Improves Search Results in LLM Wiki

> Discover how graph expansion elevates search results in LLM Wiki by connecting semantically related pages beyond keyword matches. Improve your LLM Wiki search experience today.

- Repository: [nash_su/llm_wiki](https://github.com/nashsu/llm_wiki)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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:

```typescript
// 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:

```typescript
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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph.ts) to build a cached retrieval graph and [`src/lib/graph-relevance.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/graph-relevance.ts) to weight edges by LLM similarity and structural cues.
- Community detection in [`src/lib/wiki-graph-analysis.ts`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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`](https://github.com/nashsu/llm_wiki/blob/main/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.