Trait StorageBackend 

pub trait StorageBackend: Send + Sync {
    // Required methods
    fn insert_memory(&self, memory: &MemoryNode) -> Result<(), CodememError>;
    fn get_memory(&self, id: &str) -> Result<Option<MemoryNode>, CodememError>;
    fn get_memories_batch(
        &self,
        ids: &[&str],
    ) -> Result<Vec<MemoryNode>, CodememError>;
    fn update_memory(
        &self,
        id: &str,
        content: &str,
        importance: Option<f64>,
    ) -> Result<(), CodememError>;
    fn delete_memory(&self, id: &str) -> Result<bool, CodememError>;
    fn list_memory_ids(&self) -> Result<Vec<String>, CodememError>;
    fn list_memory_ids_for_namespace(
        &self,
        namespace: &str,
    ) -> Result<Vec<String>, CodememError>;
    fn list_namespaces(&self) -> Result<Vec<String>, CodememError>;
    fn memory_count(&self) -> Result<usize, CodememError>;
    fn store_embedding(
        &self,
        memory_id: &str,
        embedding: &[f32],
    ) -> Result<(), CodememError>;
    fn get_embedding(
        &self,
        memory_id: &str,
    ) -> Result<Option<Vec<f32>>, CodememError>;
    fn delete_embedding(&self, memory_id: &str) -> Result<bool, CodememError>;
    fn list_all_embeddings(
        &self,
    ) -> Result<Vec<(String, Vec<f32>)>, CodememError>;
    fn insert_graph_node(&self, node: &GraphNode) -> Result<(), CodememError>;
    fn get_graph_node(
        &self,
        id: &str,
    ) -> Result<Option<GraphNode>, CodememError>;
    fn delete_graph_node(&self, id: &str) -> Result<bool, CodememError>;
    fn all_graph_nodes(&self) -> Result<Vec<GraphNode>, CodememError>;
    fn insert_graph_edge(&self, edge: &Edge) -> Result<(), CodememError>;
    fn get_edges_for_node(
        &self,
        node_id: &str,
    ) -> Result<Vec<Edge>, CodememError>;
    fn all_graph_edges(&self) -> Result<Vec<Edge>, CodememError>;
    fn delete_graph_edges_for_node(
        &self,
        node_id: &str,
    ) -> Result<usize, CodememError>;
    fn delete_graph_nodes_by_prefix(
        &self,
        prefix: &str,
    ) -> Result<usize, CodememError>;
    fn start_session(
        &self,
        id: &str,
        namespace: Option<&str>,
    ) -> Result<(), CodememError>;
    fn end_session(
        &self,
        id: &str,
        summary: Option<&str>,
    ) -> Result<(), CodememError>;
    fn list_sessions(
        &self,
        namespace: Option<&str>,
        limit: usize,
    ) -> Result<Vec<Session>, CodememError>;
    fn insert_consolidation_log(
        &self,
        cycle_type: &str,
        affected_count: usize,
    ) -> Result<(), CodememError>;
    fn last_consolidation_runs(
        &self,
    ) -> Result<Vec<ConsolidationLogEntry>, CodememError>;
    fn get_repeated_searches(
        &self,
        min_count: usize,
        namespace: Option<&str>,
    ) -> Result<Vec<(String, usize, Vec<String>)>, CodememError>;
    fn get_file_hotspots(
        &self,
        min_count: usize,
        namespace: Option<&str>,
    ) -> Result<Vec<(String, usize, Vec<String>)>, CodememError>;
    fn get_tool_usage_stats(
        &self,
        namespace: Option<&str>,
    ) -> Result<Vec<(String, usize)>, CodememError>;
    fn get_decision_chains(
        &self,
        min_count: usize,
        namespace: Option<&str>,
    ) -> Result<Vec<(String, usize, Vec<String>)>, CodememError>;
    fn decay_stale_memories(
        &self,
        threshold_ts: i64,
        decay_factor: f64,
    ) -> Result<usize, CodememError>;
    fn list_memories_for_creative(
        &self,
    ) -> Result<Vec<(String, String, Vec<String>)>, CodememError>;
    fn find_cluster_duplicates(
        &self,
    ) -> Result<Vec<(String, String, f64)>, CodememError>;
    fn find_forgettable(
        &self,
        importance_threshold: f64,
    ) -> Result<Vec<String>, CodememError>;
    fn find_unembedded_memories(
        &self,
    ) -> Result<Vec<(String, String)>, CodememError>;
    fn search_graph_nodes(
        &self,
        query: &str,
        namespace: Option<&str>,
        limit: usize,
    ) -> Result<Vec<GraphNode>, CodememError>;
    fn list_memories_filtered(
        &self,
        namespace: Option<&str>,
        memory_type: Option<&str>,
    ) -> Result<Vec<MemoryNode>, CodememError>;
    fn graph_edges_for_namespace(
        &self,
        namespace: &str,
    ) -> Result<Vec<Edge>, CodememError>;
    fn get_stale_memories_for_decay(
        &self,
        threshold_ts: i64,
    ) -> Result<Vec<(String, f64, u32, i64)>, CodememError>;
    fn batch_update_importance(
        &self,
        updates: &[(String, f64)],
    ) -> Result<usize, CodememError>;
    fn session_count(
        &self,
        namespace: Option<&str>,
    ) -> Result<usize, CodememError>;
    fn load_file_hashes(&self) -> Result<HashMap<String, String>, CodememError>;
    fn save_file_hashes(
        &self,
        hashes: &HashMap<String, String>,
    ) -> Result<(), CodememError>;
    fn record_session_activity(
        &self,
        session_id: &str,
        tool_name: &str,
        file_path: Option<&str>,
        directory: Option<&str>,
        pattern: Option<&str>,
    ) -> Result<(), CodememError>;
    fn get_session_activity_summary(
        &self,
        session_id: &str,
    ) -> Result<SessionActivitySummary, CodememError>;
    fn get_session_hot_directories(
        &self,
        session_id: &str,
        limit: usize,
    ) -> Result<Vec<(String, usize)>, CodememError>;
    fn has_auto_insight(
        &self,
        session_id: &str,
        dedup_tag: &str,
    ) -> Result<bool, CodememError>;
    fn count_directory_reads(
        &self,
        session_id: &str,
        directory: &str,
    ) -> Result<usize, CodememError>;
    fn was_file_read_in_session(
        &self,
        session_id: &str,
        file_path: &str,
    ) -> Result<bool, CodememError>;
    fn count_search_pattern_in_session(
        &self,
        session_id: &str,
        pattern: &str,
    ) -> Result<usize, CodememError>;
    fn stats(&self) -> Result<StorageStats, CodememError>;

    // Provided methods
    fn insert_memories_batch(
        &self,
        memories: &[MemoryNode],
    ) -> Result<(), CodememError> { ... }
    fn store_embeddings_batch(
        &self,
        items: &[(&str, &[f32])],
    ) -> Result<(), CodememError> { ... }
    fn insert_graph_nodes_batch(
        &self,
        nodes: &[GraphNode],
    ) -> Result<(), CodememError> { ... }
    fn insert_graph_edges_batch(
        &self,
        edges: &[Edge],
    ) -> Result<(), CodememError> { ... }
    fn get_edges_at_time(
        &self,
        node_id: &str,
        _timestamp: i64,
    ) -> Result<Vec<Edge>, CodememError> { ... }
}

Pluggable storage backend trait for all persistence operations.

This trait unifies memory CRUD, embedding persistence, graph node/edge storage, sessions, consolidation, and pattern detection behind a single interface. Implementations include SQLite (default) and can be extended for SurrealDB, FalkorDB, or other backends.

Required Methods

fn insert_memory(&self, memory: &MemoryNode) -> Result<(), CodememError>

Insert a new memory. Returns Err(Duplicate) if content hash already exists.

fn get_memory(&self, id: &str) -> Result<Option<MemoryNode>, CodememError>

Get a memory by ID. Updates access_count and last_accessed_at.

fn get_memories_batch( &self, ids: &[&str], ) -> Result<Vec<MemoryNode>, CodememError>

Get multiple memories by IDs in a single batch operation.

fn update_memory( &self, id: &str, content: &str, importance: Option<f64>, ) -> Result<(), CodememError>

Update a memory’s content and optionally its importance. Re-computes content hash.

fn delete_memory(&self, id: &str) -> Result<bool, CodememError>

Delete a memory by ID. Returns true if a row was deleted.

fn list_memory_ids(&self) -> Result<Vec<String>, CodememError>

List all memory IDs, ordered by created_at descending.

fn list_memory_ids_for_namespace( &self, namespace: &str, ) -> Result<Vec<String>, CodememError>

List memory IDs scoped to a specific namespace.

fn list_namespaces(&self) -> Result<Vec<String>, CodememError>

List all distinct namespaces.

fn memory_count(&self) -> Result<usize, CodememError>

Get total memory count.

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

Store an embedding vector for a memory.

fn get_embedding( &self, memory_id: &str, ) -> Result<Option<Vec<f32>>, CodememError>

Get an embedding by memory ID.

fn delete_embedding(&self, memory_id: &str) -> Result<bool, CodememError>

Delete an embedding by memory ID. Returns true if a row was deleted.

fn list_all_embeddings(&self) -> Result<Vec<(String, Vec<f32>)>, CodememError>

List all stored embeddings as (memory_id, embedding_vector) pairs.

fn insert_graph_node(&self, node: &GraphNode) -> Result<(), CodememError>

Insert or replace a graph node.

fn get_graph_node(&self, id: &str) -> Result<Option<GraphNode>, CodememError>

Get a graph node by ID.

fn delete_graph_node(&self, id: &str) -> Result<bool, CodememError>

Delete a graph node by ID. Returns true if a row was deleted.

fn all_graph_nodes(&self) -> Result<Vec<GraphNode>, CodememError>

Get all graph nodes.

fn insert_graph_edge(&self, edge: &Edge) -> Result<(), CodememError>

Insert or replace a graph edge.

fn get_edges_for_node(&self, node_id: &str) -> Result<Vec<Edge>, CodememError>

Get all edges from or to a node.

fn all_graph_edges(&self) -> Result<Vec<Edge>, CodememError>

Get all graph edges.

fn delete_graph_edges_for_node( &self, node_id: &str, ) -> Result<usize, CodememError>

Delete all graph edges connected to a node. Returns count deleted.

fn delete_graph_nodes_by_prefix( &self, prefix: &str, ) -> Result<usize, CodememError>

Delete all graph nodes, edges, and embeddings whose node ID starts with the given prefix. Returns count of nodes deleted.

fn start_session( &self, id: &str, namespace: Option<&str>, ) -> Result<(), CodememError>

Start a new session.

fn end_session( &self, id: &str, summary: Option<&str>, ) -> Result<(), CodememError>

End a session with optional summary.

fn list_sessions( &self, namespace: Option<&str>, limit: usize, ) -> Result<Vec<Session>, CodememError>

List sessions, optionally filtered by namespace, up to limit.

fn insert_consolidation_log( &self, cycle_type: &str, affected_count: usize, ) -> Result<(), CodememError>

Record a consolidation run.

fn last_consolidation_runs( &self, ) -> Result<Vec<ConsolidationLogEntry>, CodememError>

Get the last consolidation run for each cycle type.

fn get_repeated_searches( &self, min_count: usize, namespace: Option<&str>, ) -> Result<Vec<(String, usize, Vec<String>)>, CodememError>

Find repeated search patterns. Returns (pattern, count, memory_ids).

fn get_file_hotspots( &self, min_count: usize, namespace: Option<&str>, ) -> Result<Vec<(String, usize, Vec<String>)>, CodememError>

Find file hotspots. Returns (file_path, count, memory_ids).

fn get_tool_usage_stats( &self, namespace: Option<&str>, ) -> Result<Vec<(String, usize)>, CodememError>

Get tool usage statistics. Returns (tool_name, count) pairs.

fn get_decision_chains( &self, min_count: usize, namespace: Option<&str>, ) -> Result<Vec<(String, usize, Vec<String>)>, CodememError>

Find decision chains. Returns (file_path, count, memory_ids).

fn decay_stale_memories( &self, threshold_ts: i64, decay_factor: f64, ) -> Result<usize, CodememError>

Decay importance of stale memories older than threshold_ts by decay_factor. Returns count of affected memories.

fn list_memories_for_creative( &self, ) -> Result<Vec<(String, String, Vec<String>)>, CodememError>

List memories for creative consolidation: (id, memory_type, tags).

fn find_cluster_duplicates( &self, ) -> Result<Vec<(String, String, f64)>, CodememError>

Find near-duplicate memories by content hash prefix similarity. Returns (id1, id2, similarity) pairs.

fn find_forgettable( &self, importance_threshold: f64, ) -> Result<Vec<String>, CodememError>

Find memories eligible for forgetting (low importance). Returns list of memory IDs.

fn find_unembedded_memories( &self, ) -> Result<Vec<(String, String)>, CodememError>

Find memories that have no embeddings yet. Returns (id, content) pairs.

fn search_graph_nodes( &self, query: &str, namespace: Option<&str>, limit: usize, ) -> Result<Vec<GraphNode>, CodememError>

Search graph nodes by label (case-insensitive LIKE). Returns matching nodes sorted by centrality descending, limited to limit results.

fn list_memories_filtered( &self, namespace: Option<&str>, memory_type: Option<&str>, ) -> Result<Vec<MemoryNode>, CodememError>

List memories with optional namespace and memory_type filters.

fn graph_edges_for_namespace( &self, namespace: &str, ) -> Result<Vec<Edge>, CodememError>

Get edges filtered by namespace (edges where both src and dst nodes have the given namespace).

fn get_stale_memories_for_decay( &self, threshold_ts: i64, ) -> Result<Vec<(String, f64, u32, i64)>, CodememError>

Fetch stale memories with access metadata for power-law decay. Returns (id, importance, access_count, last_accessed_at).

fn batch_update_importance( &self, updates: &[(String, f64)], ) -> Result<usize, CodememError>

Batch-update importance values. Returns count of updated rows.

fn session_count(&self, namespace: Option<&str>) -> Result<usize, CodememError>

Total session count, optionally filtered by namespace.

fn load_file_hashes(&self) -> Result<HashMap<String, String>, CodememError>

Load all file hashes for incremental indexing. Returns path -> hash map.

fn save_file_hashes( &self, hashes: &HashMap<String, String>, ) -> Result<(), CodememError>

Save file hashes for incremental indexing.

fn record_session_activity( &self, session_id: &str, tool_name: &str, file_path: Option<&str>, directory: Option<&str>, pattern: Option<&str>, ) -> Result<(), CodememError>

Record a session activity event (tool use with context).

fn get_session_activity_summary( &self, session_id: &str, ) -> Result<SessionActivitySummary, CodememError>

Get a summary of session activity counts.

fn get_session_hot_directories( &self, session_id: &str, limit: usize, ) -> Result<Vec<(String, usize)>, CodememError>

Get the most active directories in a session. Returns (directory, count) pairs.

fn has_auto_insight( &self, session_id: &str, dedup_tag: &str, ) -> Result<bool, CodememError>

Check whether a particular auto-insight dedup tag already exists for a session.

fn count_directory_reads( &self, session_id: &str, directory: &str, ) -> Result<usize, CodememError>

Count how many Read events occurred in a directory during a session.

fn was_file_read_in_session( &self, session_id: &str, file_path: &str, ) -> Result<bool, CodememError>

Check if a file was read in the current session.

fn count_search_pattern_in_session( &self, session_id: &str, pattern: &str, ) -> Result<usize, CodememError>

Count how many times a search pattern was used in a session.

fn stats(&self) -> Result<StorageStats, CodememError>

Get database statistics.

Provided Methods

fn insert_memories_batch( &self, memories: &[MemoryNode], ) -> Result<(), CodememError>

Insert multiple memories in a single batch. Default impl calls insert_memory in a loop.

fn store_embeddings_batch( &self, items: &[(&str, &[f32])], ) -> Result<(), CodememError>

Store multiple embeddings in a single batch. Default impl calls store_embedding in a loop.

fn insert_graph_nodes_batch( &self, nodes: &[GraphNode], ) -> Result<(), CodememError>

Insert multiple graph nodes in a single batch. Default impl calls insert_graph_node in a loop.

fn insert_graph_edges_batch(&self, edges: &[Edge]) -> Result<(), CodememError>

Insert multiple graph edges in a single batch. Default impl calls insert_graph_edge in a loop.

fn get_edges_at_time( &self, node_id: &str, _timestamp: i64, ) -> Result<Vec<Edge>, CodememError>

Get edges active at a specific timestamp. Default: no temporal filtering.

Implementors