Trait GraphBackend 

pub trait GraphBackend: Send + Sync {
    // Required methods
    fn store_entity(&self, entity: &Entity) -> Result<()>;
    fn get_entity(&self, id: &EntityId) -> Result<Option<Entity>>;
    fn query_entities(&self, query: &EntityQuery) -> Result<Vec<Entity>>;
    fn delete_entity(&self, id: &EntityId) -> Result<bool>;
    fn merge_entities(
        &self,
        entity_ids: &[EntityId],
        canonical_name: &str,
    ) -> Result<Entity>;
    fn find_entities_by_name(
        &self,
        name: &str,
        entity_type: Option<EntityType>,
        domain: Option<&Domain>,
        limit: usize,
    ) -> Result<Vec<Entity>>;
    fn store_relationship(&self, relationship: &Relationship) -> Result<()>;
    fn query_relationships(
        &self,
        query: &RelationshipQuery,
    ) -> Result<Vec<Relationship>>;
    fn delete_relationships(&self, query: &RelationshipQuery) -> Result<usize>;
    fn get_relationship_types(
        &self,
        from_entity: &EntityId,
        to_entity: &EntityId,
    ) -> Result<Vec<RelationshipType>>;
    fn store_mention(&self, mention: &EntityMention) -> Result<()>;
    fn get_mentions_for_entity(
        &self,
        entity_id: &EntityId,
    ) -> Result<Vec<EntityMention>>;
    fn get_entities_in_memory(
        &self,
        memory_id: &MemoryId,
    ) -> Result<Vec<Entity>>;
    fn delete_mentions_for_entity(&self, entity_id: &EntityId) -> Result<usize>;
    fn delete_mentions_for_memory(&self, memory_id: &MemoryId) -> Result<usize>;
    fn traverse(
        &self,
        start: &EntityId,
        max_depth: u32,
        relationship_types: Option<&[RelationshipType]>,
        min_confidence: Option<f32>,
    ) -> Result<TraversalResult>;
    fn find_path(
        &self,
        from: &EntityId,
        to: &EntityId,
        max_depth: u32,
    ) -> Result<Option<TraversalResult>>;
    fn query_entities_at(
        &self,
        query: &EntityQuery,
        point: &BitemporalPoint,
    ) -> Result<Vec<Entity>>;
    fn query_relationships_at(
        &self,
        query: &RelationshipQuery,
        point: &BitemporalPoint,
    ) -> Result<Vec<Relationship>>;
    fn close_entity_valid_time(
        &self,
        id: &EntityId,
        end_time: i64,
    ) -> Result<()>;
    fn close_relationship_valid_time(
        &self,
        from_entity: &EntityId,
        to_entity: &EntityId,
        relationship_type: RelationshipType,
        end_time: i64,
    ) -> Result<()>;
    fn get_stats(&self) -> Result<GraphStats>;
    fn clear(&self) -> Result<()>;

    // Provided method
    fn get_related_entities(
        &self,
        entity_id: &EntityId,
        max_depth: u32,
        limit: usize,
    ) -> Result<Vec<Entity>> { ... }
}

Trait for graph layer backends.

Graph backends provide entity and relationship storage for knowledge graph construction, with support for temporal queries and graph traversal.

Implementor Notes

• Methods use &self to enable sharing via Arc<dyn GraphBackend>
• Use interior mutability (e.g., Mutex<Connection>) for mutable state
• Implement traverse() with recursive CTEs or similar for efficient multi-hop queries
• Support bitemporal filtering on all query methods
• Entity deletion should cascade to relationships (or return error if referenced)

Required Methods

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

Stores an entity in the graph.

If an entity with the same ID exists, it is updated. Uses interior mutability for thread-safe concurrent access.

Errors

Returns an error if the storage operation fails.

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

Retrieves an entity by ID.

Errors

Returns an error if the lookup operation fails.

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

Queries entities with optional filters.

Returns entities matching the query criteria, ordered by relevance (mention count, confidence, or recency depending on query).

Errors

Returns an error if the query operation fails.

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

Deletes an entity by ID.

This also removes all relationships involving the entity and all entity mentions.

Returns true if the entity was deleted, false if not found.

Errors

Returns an error if the deletion operation fails.

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

Merges multiple entities into a canonical entity.

The first entity ID becomes the canonical entity. All relationships from the other entities are re-pointed to the canonical entity, and the other entities are deleted.

Arguments

• entity_ids - Entity IDs to merge (first is canonical)
• canonical_name - New canonical name for the merged entity

Errors

Returns an error if any entity is not found or the merge fails.

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

Finds entities by name using fuzzy matching.

Searches both canonical names and aliases.

Errors

Returns an error if the search operation fails.

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

Stores a relationship in the graph.

If a relationship between the same entities with the same type exists, it may be updated or a new version created (depending on temporal settings).

Errors

Returns an error if the storage operation fails or if either entity referenced by the relationship does not exist.

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

Queries relationships with optional filters.

Returns relationships matching the query criteria.

Errors

Returns an error if the query operation fails.

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

Deletes relationships matching the query.

Returns the number of relationships deleted.

Errors

Returns an error if the deletion operation fails.

fn get_relationship_types( &self, from_entity: &EntityId, to_entity: &EntityId, ) -> Result<Vec<RelationshipType>>

Gets all relationship types between two entities.

Errors

Returns an error if the query operation fails.

fn store_mention(&self, mention: &EntityMention) -> Result<()>

Stores an entity mention (link between entity and memory).

Errors

Returns an error if the storage operation fails.

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

Gets all mentions of an entity.

Returns memory IDs where the entity was mentioned, with confidence scores.

Errors

Returns an error if the query operation fails.

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 operation fails.

fn delete_mentions_for_entity(&self, entity_id: &EntityId) -> Result<usize>

Deletes all mentions of an entity.

Returns the number of mentions deleted.

Errors

Returns an error if the deletion operation fails.

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

Deletes all entity mentions for a memory.

Returns the number of mentions deleted.

Errors

Returns an error if the deletion operation fails.

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 traversal up to max_depth hops, collecting all reachable entities and the relationships used to reach them.

Arguments

• start - Starting entity ID
• max_depth - Maximum traversal depth (1 = immediate neighbors)
• relationship_types - Optional filter for relationship types
• min_confidence - Minimum confidence threshold for relationships

Errors

Returns an error if the traversal operation fails.

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

Finds the shortest path between two entities.

Returns None if no path exists within max_depth.

Errors

Returns an error if the operation fails.

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

Queries entities at a specific point in bitemporal space.

Returns entities that were valid at point.valid_at and were known to the system as of point.as_of.

Errors

Returns an error if the query operation fails.

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

Queries relationships at a specific point in bitemporal space.

Errors

Returns an error if the query operation fails.

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

Closes (ends) an entity’s valid time at the given timestamp.

This marks the entity as no longer valid from the given time forward, without deleting historical data.

Errors

Returns an error if the entity is not found or the operation fails.

fn close_relationship_valid_time( &self, from_entity: &EntityId, to_entity: &EntityId, relationship_type: RelationshipType, end_time: i64, ) -> Result<()>

Closes (ends) a relationship’s valid time at the given timestamp.

Errors

Returns an error if the relationship is not found or the operation fails.

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

Returns statistics about the graph.

Errors

Returns an error if the operation fails.

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

Clears all graph data.

Use with caution - this removes all entities, relationships, and mentions.

Errors

Returns an error if the operation fails.

Provided Methods

fn get_related_entities( &self, entity_id: &EntityId, max_depth: u32, limit: usize, ) -> Result<Vec<Entity>>

Gets entities related to a given entity within N hops.

Convenience method combining traversal with entity extraction.

Errors

Returns an error if the operation fails.

Implementors

impl GraphBackend for InMemoryGraphBackend

impl GraphBackend for SqliteGraphBackend