Graph Enrichment

How SourcePrep keeps deepening what it knows about your code — parsing structure fast, reasoning about meaning slowly, and re-checking what it thinks it knows whenever the code changes.

The short version

SourcePrep doesn't just search your code — it actively tries to understand it. A fast Rust parser maps the structure in seconds. Then small and large language models layer in meaning: what each file does, how it connects to others, which modules it belongs to. When you change a file, the system notices its neighbors' understanding may have shifted and re-checks them. Your AI never acts on stale context. The rest of this page explains how — including the research it's built on, for readers who want that depth.

Why Epistemology?

Most code intelligence tools answer a simple question: "Which files match this query?"SourcePrep asks a fundamentally different one: "How well does the system understand this code — and how justified is that understanding?"

That question is epistemological. Epistemology is the branch of philosophy concerned with knowledge itself — what it means to know something, how knowledge is justified, and when it becomes stale. These aren't abstract concerns when you're building a code graph:

A file summary can be accurate (the text is correct) but not understood (we don't know how it connects to anything)
A node's understanding decays when its neighbors change — because context is relational, not intrinsic
A doc referencing a renamed file is drifted knowledge — technically present, epistemically broken
Re-enriching the least understood nodes first (residual scheduling) mirrors how belief propagation converges in probabilistic graphical models

The trace graph doesn't just contain knowledge about your code — it knows about its own knowledge.

Inside the Pipeline

Enrichment runs in two groups. Fast Sync runs on every file save (~seconds) to keep the structural map current. Deep Enrichment runs when the system is idle or on a schedule (~minutes) to layer in meaning and relationships.

Group A: Fast Sync

Structural Graph Rust

Tree-sitter parses code into symbols, imports, and call edges. A Markdown scanner extracts section headers and links from documentation files. This is the factual skeleton — no LLM involved, no opinions, just structure.

Fast Catalogue 3b LLM

A small, fast model reads strategic excerpts of each file (Rust-ranked hot sections) to produce a summary, role classification, and initial confidence estimate. This is triage, not understanding — the 3b model's job is to answer "what does this file appear to do?"

Relationship Validation Rust

The LLM hypothesizes, Rust validates pattern. The catalogue model suggests relationships ("FileA probably relates to FileB") — the Rust engine checks if both files actually exist. Hallucinated edges are discarded. Confirmed edges gain boosted confidence. Inferred edges never override parser-derived structural edges.

Knowledge Embedding Embeddings

Validated nodes and their metadata are embedded for semantic search retrieval. This makes the catalogue immediately searchable while deep enrichment continues in the background.

Group B: Deep Enrichment

Deep Reasoning 14b LLM

Epistemic enrichment. A larger model reasons about each node in the context of its graph neighbors — adding domain tags, architecture layers, design patterns, cross-references, and a self-reported reasoning confidence. Nodes are processed in reverse-topological order (leaf files first) so each node's neighbors already have enriched summaries when it's processed.

Module Synthesis 14b LLM

Cluster synthesis. Enriched nodes are grouped by domain tags and graph connectivity into subsystem modules. The model generates module-level summaries — creating navigable high-level architecture maps. Think of it as the trace graph discovering its own subsystems.

Codebase Atlas Routing

Synthesized modules are used to build a pre-retrieval routing index. When your AI asks for context, the Atlas scopes the search to the right subsystem before retrieval begins — reducing noise without reducing coverage.

Continuous Deepening Loop

The convergence loop. Nodes whose understanding scores have decayed — because a neighbor changed, a doc drifted, or source was modified — are re-enriched in priority order. Inspired by belief propagation (Pearl 1988): the least-understood nodes are processed first, and the loop continues until the graph stabilizes or a token budget is reached.

Deep Knowledge Embedding Embeddings

All enriched knowledge — module summaries, deepened connections, refined cross-references — is re-embedded for maximum retrieval accuracy. The search index now reflects the graph's full understanding, not just the initial catalogue.

The Understanding Score

Every node in the graph gets an understanding score (0.0–1.0) — internally called the epistemic score — that represents how well the trace comprehends this node in the context of the entire codebase. This is fundamentally different from search relevance or summary accuracy. A file can have a perfect summary but a low understanding score if we don't know how it connects to anything else.

The score is a weighted composite of six dimensions:

Summary confidence (20%)

How certain is the catalogue model about its own output?

Validation depth (15%)

Has a larger model verified and enriched the summary?

Neighbor coverage (20%)

Are connected nodes also enriched? Understanding is relational.

Cross-reference density (15%)

How many doc↔code bidirectional links exist?

Enrichment depth (15%)

How many reasoning passes has this node been through?

Temporal currency (15%)

Has the source changed since enrichment? Stale knowledge scores zero.

Score Decay — Knowledge Has a Half-Life

Understanding scores aren't static. They decay when the world changes around a node — because in epistemology, knowledge that hasn't been re-verified against current evidence is no longer justified belief:

Event	Effect	Rationale
Source file changed	Score → 0.0	Everything might be wrong
Neighbor re-enriched	Score × 0.95	Context shifted slightly
Referenced doc updated	Score × 0.90	Documentation changed, claims may be invalid
Trace rebuilt (structural)	Score × 0.80	Edges changed, relationships may differ
Module re-synthesized	Score × 0.97	Module understanding refined

Decay cascades through neighbors: if File A changes, File B (which imports A) decays slightly, and File C (which imports B) decays even less — up to a 3-hop propagation limit. This mirrors how uncertainty propagates through belief networks.

Nodes with decayed scores enter a re-analysis queue ordered by score (lowest first). The Continuous Deepening stage processes this queue until the graph converges or the token budget is exhausted.

Documentation Mining

Most indexing tools treat .md files as flat text blobs. SourcePrep's enrichment pipeline extracts structure from documentation: section headers, code references, status markers, and cross-links. This enables:

Doc↔code links — docs reference code files and vice versa
Staleness detection — a doc referencing a renamed file is flagged as drifted
Decision tracking — architecture decisions and their outcomes are captured
Orphan detection — docs with no code references or incoming links are identified

Research Foundation

The pipeline draws on peer-reviewed research in knowledge graph construction, code intelligence, and probabilistic reasoning:

Hierarchical graph + community summaries — Microsoft GraphRAG (2024)
LLM → validator multi-agent enrichment — KARMA (2025)
AST → code knowledge graph — KG-based Repo-Level Code Gen (2025)
Bottom-up topological enrichment — RepoAgent, EMNLP 2024
Iterative convergence via residual scheduling — Belief Propagation (Pearl 1988, Yedidia 2003)
Score decay and re-enrichment — inspired by epistemic logic and truth-maintenance systems (Doyle 1979)

Why This Matters in Practice

Without enrichment: asking your AI "how does the ad framework work?" might return one file that mentions "ad".

With enrichment: the same query returns the module summary, the 6 files that compose the subsystem, their entry points, the 3 docs that describe the architecture, and a flag that one doc references a renamed file. The understanding score tells the AI that the framework is well understood, but one file's score has decayed because one neighbor was recently modified and hasn't been re-analyzed yet.

The difference isn't just better search results. It's the difference between a tool that retrieves and a tool that understands — and knows the boundary between the two.