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 find_memory_ids_by_tag(
        &self,
        tag: &str,
        namespace: Option<&str>,
        exclude_id: &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_hash_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_by_tag(
        &self,
        tag: &str,
        namespace: Option<&str>,
        limit: usize,
    ) -> Result<Vec<MemoryNode>, CodememError>;
    fn list_memories_filtered(
        &self,
        namespace: Option<&str>,
        memory_type: Option<&str>,
    ) -> Result<Vec<MemoryNode>, 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 list_repos(&self) -> Result<Vec<Repository>, CodememError>;
    fn add_repo(&self, repo: &Repository) -> Result<(), CodememError>;
    fn get_repo(&self, id: &str) -> Result<Option<Repository>, CodememError>;
    fn remove_repo(&self, id: &str) -> Result<bool, CodememError>;
    fn update_repo_status(
        &self,
        id: &str,
        status: &str,
        indexed_at: Option<&str>,
    ) -> Result<(), CodememError>;
    fn stats(&self) -> Result<StorageStats, CodememError>;

    // Provided methods
    fn get_memory_no_touch(
        &self,
        id: &str,
    ) -> Result<Option<MemoryNode>, CodememError> { ... }
    fn delete_memory_cascade(&self, id: &str) -> Result<bool, CodememError> { ... }
    fn delete_memories_batch_cascade(
        &self,
        ids: &[&str],
    ) -> Result<usize, CodememError> { ... }
    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 begin_transaction(&self) -> Result<(), CodememError> { ... }
    fn commit_transaction(&self) -> Result<(), CodememError> { ... }
    fn rollback_transaction(&self) -> Result<(), CodememError> { ... }
}

Pluggable storage backend trait for all persistence operations.

This trait unifies every persistence concern behind a single interface so that the engine layer (CodememEngine) remains backend-agnostic.

Method groups

Group	Methods	Purpose
Memory CRUD	insert_memory, get_memory, update_memory, delete_memory, list_memory_ids, …	Create, read, update, delete memory nodes
Embedding persistence	store_embedding, get_embedding, delete_embedding, list_all_embeddings	Persist and retrieve embedding vectors
Graph node/edge storage	insert_graph_node, get_graph_node, all_graph_nodes, insert_graph_edge, …	Persist the knowledge graph structure
Sessions	start_session, end_session, list_sessions, session_count	Track interaction sessions
Consolidation	insert_consolidation_log, last_consolidation_runs	Record and query memory consolidation runs
Pattern detection	get_repeated_searches, get_file_hotspots, get_tool_usage_stats, get_decision_chains	Cross-session pattern queries
Bulk/batch operations	insert_memories_batch, store_embeddings_batch, insert_graph_nodes_batch, insert_graph_edges_batch	Efficient multi-row inserts
Decay & forgetting	decay_stale_memories, find_forgettable, get_stale_memories_for_decay, batch_update_importance	Power-law decay and garbage collection
Query helpers	find_unembedded_memories, search_graph_nodes, list_memories_filtered, find_hash_duplicates	Filtered searches and dedup
File hash tracking	load_file_hashes, save_file_hashes	Incremental indexing support
Session activity	record_session_activity, get_session_activity_summary, get_session_hot_directories, …	Fine-grained activity tracking
Stats	stats	Database-level statistics

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 find_memory_ids_by_tag( &self, tag: &str, namespace: Option<&str>, exclude_id: &str, ) -> Result<Vec<String>, CodememError>

Find memory IDs whose tags contain the given tag value. Optionally scoped to a namespace. Excludes exclude_id.

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_hash_duplicates( &self, ) -> Result<Vec<(String, String, f64)>, CodememError>

Find near-duplicate memories by content hash prefix matching. Returns (id1, id2, similarity) pairs. Only catches exact content matches (hash prefix), not semantic near-duplicates.

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_by_tag( &self, tag: &str, namespace: Option<&str>, limit: usize, ) -> Result<Vec<MemoryNode>, CodememError>

List memories matching a specific tag, with optional namespace filter.

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 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 list_repos(&self) -> Result<Vec<Repository>, CodememError>

List all registered repositories.

fn add_repo(&self, repo: &Repository) -> Result<(), CodememError>

Add a new repository.

fn get_repo(&self, id: &str) -> Result<Option<Repository>, CodememError>

Get a repository by ID.

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

Remove a repository by ID. Returns true if it existed.

fn update_repo_status( &self, id: &str, status: &str, indexed_at: Option<&str>, ) -> Result<(), CodememError>

Update a repository’s status and optionally its last-indexed timestamp.

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

Get database statistics.

Provided Methods

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

Get a memory by ID without updating access_count or last_accessed_at. Use this for internal/system reads (consolidation checks, stats, batch processing).

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

Delete a memory and all related data (graph nodes/edges, embeddings) atomically. Returns true if the memory existed and was deleted. Default falls back to individual deletes (non-transactional) for backwards compatibility.

fn delete_memories_batch_cascade( &self, ids: &[&str], ) -> Result<usize, CodememError>

Delete multiple memories and all related data (graph nodes/edges, embeddings) atomically. Returns the number of memories that were actually deleted. Default falls back to calling delete_memory_cascade per ID for backwards compatibility.

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 begin_transaction(&self) -> Result<(), CodememError>

Begin an explicit transaction.

While a transaction is active, individual storage methods (e.g. insert_memory, insert_graph_node) participate in it instead of starting their own. Call commit_transaction to persist or rollback_transaction to discard.

Default implementation is a no-op for backends that don’t support explicit transaction control.

fn commit_transaction(&self) -> Result<(), CodememError>

Commit the active transaction started by begin_transaction.

Default implementation is a no-op.

fn rollback_transaction(&self) -> Result<(), CodememError>

Roll back the active transaction started by begin_transaction.

Default implementation is a no-op.

Implementors