Struct TemporalGraphIndex

pub struct TemporalGraphIndex<D: DistanceMetric> {
    inner: TemporalHnsw<D>,
    edges: TemporalEdgeLayer,
    typed_edges: TypedEdgeStore,
}

Temporal Graph Index: HNSW with temporal successor/predecessor edges.

Wraps TemporalHnsw (untouched) with a TemporalEdgeLayer for causal navigation and hybrid search.

Fields

inner: TemporalHnsw<D>

The underlying spatiotemporal HNSW index.

edges: TemporalEdgeLayer

Temporal edge layer (successor/predecessor per entity).

typed_edges: TypedEdgeStore

Typed relational edges (RFC-013 Part B).

Implementations

impl<D: DistanceMetric + Clone> TemporalGraphIndex<D>

pub fn new(config: HnswConfig, metric: D) -> Self

Create a new empty temporal graph index.

pub fn from_temporal_hnsw(inner: TemporalHnsw<D>) -> Self

Create from an existing TemporalHnsw (migration path).

Rebuilds the temporal edge layer from the entity_index.

pub fn insert(&mut self, entity_id: u64, timestamp: i64, vector: &[f32]) -> u32

Insert a temporal point.

pub fn insert_with_reward( &mut self, entity_id: u64, timestamp: i64, vector: &[f32], reward: f32, ) -> u32

Insert a temporal point with an outcome reward.

pub fn search( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, ) -> Vec<(u32, f32)>

Standard search (delegates to inner TemporalHnsw).

pub fn causal_search( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, temporal_context: usize, ) -> Vec<CausalSearchResult>

Causal search: semantic search + temporal edge context.

Phase 1: Standard HNSW search. Phase 2: For each result, walk temporal edges to get what happened before and after.

Answers: “Find similar entities, and show me what happened to them next.”

pub fn hybrid_search( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, beta: f32, query_timestamp: i64, ) -> Vec<(u32, f32)>

Hybrid search: beam search exploring both semantic AND temporal edges.

At each step of the beam search on level 0, when visiting a node, also adds its temporal neighbors to the candidate set with a distance penalty controlled by beta.

• beta = 0.0: pure semantic HNSW (ignores temporal edges)
• beta = 1.0: always follow temporal edges (aggressive temporal exploration)

pub fn inner(&self) -> &TemporalHnsw<D>

Access the underlying TemporalHnsw.

pub fn edges(&self) -> &TemporalEdgeLayer

Access the temporal edge layer.

pub fn trajectory( &self, entity_id: u64, filter: TemporalFilter, ) -> Vec<(i64, u32)>

Get trajectory for an entity.

pub fn vector(&self, node_id: u32) -> &[f32]

Get vector by node ID.

pub fn entity_id(&self, node_id: u32) -> u64

Get entity ID by node ID.

pub fn timestamp(&self, node_id: u32) -> i64

Get timestamp by node ID.

pub fn len(&self) -> usize

Total number of points.

pub fn is_empty(&self) -> bool

Whether empty.

pub fn inner_mut(&mut self) -> &mut TemporalHnsw<D>

Mutable access to the underlying TemporalHnsw.

pub fn config(&self) -> &HnswConfig

Get HNSW config.

pub fn set_ef_construction(&mut self, ef: usize)

Set ef_construction at runtime.

pub fn set_ef_search(&mut self, ef: usize)

Set ef_search at runtime.

pub fn enable_scalar_quantization(&mut self, min_val: f32, max_val: f32)

Enable scalar quantization.

pub fn disable_scalar_quantization(&mut self)

Disable scalar quantization.

pub fn search_with_recency( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, recency_lambda: f32, recency_weight: f32, ) -> Vec<(u32, f32)>

Search with recency bias and normalized distances.

pub fn reward(&self, node_id: u32) -> f32

Get the reward for a node.

pub fn set_reward(&mut self, node_id: u32, reward: f32)

Set the reward for a node retroactively.

pub fn search_with_reward( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, min_reward: f32, ) -> Vec<(u32, f32)>

Search with reward pre-filtering.

pub fn compute_centroid(&self) -> Option<Vec<f32>>

Compute the centroid of all vectors.

pub fn set_centroid(&mut self, centroid: Vec<f32>)

Set centroid for anisotropy correction.

pub fn clear_centroid(&mut self)

Clear centroid.

pub fn centroid(&self) -> Option<&[f32]>

Get current centroid.

pub fn centered_vector(&self, vec: &[f32]) -> Vec<f32>

Center a vector by subtracting the centroid.

pub fn regions(&self, level: usize) -> Vec<(u32, Vec<f32>, usize)>

Get semantic regions at a given HNSW level.

pub fn region_assignments( &self, level: usize, filter: TemporalFilter, ) -> HashMap<u32, Vec<(u64, i64)>>

O(N) single-pass region assignments.

pub fn region_trajectory( &self, entity_id: u64, level: usize, window_days: i64, alpha: f32, ) -> Vec<(i64, Vec<f32>)>

Smoothed region distribution trajectory for an entity.

pub fn typed_edges(&self) -> &TypedEdgeStore

Access the typed edge store.

pub fn typed_edges_mut(&mut self) -> &mut TypedEdgeStore

Mutable access to the typed edge store.

pub fn add_typed_edge( &mut self, source: u32, target: u32, edge_type: EdgeType, weight: f32, )

Add a typed edge between two nodes.

pub fn success_score(&self, node_id: u32) -> f32

Get the success score of a node based on typed edges.

Uses Beta prior: P(success) = (1 + n_success) / (2 + n_total).

pub fn save(&self, dir: &Path) -> Result<()>

Save to directory (index + temporal edges + typed edges).

pub fn load(dir: &Path, metric: D) -> Result<Self>

Load from directory.

pub fn scored_search( &self, query: &[f32], k: usize, filter: TemporalFilter, query_timestamp: i64, weights: &ScoringWeights, query_region: Option<u32>, ) -> Vec<(u32, f32)>

Search with Bayesian multi-factor scoring.

Pipeline:

1. HNSW over-fetch 4k candidates
2. Compute features per candidate (similarity, recency, reward, success_score, region)
3. Bayesian rerank using weights
4. Return top-k

This integrates typed edges (success_score), reward annotations, recency, and region membership into a single scored retrieval.

pub fn assign_region(&self, vector: &[f32], level: usize) -> Option<u32>

Assign a vector to a region at a given HNSW level.

pub fn trajectory_search( &self, recent_trajectory: &[(i64, &[f32])], k: usize, signature_depth: usize, ) -> Vec<(u64, f64, usize)>

Search for episodes with similar trajectory SHAPE (not just similar state).

Uses path signatures to compare the agent’s recent trajectory against stored episodes. Returns episodes whose trajectory shape is most similar, regardless of where in embedding space they are.

This enables “lateral thinking”: finding episodes that MOVED similarly, not just episodes that WERE in a similar position.

Returns (entity_id, signature_distance, trajectory_length). Search for episodes with similar trajectory SHAPE (not just similar state).

Uses path signatures to compare the agent’s recent trajectory against stored episodes. Returns episodes whose trajectory shape is most similar.

This enables “lateral thinking”: finding episodes that MOVED similarly, not just episodes that WERE in a similar position.

Returns (entity_id, signature_distance, trajectory_length).

Trait Implementations

impl<D: DistanceMetric + Clone> TemporalIndexAccess for TemporalGraphIndex<D>

fn search_raw( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, ) -> Vec<(u32, f32)>

Search with temporal filtering, returning (node_id, score) pairs.

fn trajectory(&self, entity_id: u64, filter: TemporalFilter) -> Vec<(i64, u32)>

Retrieve trajectory for an entity: (timestamp, node_id) pairs.

fn vector(&self, node_id: u32) -> Vec<f32>

Get the vector for a node. Returns owned vec for thread safety.

fn entity_id(&self, node_id: u32) -> u64

Get the entity_id for a node.

fn timestamp(&self, node_id: u32) -> i64

Get the timestamp for a node.

fn len(&self) -> usize

Number of points in the index.

fn is_empty(&self) -> bool

Whether the index is empty.

fn regions(&self, _level: usize) -> Vec<(u32, Vec<f32>, usize)>

Get semantic regions at a given HNSW level (RFC-004). Returns (hub_node_id, hub_vector, n_assigned) per region.

fn region_members( &self, _region_hub: u32, _level: usize, _filter: TemporalFilter, ) -> Vec<(u32, u64, i64)>

Get points belonging to a specific region, optionally time-filtered (RFC-005). Returns (node_id, entity_id, timestamp) per member.

fn region_assignments( &self, _level: usize, _filter: TemporalFilter, ) -> HashMap<u32, Vec<(u64, i64)>>

Assign all nodes to regions in a single O(N) pass, optionally time-filtered. Returns HashMap<hub_id, Vec<(entity_id, timestamp)>>.

fn region_trajectory( &self, _entity_id: u64, _level: usize, _window_days: i64, _alpha: f32, ) -> Vec<(i64, Vec<f32>)>

Smoothed region-distribution trajectory for an entity (RFC-004).

fn metadata(&self, _node_id: u32) -> HashMap<String, String>

Get metadata for a node. Returns empty map if not available.

fn search_with_metadata( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, metadata_filter: &MetadataFilter, ) -> Vec<(u32, f32)>

Search with metadata filtering (post-filter on search results). Default: ignores metadata filter and delegates to search_raw.