Struct Graph 

pub struct Graph { /* private fields */ }

An embeddable graph database built on SQLite.

Provides entity/edge storage, bi-temporal edges, FTS5 search, vector embeddings with RRF fusion, and recursive CTE traversal.

Implementations

impl Graph

pub fn open(db_path: &Path) -> Result<Self>

Open an existing database file.

pub fn open_or_create(db_path: &Path) -> Result<Self>

Open an existing database or create a new one at the given path.

pub fn in_memory() -> Result<Self>

Open an in-memory database (for testing or ephemeral use).

pub fn add_episode(&self, episode: Episode) -> Result<EpisodeResult>

Add an episode (event, decision, message) to the graph.

pub fn get_episode(&self, id: &str) -> Result<Option<Episode>>

Get an episode by ID.

pub fn list_episodes(&self, limit: usize, offset: usize) -> Result<Vec<Episode>>

List episodes with pagination.

pub fn add_entity(&self, entity: Entity) -> Result<()>

Add an entity (node) to the graph.

pub fn add_entity_deduped( &self, entity: Entity, threshold: f64, ) -> Result<(String, bool)>

Add an entity with fuzzy deduplication against existing entities of the same type.

If an existing entity with Jaro-Winkler similarity >= threshold exists, returns that entity’s ID and stores the new name as an alias. Otherwise creates a new entity.

Returns (entity_id, was_merged: bool).

pub fn get_entity(&self, id: &str) -> Result<Option<Entity>>

Get an entity by ID.

pub fn get_entity_by_name(&self, name: &str) -> Result<Option<Entity>>

Get an entity by name.

pub fn list_entities( &self, entity_type: Option<&str>, limit: usize, ) -> Result<Vec<Entity>>

List entities, optionally filtered by type.

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

Add an edge (relationship) between two entities.

pub fn get_edges_for_entity(&self, entity_id: &str) -> Result<Vec<Edge>>

Get all edges for an entity (both as source and target).

pub fn invalidate_edge(&self, edge_id: &str) -> Result<()>

Invalidate an edge (set valid_until to now).

pub fn link_episode_entity( &self, episode_id: &str, entity_id: &str, span_start: Option<usize>, span_end: Option<usize>, ) -> Result<()>

Link an episode to an entity (with optional character span).

pub fn store_embedding(&self, episode_id: &str, embedding: &[f32]) -> Result<()>

Store an embedding for an episode (serialized as little-endian f32 bytes).

pub fn store_entity_embedding( &self, entity_id: &str, embedding: &[f32], ) -> Result<()>

Store an embedding for an entity.

pub fn get_embeddings(&self) -> Result<Vec<(String, Vec<f32>)>>

Load all episode embeddings as (episode_id, Vec) pairs.

pub fn search(&self, query: &str, limit: usize) -> Result<Vec<(Episode, f64)>>

Search episodes via FTS5 full-text search.

pub fn search_entities( &self, query: &str, limit: usize, ) -> Result<Vec<(Entity, f64)>>

Search entities via FTS5.

pub fn search_fused( &self, query: &str, query_embedding: &[f32], limit: usize, ) -> Result<Vec<FusedEpisodeResult>>

Fused search using Reciprocal Rank Fusion (RRF) over FTS5 + semantic results.

query_embedding should be the pre-computed embedding for query. Returns episodes ranked by combined RRF score.

pub fn get_entity_context(&self, entity_id: &str) -> Result<EntityContext>

Get context around an entity — its neighbors and connecting edges.

pub fn traverse( &self, start_entity_id: &str, max_depth: usize, ) -> Result<(Vec<Entity>, Vec<Edge>)>

Multi-hop graph traversal from a starting entity.

Returns all entities reachable within max_depth hops and the edges connecting them.

pub fn traverse_with_history( &self, start_entity_id: &str, max_depth: usize, ) -> Result<(Vec<Entity>, Vec<Edge>)>

Multi-hop traversal including historical (invalidated) edges.

pub fn stats(&self) -> Result<GraphStats>

Get graph-wide statistics.