Struct PropertyGraph 

pub struct PropertyGraph { /* private fields */ }

In-memory property graph backed by petgraph’s directed graph.

Implementations

impl PropertyGraph

pub fn new() -> Self

Create an empty graph.

pub fn with_max_nodes(max_node_count: usize) -> Self

Create an empty graph with a custom node capacity limit.

pub fn from_snapshot_with_config( snapshot: GraphSnapshot, max_node_count: usize, ) -> Self

Reconstruct from persisted snapshot, honouring the configured node cap.

max_node_count is the cap for the restored graph (the same value used when the graph was first created). Snapshot data that exceeds the cap is still loaded in full so that no data is silently dropped; the cap only governs future eviction after restoration.

pub fn snapshot(&self) -> GraphSnapshot

Create a snapshot for persistence.

pub fn add_node( &mut self, id: MemoryId, layer: Layer, importance: f32, created_at: Timestamp, ) -> bool

Add a node for a memory record with the default namespace. Returns true if newly added.

pub fn add_node_ns( &mut self, id: MemoryId, layer: Layer, importance: f32, created_at: Timestamp, namespace: Namespace, ) -> bool

Add a node with an explicit namespace. Returns true if newly added.

Returns an error if the graph has reached its max_node_count (F-ENG-14).

pub fn remove_node(&mut self, id: MemoryId) -> bool

Remove a node and all its edges. Returns the IDs of removed edges.

pub fn node_edge_ids(&self, id: MemoryId) -> Vec<EdgeId>

Get the edge IDs connected to a node (for incremental persistence cleanup).

pub fn edge_by_id(&self, edge_id: EdgeId) -> Option<&GraphEdge>

Get a reference to an edge by its EdgeId.

pub fn has_node(&self, id: MemoryId) -> bool

Whether a node exists.

pub fn record_access(&mut self, id: MemoryId)

Record an access to a node (bumps the access counter for LRU eviction).

pub fn drain_dirty_access_counts(&mut self) -> Vec<(MemoryId, u64)>

Drain the set of nodes with updated access_count since the last flush.

Returns (MemoryId, latest_count) pairs and clears the dirty set. Called by the cold-tier flush path in CachedGraphStore.

pub fn access_count(&self, id: MemoryId) -> u64

Get the access count for a node (for monitoring/testing).

pub fn node_count(&self) -> usize

Number of nodes.

pub fn edge_count(&self) -> usize

Number of edges. Count of currently-active (non-expired) edges.

Consistent with get_edges() which also filters by is_currently_active(). Use self.graph.edge_count() directly when a raw physical count (including soft-expired edges) is needed for audit or storage sizing purposes.

pub fn add_edge( &mut self, source: MemoryId, target: MemoryId, relation: EdgeRelation, weight: f32, metadata: Metadata, ) -> HirnResult<EdgeId>

Add a directed edge. Returns the edge ID. If relation.is_bidirectional(), also adds the reverse edge.

Enforces a per-node fan-out cap (MAX_EDGES_PER_NODE) to prevent graph injection attacks.

pub fn add_causal_edge( &mut self, source: MemoryId, target: MemoryId, relation: EdgeRelation, weight: f32, metadata: Metadata, causal: CausalEdgeData, ) -> HirnResult<EdgeId>

Create a causal edge with associated CausalEdgeData.

Identical to [add_edge] but populates causal on the created edge so that strength, confidence, evidence count, and mechanism are stored together with the graph topology. Bidirectional relations (e.g. Contradicts) automatically get a reverse edge that shares the same causal data.

pub fn remove_edge(&mut self, edge_id: EdgeId) -> HirnResult<()>

Remove an edge by its ID.

pub fn expire_edges_for_node( &mut self, node_id: MemoryId, retraction_ts: Timestamp, )

Mark all edges incident to node_id as expired at retraction_ts.

Used when a memory record is retracted: the hot-tier edges remain in the graph (for audit / AS OF time-travel) but are filtered out of live traversal results by is_currently_active().

pub fn get_edges(&self, node_id: MemoryId) -> Vec<&GraphEdge>

Get all edges from/to a node.

Returns only currently-active edges (not yet expired via valid_until). Use [get_edges_at] for time-travel queries.

pub fn get_edges_at( &self, node_id: MemoryId, as_of: Timestamp, ) -> Vec<&GraphEdge>

Get all edges from/to a node that were valid at as_of.

pub fn edges_for_nodes( &self, ids: &[MemoryId], ) -> HashMap<MemoryId, Vec<&GraphEdge>>

Batch edge lookup: returns all edges for each of the given node IDs.

O(1) per node (direct petgraph adjacency). Missing IDs are silently skipped (no entry in the result map).

pub fn get_edges_visible( &self, node_id: MemoryId, allowed_namespaces: &[Namespace], ) -> Vec<&GraphEdge>

Get edges from/to a node, filtered by namespace visibility. Only returns currently-active edges where BOTH endpoints are in the allowed namespaces.

pub fn get_edges_of_type( &self, node_id: MemoryId, relation: EdgeRelation, ) -> Vec<&GraphEdge>

Get edges filtered by relation type.

pub fn get_edges_of_type_visible( &self, node_id: MemoryId, relation: EdgeRelation, allowed_namespaces: &[Namespace], ) -> Vec<&GraphEdge>

Get edges of a given relation type, filtered by namespace visibility. Only returns currently-active edges.

pub fn get_edges_between(&self, a: MemoryId, b: MemoryId) -> Vec<&GraphEdge>

Get edges between two specific nodes (currently-active only).

pub fn get_edges_between_visible( &self, a: MemoryId, b: MemoryId, allowed_namespaces: &[Namespace], ) -> Vec<&GraphEdge>

Get edges between two nodes, only if both are in the allowed namespaces.

pub fn edge_mut(&mut self, edge_id: EdgeId) -> Option<&mut GraphEdge>

Mutably access an edge by ID.

pub fn all_edges(&self) -> Vec<&GraphEdge>

Get all currently-active edges (immutable).

Expired edges (where valid_until has passed) are excluded. Use all_edges_including_expired() for audit / time-travel use.

pub fn all_edges_including_expired(&self) -> Vec<&GraphEdge>

Get all edges including expired ones (for audit and time-travel queries).

pub fn get_neighbors( &self, start: MemoryId, depth: usize, min_weight: f32, ) -> Vec<MemoryId>

BFS traversal from start to depth, respecting min_weight. Returns the set of discovered node IDs (excluding the start node).

pub fn get_neighbors_filtered( &self, start: MemoryId, depth: usize, min_weight: f32, allowed_namespaces: Option<&[Namespace]>, ) -> Vec<MemoryId>

BFS traversal with optional namespace filtering. If allowed_namespaces is Some, only nodes in allowed namespaces are traversed.

pub fn shortest_path( &self, source: MemoryId, target: MemoryId, ) -> Option<Vec<MemoryId>>

Shortest path (BFS) from source to target. Returns the path as a vec of MemoryIds (including source and target), or None if no path exists.

pub fn subgraph(&self, node_ids: &[MemoryId]) -> Vec<&GraphEdge>

Extract a subgraph containing the specified nodes and all edges between them.

pub fn outgoing_weighted( &self, node_id: MemoryId, ) -> Vec<(MemoryId, f32, EdgeRelation)>

Get outgoing neighbors with their edge weights (used by activation engine).

pub fn outgoing_weighted_iter( &self, idx: NodeIndex, ) -> impl Iterator<Item = (NodeIndex, f32, &EdgeRelation)>

Zero-allocation iterator over outgoing edges: (target NodeIndex, weight, &EdgeRelation).

Unlike outgoing_weighted, this returns petgraph NodeIndex values and borrows the relation instead of copying/collecting. Ideal for spreading activation hot paths.

pub fn incoming_weighted_iter( &self, idx: NodeIndex, ) -> impl Iterator<Item = (NodeIndex, f32, &EdgeRelation)>

Zero-copy iterator over incoming edges from idx. Returns (source_idx, weight, &relation).

pub fn node_index(&self, id: MemoryId) -> Option<NodeIndex>

Resolve a MemoryId to its petgraph NodeIndex.

pub fn node_id(&self, idx: NodeIndex) -> Option<MemoryId>

Resolve a petgraph NodeIndex back to a MemoryId.

pub fn node_ids(&self) -> Vec<MemoryId>

Get all node IDs.

pub fn node_importance(&self, id: MemoryId) -> Option<f32>

Get node importance (cached).

pub fn set_node_importance(&mut self, id: MemoryId, importance: f32)

Update node importance.

pub fn node_layer(&self, id: MemoryId) -> Option<Layer>

Get node layer.

pub fn node_namespace(&self, id: MemoryId) -> Option<&Namespace>

Get node namespace (borrowed to avoid cloning in hot paths).

pub fn namespaces_compatible(&self, a: MemoryId, b: MemoryId) -> bool

Check whether two nodes can be connected based on namespace rules. Auto-edges are allowed only within the same namespace or when either node is in the shared namespace.

Trait Implementations

impl Default for PropertyGraph

fn default() -> Self

Returns the “default value” for a type.