Graph Engine Internals

The graph engine is the core of Synapses. It holds the entire code graph in memory and provides fast traversal for context retrieval.

In-Memory Representation

The graph uses adjacency list maps:

• outEdges — maps each node ID to its outgoing edges
• inEdges — maps each node ID to its incoming edges
• edgeSet — deduplication map keyed by (from, to, type) tuples, preventing duplicate edges from repeated parses

Nodes carry metadata: type (function, struct, file, package, etc.), name, file path, line number, and whether the symbol is exported.

BFS Ego-Graph Carving

When an agent requests context for a symbol, the engine carves an ego-graph centered on that node:

1. Start at the root node with a score of 1.0
2. Expand via BFS, visiting neighbors level by level
3. Decay the score at each hop (configurable decay factor)
4. Modulate edge weights based on edge type — call edges carry more weight than file-contains edges
5. Budget the traversal by token count — stop expanding when the estimated token cost of included nodes exceeds the budget

The result is a subgraph focused around the target symbol, sized to fit the agent’s context window.

Personalized PageRank (PPR)

For broader context queries, the engine runs Personalized PageRank:

• Alpha = 0.15 — teleport probability back to the query node
• Power iteration — iterates until score changes converge below a threshold
• Produces a global importance ranking biased toward the query node
• Used to rank nodes when BFS alone returns too many candidates at equal depth

FlatGraph

FlatGraph is a Structure of Arrays (SoA) layout rebuilt from the main graph:

• Node data stored in parallel arrays (IDs, types, names, files) instead of maps of structs
• Edge lists stored as contiguous slices
• Cache-friendly for sequential traversal — important when scanning thousands of nodes

FlatGraph is read-only and rebuilt asynchronously after each parse cycle.

GraphIndex

GraphIndex is a read-optimized columnar view that provides fast lookups by various dimensions:

• By file path
• By node type
• By package
• By name (with FTS support)

Rebuilt asynchronously after parse, it serves as the primary query layer for search(mode="exact") and search tools.

Intent-Specific Weight Adjustments

The engine adjusts edge weights based on the agent’s declared intent:

This ensures the carved subgraph contains the most relevant nodes for the task at hand.

Hybrid Lambda Scoring

When semantic embeddings are available, the engine blends two signals:

• Structural score — from BFS traversal (graph distance and edge weights)
• Semantic score — cosine similarity between node embeddings and the query embedding

The blend factor (lambda) is configurable. A lambda of 0.0 uses pure structural scoring; 1.0 uses pure semantic; values in between blend both signals.