Struct SemanticMemory 

pub struct SemanticMemory {
    pub token_counter: Arc<TokenCounter>,
    pub graph_store: Option<Arc<GraphStore>>,
    /* private fields */
}

Fields

token_counter: Arc<TokenCounter>

graph_store: Option<Arc<GraphStore>>

Implementations

impl SemanticMemory

pub async fn store_correction_embedding( &self, correction_id: i64, correction_text: &str, ) -> Result<(), MemoryError>

Store an embedding for a user correction in the vector store.

Silently skips if no vector store is configured or embeddings are unsupported.

Errors

Returns an error if embedding generation or vector store write fails.

pub async fn retrieve_similar_corrections( &self, query: &str, limit: usize, min_score: f32, ) -> Result<Vec<UserCorrectionRow>, MemoryError>

Retrieve corrections semantically similar to query.

Returns up to limit corrections scoring above min_score. Returns an empty vec if no vector store is configured.

Errors

Returns an error if embedding generation or vector search fails.

impl SemanticMemory

pub async fn has_session_summary( &self, conversation_id: ConversationId, ) -> Result<bool, MemoryError>

Check whether a session summary already exists for the given conversation.

Returns true if at least one session summary is stored in SQLite for this conversation. Used as the primary guard in the shutdown summary path to handle cases where hard compaction fired but its Qdrant write failed (the SQLite record is the authoritative source).

Errors

Returns an error if the database query fails.

pub async fn store_shutdown_summary( &self, conversation_id: ConversationId, summary_text: &str, key_facts: &[String], ) -> Result<(), MemoryError>

Store a shutdown session summary: persists to SQLite, embeds into the zeph_session_summaries Qdrant collection (so cross-session search can find it), and stores key facts into the key-facts collection.

Unlike the hard-compaction path, first_message_id and last_message_id are None because the shutdown hook does not track exact message boundaries.

Errors

Returns an error if the SQLite insert fails. Qdrant errors are logged as warnings and do not propagate — the SQLite record is the authoritative summary store.

pub async fn store_session_summary( &self, conversation_id: ConversationId, summary_text: &str, ) -> Result<(), MemoryError>

Store a session summary into the dedicated zeph_session_summaries Qdrant collection.

Errors

Returns an error if embedding or Qdrant storage fails.

pub async fn search_session_summaries( &self, query: &str, limit: usize, exclude_conversation_id: Option<ConversationId>, ) -> Result<Vec<SessionSummaryResult>, MemoryError>

Search session summaries from other conversations.

Errors

Returns an error if embedding or Qdrant search fails.

impl SemanticMemory

pub fn spawn_graph_extraction( &self, content: String, context_messages: Vec<String>, config: GraphExtractionConfig, post_extract_validator: PostExtractValidator, ) -> JoinHandle<()>

Spawn background graph extraction for a message. Fire-and-forget — never blocks.

Extraction runs in a separate tokio task with a timeout. Any error or timeout is logged and the task exits silently; the agent response is never blocked.

The optional post_extract_validator is called after extraction, before upsert. It is a generic predicate opaque to zeph-memory (design decision D1).

When config.note_linking.enabled is true and an embedding store is available, link_memory_notes runs after successful extraction inside the same task, bounded by config.note_linking.timeout_secs.

impl SemanticMemory

pub async fn remember( &self, conversation_id: ConversationId, role: &str, content: &str, ) -> Result<MessageId, MemoryError>

Save a message to SQLite and optionally embed and store in Qdrant.

Returns the message ID assigned by SQLite.

Errors

Returns an error if the SQLite save fails. Embedding failures are logged but not propagated.

pub async fn remember_with_parts( &self, conversation_id: ConversationId, role: &str, content: &str, parts_json: &str, ) -> Result<(MessageId, bool), MemoryError>

Save a message with pre-serialized parts JSON to SQLite and optionally embed in Qdrant.

Returns (message_id, embedding_stored) tuple where embedding_stored is true if an embedding was successfully generated and stored in Qdrant.

Errors

Returns an error if the SQLite save fails.

pub async fn save_only( &self, conversation_id: ConversationId, role: &str, content: &str, parts_json: &str, ) -> Result<MessageId, MemoryError>

Save a message to SQLite without generating an embedding.

Use this when embedding is intentionally skipped (e.g. autosave disabled for assistant).

Errors

Returns an error if the SQLite save fails.

pub async fn recall( &self, query: &str, limit: usize, filter: Option<SearchFilter>, ) -> Result<Vec<RecalledMessage>, MemoryError>

Recall relevant messages using hybrid search (vector + FTS5 keyword).

When Qdrant is available, runs both vector and keyword searches, then merges results using weighted scoring. When Qdrant is unavailable, falls back to FTS5-only keyword search.

Errors

Returns an error if embedding generation, Qdrant search, or FTS5 query fails.

pub async fn recall_routed( &self, query: &str, limit: usize, filter: Option<SearchFilter>, router: &dyn MemoryRouter, ) -> Result<Vec<RecalledMessage>, MemoryError>

Recall messages using query-aware routing.

Delegates to FTS5-only, vector-only, or hybrid search based on the router decision, then runs the shared merge and ranking pipeline.

Errors

Returns an error if any underlying search or database operation fails.

pub async fn recall_graph( &self, query: &str, limit: usize, max_hops: u32, at_timestamp: Option<&str>, temporal_decay_rate: f64, edge_types: &[EdgeType], ) -> Result<Vec<GraphFact>, MemoryError>

Retrieve graph facts relevant to query via BFS traversal.

Returns an empty Vec if no graph_store is configured.

Parameters

• at_timestamp: when Some, only edges valid at that SQLite datetime string are returned. When None, only currently active edges are used.
• temporal_decay_rate: non-negative decay rate (1/day). 0.0 preserves original ordering.

Errors

Returns an error if the underlying graph query fails.

pub async fn recall_graph_activated( &self, query: &str, limit: usize, params: SpreadingActivationParams, edge_types: &[EdgeType], ) -> Result<Vec<ActivatedFact>, MemoryError>

Retrieve graph facts via SYNAPSE spreading activation.

Delegates to crate::graph::retrieval::graph_recall_activated. Used in place of [recall_graph] when spreading_activation.enabled = true.

Errors

Returns an error if the underlying graph query fails.

pub async fn has_embedding( &self, message_id: MessageId, ) -> Result<bool, MemoryError>

Check whether an embedding exists for a given message ID.

Errors

Returns an error if the SQLite query fails.

pub async fn embed_missing(&self) -> Result<usize, MemoryError>

Embed all messages that do not yet have embeddings.

Returns the count of successfully embedded messages.

Errors

Returns an error if collection initialization or database query fails. Individual embedding failures are logged but do not stop processing.

impl SemanticMemory

pub async fn load_summaries( &self, conversation_id: ConversationId, ) -> Result<Vec<Summary>, MemoryError>

Load all summaries for a conversation.

Errors

Returns an error if the query fails.

pub async fn summarize( &self, conversation_id: ConversationId, message_count: usize, ) -> Result<Option<i64>, MemoryError>

Generate a summary of the oldest unsummarized messages.

Returns Ok(None) if there are not enough messages to summarize.

Errors

Returns an error if LLM call or database operation fails.

pub async fn search_key_facts( &self, query: &str, limit: usize, ) -> Result<Vec<String>, MemoryError>

Search key facts extracted from conversation summaries.

Errors

Returns an error if embedding or Qdrant search fails.

pub async fn search_document_collection( &self, collection: &str, query: &str, limit: usize, ) -> Result<Vec<ScoredVectorPoint>, MemoryError>

Search a named document collection by semantic similarity.

Returns up to limit scored vector points whose payloads contain ingested document chunks. Returns an empty vec when Qdrant is unavailable, the collection does not exist, or the provider does not support embeddings.

Errors

Returns an error if embedding generation or Qdrant search fails.

impl SemanticMemory

pub async fn new( sqlite_path: &str, qdrant_url: &str, provider: AnyProvider, embedding_model: &str, ) -> Result<Self, MemoryError>

Create a new SemanticMemory instance with default hybrid search weights (0.7/0.3).

Qdrant connection is best-effort: if unavailable, semantic search is disabled.

For AppBuilder bootstrap, prefer SemanticMemory::with_qdrant_ops to share a single gRPC channel across all subsystems.

Errors

Returns an error if SQLite cannot be initialized.

pub async fn with_weights( sqlite_path: &str, qdrant_url: &str, provider: AnyProvider, embedding_model: &str, vector_weight: f64, keyword_weight: f64, ) -> Result<Self, MemoryError>

Create a new SemanticMemory with custom vector/keyword weights for hybrid search.

For AppBuilder bootstrap, prefer SemanticMemory::with_qdrant_ops to share a single gRPC channel across all subsystems.

Errors

Returns an error if SQLite cannot be initialized.

pub async fn with_weights_and_pool_size( sqlite_path: &str, qdrant_url: &str, provider: AnyProvider, embedding_model: &str, vector_weight: f64, keyword_weight: f64, pool_size: u32, ) -> Result<Self, MemoryError>

Create a new SemanticMemory with custom weights and configurable pool size.

For AppBuilder bootstrap, prefer SemanticMemory::with_qdrant_ops to share a single gRPC channel across all subsystems.

Errors

Returns an error if SQLite cannot be initialized.

pub async fn with_qdrant_ops( sqlite_path: &str, ops: QdrantOps, provider: AnyProvider, embedding_model: &str, vector_weight: f64, keyword_weight: f64, pool_size: u32, ) -> Result<Self, MemoryError>

Create a SemanticMemory from a pre-built QdrantOps instance.

Use this at bootstrap to share one QdrantOps (and thus one gRPC channel) across all subsystems. The ops is consumed and wrapped inside EmbeddingStore.

Errors

Returns an error if SQLite cannot be initialized.

pub fn with_graph_store(self, store: Arc<GraphStore>) -> Self

Attach a GraphStore for graph-aware retrieval.

When set, recall_graph traverses the graph starting from entities matched by the query.

pub fn community_detection_failures(&self) -> u64

Returns the cumulative count of community detection failures since startup.

pub fn graph_extraction_count(&self) -> u64

Returns the cumulative count of successful graph extractions since startup.

pub fn graph_extraction_failures(&self) -> u64

Returns the cumulative count of failed graph extractions since startup.

pub fn with_ranking_options( self, temporal_decay_enabled: bool, temporal_decay_half_life_days: u32, mmr_enabled: bool, mmr_lambda: f32, ) -> Self

Configure temporal decay and MMR re-ranking options.

pub fn with_importance_options(self, enabled: bool, weight: f64) -> Self

Configure write-time importance scoring for memory retrieval.

pub fn from_parts( sqlite: SqliteStore, qdrant: Option<Arc<EmbeddingStore>>, provider: AnyProvider, embedding_model: impl Into<String>, vector_weight: f64, keyword_weight: f64, token_counter: Arc<TokenCounter>, ) -> Self

Construct a SemanticMemory from pre-built parts.

Intended for tests that need full control over the backing stores.

pub async fn with_sqlite_backend( sqlite_path: &str, provider: AnyProvider, embedding_model: &str, vector_weight: f64, keyword_weight: f64, ) -> Result<Self, MemoryError>

Create a SemanticMemory using the SQLite-embedded vector backend.

Errors

Returns an error if SQLite cannot be initialized.

pub async fn with_sqlite_backend_and_pool_size( sqlite_path: &str, provider: AnyProvider, embedding_model: &str, vector_weight: f64, keyword_weight: f64, pool_size: u32, ) -> Result<Self, MemoryError>

Create a SemanticMemory using the SQLite-embedded vector backend with configurable pool size.

Errors

Returns an error if SQLite cannot be initialized.

pub fn sqlite(&self) -> &SqliteStore

Access the underlying SqliteStore for operations that don’t involve semantics.

pub async fn is_vector_store_connected(&self) -> bool

Check if the vector store backend is reachable.

Performs a real health check (Qdrant gRPC ping or SQLite query) instead of just checking whether the client was created.

pub fn has_vector_store(&self) -> bool

Check if a vector store client is configured (may not be connected).

pub fn embedding_store(&self) -> Option<&Arc<EmbeddingStore>>

Return a reference to the embedding store, if configured.

pub async fn message_count( &self, conversation_id: ConversationId, ) -> Result<i64, MemoryError>

Count messages in a conversation.

Errors

Returns an error if the query fails.

pub async fn unsummarized_message_count( &self, conversation_id: ConversationId, ) -> Result<i64, MemoryError>

Count messages not yet covered by any summary.

Errors

Returns an error if the query fails.