# How Four Relevance Signals Are Weighted in LLM Wiki's Graph Engine

> Discover how LLM Wiki's graph engine weights four relevance signals: source overlap, direct links, common neighbors, and type affinity. Understand the calculation for final relevance scores.

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

---

**In LLM Wiki's graph engine, four relevance signals are weighted as follows: source overlap receives the highest weight of 4.0, direct bidirectional links are weighted at 3.0, common neighbors using the Adamic-Adar index are weighted at 1.5, and type affinity receives the lowest weight of 1.0, with the final relevance score calculated as the linear sum of these weighted contributions.**

The `nashsu/llm_wiki` repository implements a sophisticated retrieval graph that scores relevance between knowledge base pages using these four independent signals. Understanding how these relevance signals are weighted in LLM Wiki's graph engine helps developers optimize knowledge retrieval and predict which pages will be considered most related by the algorithm.

## The Weight Configuration in [`src/lib/graph-relevance.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/graph-relevance.ts)

The **weight values** are defined as a constant object at the top of [`src/lib/graph-relevance.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/graph-relevance.ts). These fixed multipliers determine how much each topological or semantic feature influences the final relevance calculation:

```typescript
const WEIGHTS = {
  directLink: 3.0,
  sourceOverlap: 4.0,
  commonNeighbor: 1.5,
  typeAffinity: 1.0,
} as const

```

This configuration prioritizes **source overlap** (shared origin documents) over structural connections, while still valuing direct hyperlinks significantly more than neighborhood topology or semantic type relationships.

## Breakdown of the Four Weighted Signals

Each signal measures a different dimension of page relatedness before being multiplied by its respective weight in the `calculateRelevance` function.

### Source Overlap (Weight: 4.0)

The **highest-weighted signal** counts how many source files appear in the front-matter `sources:` array of both pages. When two pages reference the same PDF or external document, they receive a raw score multiplied by 4.0, making shared provenance the strongest indicator of relevance in LLM Wiki's graph engine.

### Direct Links (Weight: 3.0)

This signal captures **bidirectional wikilink relationships** by counting both outgoing and incoming `[[wikilinks]]` between two pages. The sum of forward and backward links is multiplied by 3.0, rewarding explicit author-created connections between concepts.

### Common Neighbors (Weight: 1.5)

Using the **Adamic-Adar index**, this signal measures connectivity through shared neighbors—pages that both nodes link to or receive links from. The raw Adamic-Adar score is multiplied by 1.5, providing moderate weight to topological similarity even when direct links don't exist.

### Type Affinity (Weight: 1.0)

The **lowest-weighted signal** consults a predefined `TYPE_AFFINITY` matrix that encodes relationships between page types (entity, concept, source, synthesis, query). The affinity value is multiplied by 1.0, serving as a subtle semantic boost rather than a primary ranking factor.

## How the Scoring Algorithm Works

Inside `calculateRelevance` in [`src/lib/graph-relevance.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/graph-relevance.ts), the engine computes each weighted component and returns their arithmetic sum:

```typescript
const directLinkScore = (forwardLinks + backwardLinks) * WEIGHTS.directLink;
const sourceOverlapScore = sharedSourceCount * WEIGHTS.sourceOverlap;
const commonNeighborScore = adamicAdar * WEIGHTS.commonNeighbor;
const typeAffinityScore = (affinityMap?.[nodeB.type] ?? 0.5) * WEIGHTS.typeAffinity;

return directLinkScore + sourceOverlapScore + commonNeighborScore + typeAffinityScore;

```

This linear combination (lines 54–86 in the source) ensures that **sourceOverlapScore** dominates the calculation when pages share common origins, while **directLinkScore** provides significant secondary influence.

## Practical Implementation Examples

### Computing Relevance Between Two Specific Nodes

To calculate the weighted relevance score between two pages programmatically:

```typescript
import { buildRetrievalGraph, calculateRelevance } from '@/lib/graph-relevance';

// Build the graph for a project (once)
const graph = await buildRetrievalGraph('/path/to/project');

// Grab two nodes from the graph
const nodeA = graph.nodes.get('page-a');
const nodeB = graph.nodes.get('page-b');

if (nodeA && nodeB) {
  const relevance = calculateRelevance(nodeA, nodeB, graph);
  console.log(`Relevance between ${nodeA.title} and ${nodeB.title}:`, relevance);
}

```

The `calculateRelevance` call internally applies the four weights (3.0, 4.0, 1.5, 1.0) to each respective signal before summing them.

### Retrieving Top-Related Pages

To fetch the most relevant pages for a given node using the weighted scoring system:

```typescript
import { getRelatedNodes, buildRetrievalGraph } from '@/lib/graph-relevance';

async function showTopRelated(pageId: string) {
  const graph = await buildRetrievalGraph('/path/to/project');
  const related = getRelatedNodes(pageId, graph, 5); // top 5

  related.forEach(({ node, relevance }) => {
    console.log(`→ ${node.title} (score: ${relevance.toFixed(2)})`);
  });
}

```

The `getRelatedNodes` function iterates over the entire graph, invokes `calculateRelevance` for each candidate, and sorts results by the composite weighted score.

## Integration with the Knowledge Graph

The weighted relevance scores are consumed by [`src/lib/wiki-graph.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph.ts) (lines 95–105) to construct the final knowledge graph edges. According to the LLM Wiki source code, the `buildRetrievalGraph` output feeds directly into the edge-weighting logic, ensuring that the four weighted signals determine how strongly pages are connected in the traversable graph structure.

## Summary

- **Source overlap** carries the highest weight (4.0), prioritizing pages derived from common source documents.
- **Direct bidirectional links** receive substantial weight (3.0), rewarding explicit `[[wikilink]]` connections.
- **Common neighbors** via Adamic-Adar contribute moderately (1.5) based on shared topological neighborhood.
- **Type affinity** provides baseline semantic weighting (1.0) based on entity/concept relationships.
- All weights are defined in the `WEIGHTS` constant in [`src/lib/graph-relevance.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/graph-relevance.ts) and applied linearly in the `calculateRelevance` function.

## Frequently Asked Questions

### What is the most heavily weighted relevance signal in LLM Wiki?

**Source overlap** receives the highest weight of 4.0, meaning that sharing common source files in front-matter metadata contributes more to relevance scoring than any other signal, including direct hyperlinks.

### How does the graph engine handle bidirectional wikilinks?

The engine counts both outgoing and incoming `[[wikilinks]]` between two pages, sums them into a `directLinkScore`, and multiplies the result by the **directLink** weight of 3.0, effectively treating mutual linking as stronger than single-direction references.

### Can the relevance signal weights be customized without modifying the source code?

Currently, no. The weights are hardcoded as constants in the `WEIGHTS` object at lines 30–35 of [`src/lib/graph-relevance.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/graph-relevance.ts). Adjusting the weighting scheme requires modifying this constant and rebuilding the project.

### Which algorithm measures the common neighbors signal?

LLM Wiki uses the **Adamic-Adar index**, a metric that weights common neighbors inversely by the logarithm of their degree (number of connections), multiplied by the fixed weight of 1.0 to produce the `commonNeighborScore`.