Struct GraphService 

pub struct GraphService<B: GraphBackend> {
    backend: Arc<B>,
}

High-level service for knowledge graph operations.

Wraps a GraphBackend and provides:

• Entity CRUD with deduplication hints
• Relationship management
• Graph traversal and path finding
• Integration with memory system

Thread Safety

The service is thread-safe when the underlying backend is thread-safe. Both SqliteGraphBackend and InMemoryGraphBackend are thread-safe.

Fields

backend: Arc<B>

Implementations

impl<B: GraphBackend> GraphService<B>

pub fn new(backend: B) -> Self

Creates a new graph service with the given backend.

pub const fn with_shared_backend(backend: Arc<B>) -> Self

Creates a new graph service with a shared backend.

pub fn backend(&self) -> &B

Returns a reference to the underlying backend.

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

Stores an entity in the graph.

If an entity with the same ID exists, it will be updated.

Errors

Returns an error if the storage operation fails.

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

Retrieves an entity by ID.

Returns

Some(entity) if found, None otherwise.

Errors

Returns an error if the retrieval fails.

pub fn query_entities(&self, query: &EntityQuery) -> Result<Vec<Entity>>

Queries entities matching the given criteria.

Errors

Returns an error if the query fails.

pub fn find_by_type( &self, entity_type: EntityType, limit: usize, ) -> Result<Vec<Entity>>

Finds entities by type with a limit.

Convenience method for common entity type queries.

Errors

Returns an error if the query fails.

pub fn find_by_name( &self, name: &str, entity_type: Option<EntityType>, domain: Option<&Domain>, limit: usize, ) -> Result<Vec<Entity>>

Finds entities by name with optional type and domain filtering.

Performs case-insensitive partial matching on entity names and aliases.

Errors

Returns an error if the search fails.

pub fn delete_entity(&self, id: &EntityId) -> Result<bool>

Deletes an entity and its relationships/mentions.

Returns

true if the entity existed and was deleted.

Errors

Returns an error if the deletion fails.

pub fn merge_entities( &self, entity_ids: &[EntityId], canonical_name: &str, ) -> Result<Entity>

Merges multiple entities into one canonical entity.

The first entity ID becomes the canonical entity. All relationships and mentions from other entities are redirected to the canonical entity.

Arguments

• entity_ids - IDs of entities to merge (first is canonical)
• canonical_name - The name for the merged entity

Returns

The merged entity.

Errors

Returns an error if:

• No entity IDs provided
• Canonical entity not found
• Merge operation fails

pub fn find_duplicates( &self, entity: &Entity, threshold: f32, ) -> Result<Vec<Entity>>

Finds potential duplicate entities based on name similarity.

Returns entities that may be duplicates of the given entity, useful for deduplication workflows.

Errors

Returns an error if the search fails.

pub fn store_relationship(&self, relationship: &Relationship) -> Result<()>

Stores a relationship between entities.

If a relationship with the same (from, to, type) exists, it will be updated.

Errors

Returns an error if the storage operation fails.

pub fn relate( &self, from: &EntityId, to: &EntityId, relationship_type: RelationshipType, ) -> Result<Relationship>

Creates a relationship between two entities.

Convenience method that creates and stores a relationship.

Errors

Returns an error if:

• Either entity doesn’t exist
• Storage operation fails

pub fn query_relationships( &self, query: &RelationshipQuery, ) -> Result<Vec<Relationship>>

Queries relationships matching the given criteria.

Errors

Returns an error if the query fails.

pub fn get_outgoing_relationships( &self, entity_id: &EntityId, ) -> Result<Vec<Relationship>>

Gets all relationships from an entity.

Errors

Returns an error if the query fails.

pub fn get_incoming_relationships( &self, entity_id: &EntityId, ) -> Result<Vec<Relationship>>

Gets all relationships to an entity.

Errors

Returns an error if the query fails.

pub fn delete_relationships(&self, query: &RelationshipQuery) -> Result<usize>

Deletes relationships matching the query.

Returns

Number of relationships deleted.

Errors

Returns an error if the deletion fails.

pub fn get_relationship_types( &self, from: &EntityId, to: &EntityId, ) -> Result<Vec<RelationshipType>>

Gets all relationship types between two entities.

Errors

Returns an error if the query fails.

pub fn record_mention( &self, entity_id: &EntityId, memory_id: &MemoryId, ) -> Result<()>

Records an entity mention in a memory.

Errors

Returns an error if the storage operation fails.

pub fn get_mentions(&self, entity_id: &EntityId) -> Result<Vec<EntityMention>>

Gets all mentions of an entity.

Errors

Returns an error if the query fails.

pub fn get_entities_in_memory( &self, memory_id: &MemoryId, ) -> Result<Vec<Entity>>

Gets all entities mentioned in a memory.

Errors

Returns an error if the query fails.

pub fn remove_mentions_for_memory(&self, memory_id: &MemoryId) -> Result<usize>

Removes entity mentions when a memory is deleted.

Returns

Number of mentions removed.

Errors

Returns an error if the deletion fails.

pub fn traverse( &self, start: &EntityId, max_depth: u32, relationship_types: Option<&[RelationshipType]>, min_confidence: Option<f32>, ) -> Result<TraversalResult>

Traverses the graph from a starting entity.

Performs breadth-first search up to the specified depth.

Arguments

• start - Starting entity ID
• max_depth - Maximum traversal depth
• relationship_types - Optional filter for relationship types
• min_confidence - Optional minimum confidence threshold

Returns

Entities and relationships discovered during traversal.

Errors

Returns an error if the traversal fails.

pub fn find_path( &self, from: &EntityId, to: &EntityId, max_depth: u32, ) -> Result<Option<TraversalResult>>

Finds the shortest path between two entities.

Arguments

• from - Starting entity ID
• to - Target entity ID
• max_depth - Maximum path length

Returns

Some(result) with the path if found, None otherwise.

Errors

Returns an error if the search fails.

pub fn get_neighbors( &self, entity_id: &EntityId, depth: u32, ) -> Result<Vec<Entity>>

Gets neighbors of an entity within a given depth.

Convenience method for single-depth traversal.

Errors

Returns an error if the traversal fails.

pub fn query_entities_at( &self, query: &EntityQuery, point: &BitemporalPoint, ) -> Result<Vec<Entity>>

Queries entities at a specific point in time.

Uses bitemporal filtering to find entities that were:

• Valid at the specified time (valid_at)
• Known in the system at the specified time (as_of)

Errors

Returns an error if the query fails.

pub fn query_relationships_at( &self, query: &RelationshipQuery, point: &BitemporalPoint, ) -> Result<Vec<Relationship>>

Queries relationships at a specific point in time.

Errors

Returns an error if the query fails.

pub fn close_entity_valid_time( &self, id: &EntityId, end_time: i64, ) -> Result<()>

Closes an entity’s valid time (marks it as no longer valid).

Used when an entity is superseded or becomes invalid.

Errors

Returns an error if the entity doesn’t exist or update fails.

pub fn close_relationship_valid_time( &self, from: &EntityId, to: &EntityId, relationship_type: RelationshipType, end_time: i64, ) -> Result<()>

Closes a relationship’s valid time.

Errors

Returns an error if the relationship doesn’t exist or update fails.

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

Gets graph statistics.

Errors

Returns an error if the statistics cannot be retrieved.

pub fn clear(&self) -> Result<()>

Clears all graph data.

Warning: This permanently deletes all entities, relationships, and mentions.

Errors

Returns an error if the clear operation fails.