Struct GraphEngine 

pub struct GraphEngine { /* private fields */ }

In-memory graph engine backed by petgraph, synced to SQLite via codemem-storage.

Design: intentional in-memory architecture

All graph data (nodes, edges, adjacency) is held entirely in memory using HashMap-based structures. This is deliberate: graph traversals, centrality algorithms, and multi-hop expansions benefit enormously from avoiding disk I/O on every edge follow. The trade-off is higher memory usage, which is acceptable for the typical code-graph sizes this engine targets.

Memory characteristics

• nodes: HashMap<String, GraphNode> — ~200 bytes per node (ID, kind, label, namespace, metadata, centrality).
• edges: HashMap<String, Edge> — ~150 bytes per edge (ID, src, dst, relationship, weight, properties, timestamps).
• edge_adj: HashMap<String, Vec<String>> — adjacency index mapping node IDs to incident edge IDs for O(degree) lookups.
• id_to_index: maps string IDs to petgraph NodeIndex values.
• cached_pagerank / cached_betweenness: centrality caches populated by recompute_centrality().

Use CodememEngine::graph_memory_estimate() for a byte-level sizing estimate based on current node and edge counts.

Thread safety

GraphEngine is not Sync — it stores mutable graph state without internal locking. Callers in codemem-engine wrap it in Mutex<GraphEngine> (via lock_graph()) to ensure exclusive access. All public &mut self methods (e.g., add_node, recompute_centrality) require the caller to hold the lock.

Implementations

impl GraphEngine

pub fn pagerank_for_namespace( &self, namespace: &str, damping: f64, iterations: usize, tolerance: f64, ) -> HashMap<String, f64>

Compute PageRank scores for nodes in a single namespace using power iteration.

Only nodes belonging to namespace participate. Edges that cross into other namespaces are ignored so that unrelated projects cannot inflate or deflate centrality scores within this namespace.

Returns a map from node ID to PageRank score (only for nodes in the namespace).

pub fn pagerank( &self, damping: f64, iterations: usize, tolerance: f64, ) -> HashMap<String, f64>

Compute PageRank scores for all nodes using power iteration.

• damping: probability of following an edge (default 0.85)
• iterations: max number of power iterations (default 100)
• tolerance: convergence threshold (default 1e-6)

Returns a map from node ID to PageRank score.

pub fn louvain_communities(&self, resolution: f64) -> Vec<Vec<String>>

Detect communities using the Louvain algorithm.

Treats the directed graph as undirected for modularity computation. resolution controls community granularity (1.0 = standard modularity). Returns groups of node IDs, one group per community.

pub fn betweenness_centrality(&self) -> HashMap<String, f64>

Compute betweenness centrality for all nodes using Brandes’ algorithm.

For graphs with more than 1000 nodes, samples sqrt(n) source nodes for approximate computation.

Returns a map from node ID to betweenness centrality score (normalized by 1/((n-1)(n-2)) for directed graphs).

pub fn strongly_connected_components(&self) -> Vec<Vec<String>>

Find all strongly connected components using Tarjan’s algorithm.

Returns groups of node IDs. Each group is a strongly connected component where every node can reach every other node via directed edges.

pub fn topological_layers(&self) -> Vec<Vec<String>>

Compute topological layers using Kahn’s algorithm.

Returns layers where all nodes in layer i have no dependencies on nodes in layer i or later. For cyclic graphs, SCCs are condensed into single super-nodes first, then the resulting DAG is topologically sorted.

Each inner Vec contains the node IDs at that layer.

pub fn subgraph_top_n( &self, n: usize, namespace: Option<&str>, kinds: Option<&[NodeKind]>, ) -> (Vec<GraphNode>, Vec<Edge>)

Return top-N nodes by centrality and edges between them. Optionally filter by namespace and/or node kinds.

Non-structural edges (CALLS, IMPORTS, INHERITS, IMPLEMENTS, DEPENDS_ON) from top-N nodes pull their targets into the result so that these relationship types are visible in the UI graph.

pub fn label_community(&self, member_ids: &[&str]) -> String

Label a community by the most common parent directories of its member nodes.

Takes a list of node IDs, looks up their file_path payloads, extracts parent directory names (second-to-last path component), and returns a label. If all members share the same directory, returns that name. If mixed, combines the two most frequent directories with +. Returns "unknown" if no file paths are found.

pub fn louvain_with_assignment(&self, resolution: f64) -> HashMap<String, usize>

Return node-to-community-ID mapping for Louvain.

impl GraphEngine

pub fn new() -> GraphEngine

Create a new empty graph.

pub fn from_storage( storage: &dyn StorageBackend, ) -> Result<GraphEngine, CodememError>

Load graph from storage.

pub fn node_count(&self) -> usize

Get the number of nodes.

pub fn edge_count(&self) -> usize

Get the number of edges.

pub fn expand( &self, start_ids: &[String], max_hops: usize, ) -> Result<Vec<GraphNode>, CodememError>

Multi-hop expansion: given a set of node IDs, expand N hops to find related nodes.

pub fn neighbors(&self, node_id: &str) -> Result<Vec<GraphNode>, CodememError>

Get neighbors of a node (1-hop).

pub fn connected_components(&self) -> Vec<Vec<String>>

Return groups of connected node IDs.

Treats the directed graph as undirected: two nodes are in the same component if there is a path between them in either direction. Each inner Vec<String> is one connected component.

pub fn compute_centrality(&mut self)

Compute degree centrality for every node and update their centrality field.

Degree centrality for node v is defined as: (in_degree(v) + out_degree(v)) / (N - 1) where N is the total number of nodes. When N <= 1, centrality is 0.

pub fn get_all_nodes(&self) -> Vec<GraphNode>

Return all nodes currently in the graph.

pub fn get_node_ref(&self, id: &str) -> Option<&GraphNode>

Return a reference to a node without cloning. Returns None if not found.

pub fn get_edges_ref(&self, node_id: &str) -> Vec<&Edge>

Return references to edges incident on a node without cloning.

This is the zero-copy variant of GraphBackend::get_edges() — same lookup logic via edge_adj, but returns &Edge instead of owned Edge.

pub fn recompute_centrality(&mut self)

Recompute and cache PageRank and betweenness centrality scores.

This should be called after loading the graph (e.g., on server start) and periodically when the graph changes significantly.

pub fn recompute_centrality_for_namespace(&mut self, namespace: &str)

Recompute PageRank for a single namespace and update the cache.

Only scores for nodes in namespace are written; scores for nodes in other namespaces are left unchanged. This prevents cross-project pollution when the shared database holds multiple indexed projects.

Stale scores for deleted nodes in this namespace are evicted.

pub fn recompute_centrality_with_options(&mut self, include_betweenness: bool)

Recompute centrality caches with control over which algorithms run.

PageRank is always computed. Betweenness centrality is only computed when include_betweenness is true, since it is O(V * E) and can be expensive on large graphs.

pub fn ensure_betweenness_computed(&mut self)

Lazily ensure betweenness centrality has been computed.

If cached_betweenness is empty (e.g., after recompute_centrality_with_options(false)), this method computes and caches betweenness centrality on demand. If the cache is already populated, this is a no-op.

pub fn get_pagerank(&self, node_id: &str) -> f64

Get the cached PageRank score for a node. Returns 0.0 if not found.

pub fn get_betweenness(&self, node_id: &str) -> f64

Get the cached betweenness centrality score for a node. Returns 0.0 if not found.

pub fn raw_graph_metrics_for_memory( &self, memory_id: &str, ) -> Option<RawGraphMetrics>

Collect raw graph metrics for a memory node from both code-graph and memory-graph neighbors.

Code neighbors (sym:, file:, chunk:, pkg:) contribute centrality data (PageRank, betweenness). Memory neighbors (UUID-based) contribute connectivity data (count + edge weights). A function with many linked memories is more important; a memory with many linked memories has richer context.

Returns None if the memory node is not in the graph or has no neighbors.

Trait Implementations

impl Default for GraphEngine

fn default() -> GraphEngine

Returns the “default value” for a type.

impl GraphBackend for GraphEngine

fn add_node(&mut self, node: GraphNode) -> Result<(), CodememError>

Add a node to the graph.

fn get_node(&self, id: &str) -> Result<Option<GraphNode>, CodememError>

Get a node by ID.

fn remove_node(&mut self, id: &str) -> Result<bool, CodememError>

Remove a node by ID.

fn add_edge(&mut self, edge: Edge) -> Result<(), CodememError>

Add an edge between two nodes.

fn get_edges(&self, node_id: &str) -> Result<Vec<Edge>, CodememError>

Get edges from a node.

fn remove_edge(&mut self, id: &str) -> Result<bool, CodememError>

Remove an edge by ID.

fn bfs( &self, start_id: &str, max_depth: usize, ) -> Result<Vec<GraphNode>, CodememError>

BFS traversal from a start node up to max_depth.

fn dfs( &self, start_id: &str, max_depth: usize, ) -> Result<Vec<GraphNode>, CodememError>

DFS traversal from a start node up to max_depth.

fn bfs_filtered( &self, start_id: &str, max_depth: usize, exclude_kinds: &[NodeKind], include_relationships: Option<&[RelationshipType]>, ) -> Result<Vec<GraphNode>, CodememError>

BFS traversal with filtering: exclude certain node kinds and optionally restrict to specific relationship types.

fn dfs_filtered( &self, start_id: &str, max_depth: usize, exclude_kinds: &[NodeKind], include_relationships: Option<&[RelationshipType]>, ) -> Result<Vec<GraphNode>, CodememError>

DFS traversal with filtering: exclude certain node kinds and optionally restrict to specific relationship types.

fn shortest_path( &self, from: &str, to: &str, ) -> Result<Vec<String>, CodememError>

Shortest path between two nodes.

fn stats(&self) -> GraphStats

Get graph statistics.

fn get_all_nodes(&self) -> Vec<GraphNode>

Get all nodes in the graph.

fn get_node_ref(&self, id: &str) -> Option<&GraphNode>

Zero-copy node lookup. Returns a reference into the backend’s internal storage. Only meaningful for in-memory backends. Database backends should leave the default (returns None) and callers should use get_node() instead.

fn get_edges_ref(&self, node_id: &str) -> Vec<&Edge>

Zero-copy edge lookup. Returns references into the backend’s internal storage. Only meaningful for in-memory backends. Database backends should leave the default (returns empty) and callers should use get_edges() instead.

fn node_count(&self) -> usize

Number of nodes in the graph.

fn edge_count(&self) -> usize

Number of edges in the graph.

fn recompute_centrality(&mut self)

Recompute all centrality metrics (PageRank + betweenness).

fn recompute_centrality_with_options(&mut self, include_betweenness: bool)

Recompute centrality, optionally including expensive betweenness calculation.

fn recompute_centrality_for_namespace(&mut self, namespace: &str)

Recompute PageRank scoped to a single namespace, updating only that namespace’s scores in the cache. Nodes from other namespaces are unaffected.

fn ensure_betweenness_computed(&mut self)

Lazily compute betweenness centrality if not yet computed.

fn compute_centrality(&mut self)

Compute degree centrality (updates nodes in place).

fn get_pagerank(&self, node_id: &str) -> f64

Get cached PageRank score for a node.

fn get_betweenness(&self, node_id: &str) -> f64

Get cached betweenness centrality score for a node.

fn raw_graph_metrics_for_memory( &self, memory_id: &str, ) -> Option<RawGraphMetrics>

Collect graph metrics for a memory node (used in hybrid scoring).

fn connected_components(&self) -> Vec<Vec<String>>

Find connected components (treating graph as undirected).

fn strongly_connected_components(&self) -> Vec<Vec<String>>

Find strongly connected components using Tarjan’s algorithm. Each SCC is a group where every node can reach every other via directed edges.

fn pagerank( &self, damping: f64, iterations: usize, tolerance: f64, ) -> HashMap<String, f64>

Compute PageRank scores for all nodes. Returns a map from node ID to PageRank score.

fn pagerank_for_namespace( &self, namespace: &str, damping: f64, iterations: usize, tolerance: f64, ) -> HashMap<String, f64>

Compute PageRank scores for nodes in a single namespace. Only nodes belonging to namespace participate; cross-namespace edges are ignored. Returns a map from node ID to PageRank score (only for nodes in the namespace). Default is abstract; implementers must provide namespace-scoped computation.

fn louvain_communities(&self, resolution: f64) -> Vec<Vec<String>>

Run Louvain community detection at the given resolution. Returns groups of node IDs, one group per community.

fn topological_layers(&self) -> Vec<Vec<String>>

Compute topological layers of the graph. Returns layers where all nodes in layer i have no dependencies on nodes in layer i or later.

fn louvain_with_assignment(&self, resolution: f64) -> HashMap<String, usize>

Return node-to-community-ID mapping for Louvain.

fn subgraph_top_n( &self, n: usize, namespace: Option<&str>, kinds: Option<&[NodeKind]>, ) -> (Vec<GraphNode>, Vec<Edge>)

Return a top-N subgraph: the highest-centrality nodes plus all edges between them. Non-structural edges from top-N nodes pull their targets into the result.