Struct MemoryStore 

pub struct MemoryStore { /* private fields */ }

Thread-safe handle to the memory database.

Clone is cheap (Arc internals). Send + Sync.

Implementations

impl MemoryStore

pub async fn create_session(&self, channel: &str) -> Result<String, MemoryError>

Create a new conversation session. Returns the session ID (UUID v4).

pub async fn create_session_with_metadata( &self, channel: &str, metadata: Option<Value>, ) -> Result<String, MemoryError>

Create a new conversation session with metadata.

Metadata can be used to carry namespace tags and trace data for retention and deletion policy decisions.

pub async fn rename_session( &self, session_id: &str, new_channel: &str, ) -> Result<(), MemoryError>

Rename a session’s channel (display name).

pub async fn list_sessions( &self, limit: usize, offset: usize, ) -> Result<Vec<Session>, MemoryError>

List recent sessions, newest first.

pub async fn delete_session(&self, session_id: &str) -> Result<(), MemoryError>

Delete a session and all its messages.

Cleans up HNSW entries for embedded messages before CASCADE delete.

pub async fn add_message( &self, session_id: &str, role: Role, content: &str, token_count: Option<u32>, metadata: Option<Value>, ) -> Result<i64, MemoryError>

Append a message to a session. Returns the message’s auto-increment ID.

pub async fn add_message_with_trace( &self, session_id: &str, role: Role, content: &str, token_count: Option<u32>, metadata: Option<Value>, trace_ctx: Option<&TraceCtx>, ) -> Result<i64, MemoryError>

Append a message to a session with optional trace metadata.

pub async fn add_message_fts( &self, session_id: &str, role: Role, content: &str, token_count: Option<u32>, metadata: Option<Value>, ) -> Result<i64, MemoryError>

Append a message to a session with FTS indexing but no embedding.

Fallback path when embedding fails: messages still appear in conversation history and are findable via BM25 search, just not via vector search.

pub async fn add_message_fts_with_trace( &self, session_id: &str, role: Role, content: &str, token_count: Option<u32>, metadata: Option<Value>, trace_ctx: Option<&TraceCtx>, ) -> Result<i64, MemoryError>

Append a message with FTS indexing and optional trace metadata.

pub async fn get_recent_messages( &self, session_id: &str, limit: usize, ) -> Result<Vec<Message>, MemoryError>

Get the most recent N messages from a session, in chronological order.

pub async fn get_messages_within_budget( &self, session_id: &str, max_tokens: u32, ) -> Result<Vec<Message>, MemoryError>

Get messages from a session up to max_tokens total.

pub async fn session_token_count( &self, session_id: &str, ) -> Result<u64, MemoryError>

Get total token count for a session.

pub async fn add_message_embedded( &self, session_id: &str, role: Role, content: &str, token_count: Option<u32>, metadata: Option<Value>, ) -> Result<i64, MemoryError>

Append a message to a session with automatic embedding and FTS indexing.

pub async fn add_message_embedded_with_trace( &self, session_id: &str, role: Role, content: &str, token_count: Option<u32>, metadata: Option<Value>, trace_ctx: Option<&TraceCtx>, ) -> Result<i64, MemoryError>

Append an embedded message with optional trace metadata.

pub async fn search_conversations( &self, query: &str, top_k: Option<usize>, session_ids: Option<&[&str]>, ) -> Result<Vec<SearchResult>, MemoryError>

Hybrid search over conversation messages only.

impl MemoryStore

pub async fn ingest_document( &self, title: &str, content: &str, namespace: &str, source_path: Option<&str>, metadata: Option<Value>, ) -> Result<String, MemoryError>

Ingest a document: chunk, embed all chunks, store everything.

pub async fn ingest_document_with_trace( &self, title: &str, content: &str, namespace: &str, source_path: Option<&str>, metadata: Option<Value>, trace_ctx: Option<&TraceCtx>, ) -> Result<String, MemoryError>

Ingest a document with optional trace metadata.

pub async fn delete_document( &self, document_id: &str, ) -> Result<(), MemoryError>

Delete a document and all its chunks.

pub async fn list_documents( &self, namespace: &str, limit: usize, offset: usize, ) -> Result<Vec<Document>, MemoryError>

List documents in a namespace.

pub async fn count_chunks_for_document( &self, document_id: &str, ) -> Result<usize, MemoryError>

Count the number of chunks for a document.

pub async fn filter_search_results_by_scope( &self, results: Vec<SearchResult>, scope: &ScopeKey, ) -> Result<Vec<SearchResult>, MemoryError>

Filter search results to those whose source scope exactly matches the requested scope.

Only source families that carry or can be joined to full scope metadata are retained: chunks, episodes, and imported projection rows. Facts and messages are excluded because they do not carry domain/workspace/repo provenance.

impl MemoryStore

pub async fn ingest_episode( &self, document_id: &str, meta: &EpisodeMeta, ) -> Result<String, MemoryError>

Ingest or update a causal episode attached to a document.

The document must already exist. Existing episodes keep their original created_at timestamp while their searchable text, outcome state, verification metadata, embeddings, and updated_at are refreshed.

pub async fn ingest_episode_with_trace( &self, document_id: &str, meta: &EpisodeMeta, trace_ctx: Option<&TraceCtx>, ) -> Result<String, MemoryError>

Ingest a causal episode with optional trace metadata. Returns the episode_id.

pub async fn create_episode( &self, episode_id: &str, document_id: &str, meta: &EpisodeMeta, ) -> Result<String, MemoryError>

Create a new episode with an explicit episode_id. Returns the episode_id.

pub async fn create_episode_with_trace( &self, episode_id: &str, document_id: &str, meta: &EpisodeMeta, trace_ctx: Option<&TraceCtx>, ) -> Result<String, MemoryError>

Create a new episode with an explicit episode_id and optional trace metadata.

pub async fn get_episode( &self, episode_id: &str, ) -> Result<Option<(String, EpisodeMeta)>, MemoryError>

Retrieve an episode by its episode_id.

pub async fn update_episode_outcome_by_id( &self, episode_id: &str, outcome: EpisodeOutcome, confidence: f32, experiment_id: Option<&str>, ) -> Result<(), MemoryError>

Update the outcome of an episode by its episode_id.

pub async fn update_episode_outcome( &self, document_id: &str, outcome: EpisodeOutcome, confidence: f32, experiment_id: Option<&str>, ) -> Result<(), MemoryError>

Update the outcome of an existing episode.

pub async fn search_episodes( &self, effect_type: Option<&str>, outcome: Option<&EpisodeOutcome>, limit: usize, ) -> Result<Vec<(String, EpisodeMeta)>, MemoryError>

Search for episodes by effect_type and/or outcome.

impl MemoryStore

pub async fn add_fact( &self, namespace: &str, content: &str, source: Option<&str>, metadata: Option<Value>, ) -> Result<String, MemoryError>

Store a fact with automatic embedding. Returns the fact ID (UUID v4).

pub async fn add_fact_with_trace( &self, namespace: &str, content: &str, source: Option<&str>, metadata: Option<Value>, trace_ctx: Option<&TraceCtx>, ) -> Result<String, MemoryError>

Store a fact with automatic embedding and optional trace metadata.

pub async fn add_fact_with_embedding( &self, namespace: &str, content: &str, embedding: &[f32], source: Option<&str>, metadata: Option<Value>, ) -> Result<String, MemoryError>

Store a fact with a pre-computed embedding.

pub async fn add_fact_with_embedding_and_trace( &self, namespace: &str, content: &str, embedding: &[f32], source: Option<&str>, metadata: Option<Value>, trace_ctx: Option<&TraceCtx>, ) -> Result<String, MemoryError>

Store a fact with a pre-computed embedding and optional trace metadata.

pub async fn update_fact( &self, fact_id: &str, content: &str, ) -> Result<(), MemoryError>

Update a fact’s content. Re-embeds automatically.

pub async fn delete_fact(&self, fact_id: &str) -> Result<(), MemoryError>

Delete a fact by ID.

pub async fn delete_namespace( &self, namespace: &str, ) -> Result<usize, MemoryError>

Delete all facts in a namespace. Returns the count of deleted facts.

pub async fn get_fact(&self, fact_id: &str) -> Result<Option<Fact>, MemoryError>

Get a fact by ID.

pub async fn get_fact_embedding( &self, fact_id: &str, ) -> Result<Option<Vec<f32>>, MemoryError>

Get a fact’s embedding vector.

pub async fn list_facts( &self, namespace: &str, limit: usize, offset: usize, ) -> Result<Vec<Fact>, MemoryError>

List all facts in a namespace.

impl MemoryStore

pub async fn invalidate_derivations( &self, source_kind: &str, source_id: &str, trigger_mode: &str, reason: &str, ) -> Result<usize, MemoryError>

Invalidate derivation edges matching a trigger mode, bounded by source artifact.

Returns the number of edges invalidated. This enables bounded recomputation: only derived artifacts downstream of the specified source are affected.

impl MemoryStore

pub async fn import_projection_batch<B: ProjectionImportBatchLike>( &self, batch: &B, ) -> Result<ProjectionImportResult, MemoryError>

Import a projection batch from forge-memory-bridge.

This is the canonical in-process import path for the stack: ExportEnvelopeV3 -> transform_envelope_v3() -> ProjectionImportBatchV3 -> semantic-memory import transaction.

V2 remains supported as a compatibility-normalized import batch shape. The old import_envelope() method remains functional only during the migration cycle. JSON parsing is retained only via import_projection_batch_json_compat().

pub async fn import_projection_batch_json_compat( &self, batch_json: &str, ) -> Result<ProjectionImportResult, MemoryError>

Deserialize and import a projection batch from JSON.

This is a compatibility boundary for callers that still cross the in-process seam as serialized JSON. New code should pass ProjectionImportBatchV3 directly to import_projection_batch().

pub async fn query_projection_imports( &self, scope_namespace: Option<&str>, limit: usize, ) -> Result<Vec<ProjectionImportLogEntry>, MemoryError>

Query the V11 projection import log.

pub async fn latest_rebuildable_kernel_projection_import_for_scope( &self, scope_key: &ScopeKey, ) -> Result<Option<ProjectionImportLogEntry>, MemoryError>

Return the most recent exact-scope import receipt carrying a rebuildable kernel V3 batch.

pub async fn query_projection_import_failures( &self, scope_namespace: Option<&str>, limit: usize, ) -> Result<Vec<ProjectionImportFailureReceiptEntry>, MemoryError>

Query durable failed projection import receipts.

impl MemoryStore

pub fn open(config: MemoryConfig) -> Result<Self, MemoryError>

Open or create a memory store at the configured base directory.

Creates the directory if it doesn’t exist, opens/creates SQLite, runs migrations, and initializes the HNSW index.

pub fn open_with_embedder( config: MemoryConfig, embedder: Box<dyn Embedder>, ) -> Result<Self, MemoryError>

Open with a custom embedder (for testing or non-Ollama providers).

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

Rebuild the HNSW index from SQLite f32 embeddings.

Call this if sidecar files are missing, corrupted, or after reembed_all().

pub fn flush_hnsw(&self) -> Result<(), MemoryError>

Persist the HNSW graph, vector data, and key mappings to disk.

Called automatically on drop, but can be called explicitly for durability.

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

Compact the HNSW index by rebuilding without tombstones.

Only rebuilds if the deleted ratio exceeds the compaction threshold.

pub async fn verify_integrity( &self, mode: VerifyMode, ) -> Result<IntegrityReport, MemoryError>

Verify database integrity.

In Quick mode, checks table existence and row counts. In Full mode, also verifies FTS consistency and runs SQLite integrity_check.

pub async fn reconcile( &self, action: ReconcileAction, ) -> Result<IntegrityReport, MemoryError>

Reconcile detected integrity issues.

• ReportOnly: no-op, just returns the integrity report.
• RebuildFts: rebuilds all FTS indexes from source data.
• ReEmbed: not yet implemented (requires async embedding calls).

pub fn config(&self) -> &MemoryConfig

Get the current configuration.

pub fn graph_view(&self) -> Arc<dyn GraphView>

View the store as a derived graph over documents, chunks, facts, sessions, messages, episodes, namespaces, and semantic similarity edges.

pub async fn search( &self, query: &str, top_k: Option<usize>, namespaces: Option<&[&str]>, source_types: Option<&[SearchSourceType]>, ) -> Result<Vec<SearchResult>, MemoryError>

Hybrid search across facts, document chunks, and searchable episodes.

pub async fn search_fts_only( &self, query: &str, top_k: Option<usize>, namespaces: Option<&[&str]>, source_types: Option<&[SearchSourceType]>, ) -> Result<Vec<SearchResult>, MemoryError>

Full-text search only (no embeddings needed).

pub async fn search_vector_only( &self, query: &str, top_k: Option<usize>, namespaces: Option<&[&str]>, source_types: Option<&[SearchSourceType]>, ) -> Result<Vec<SearchResult>, MemoryError>

Vector similarity search only (no FTS).

pub async fn search_explained( &self, query: &str, top_k: Option<usize>, namespaces: Option<&[&str]>, source_types: Option<&[SearchSourceType]>, ) -> Result<Vec<ExplainedResult>, MemoryError>

Search with full score breakdown for each result.

pub async fn embedding_displacement( &self, text_a: &str, text_b: &str, ) -> Result<EmbeddingDisplacement, MemoryError>

Compute embedding displacement between two texts.

pub fn embedding_displacement_from_vecs( a: &[f32], b: &[f32], ) -> Result<EmbeddingDisplacement, MemoryError>

Compute embedding displacement from pre-computed vectors.

pub fn chunk_text(&self, text: &str) -> Vec<TextChunk>

Chunk text using the configured strategy and token counter.

pub async fn embed(&self, text: &str) -> Result<Vec<f32>, MemoryError>

Embed a single text via the configured provider.

pub async fn embed_batch( &self, texts: &[&str], ) -> Result<Vec<Vec<f32>>, MemoryError>

Embed multiple texts in a batch.

pub async fn stats(&self) -> Result<MemoryStats, MemoryError>

Get database statistics.

pub async fn list_scope_domains(&self) -> Result<Vec<String>, MemoryError>

Return distinct scope_domain values stored in document metadata.

Queries json_extract(metadata, '$.scope_domain') across all documents and returns the unique non-null values. Used by the Recall app to populate the scope picker dynamically instead of relying on a hardcoded list.

pub async fn embeddings_are_dirty(&self) -> Result<bool, MemoryError>

Check if embeddings need re-generation after a model change.

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

Re-embed all facts, chunks, messages, and episodes. Call after changing embedding models.

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

Vacuum the database (reclaim space after deletions).

pub async fn last_import_at( &self, namespace: &str, ) -> Result<Option<String>, MemoryError>

Get the most recent successful import timestamp for a namespace.

pub async fn query_claim_versions( &self, query: ProjectionQuery, ) -> Result<Vec<ProjectionClaimVersion>, MemoryError>

Query imported claim projection rows through the supported public read surface.

pub async fn query_relation_versions( &self, query: ProjectionQuery, ) -> Result<Vec<ProjectionRelationVersion>, MemoryError>

Query imported relation projection rows through the supported public read surface.

pub async fn query_episodes( &self, query: ProjectionQuery, ) -> Result<Vec<ProjectionEpisode>, MemoryError>

Query imported episode projection rows through the supported public read surface.

pub async fn query_entity_aliases( &self, query: ProjectionQuery, ) -> Result<Vec<ProjectionEntityAlias>, MemoryError>

Query imported entity-alias rows through the supported public read surface.

pub async fn query_evidence_refs( &self, query: ProjectionQuery, ) -> Result<Vec<ProjectionEvidenceRef>, MemoryError>

Query imported evidence-reference rows through the supported public read surface.

Trait Implementations

impl Clone for MemoryStore

fn clone(&self) -> MemoryStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.