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 ingest_chunk_manifest( &self, options: ChunkManifestIngestOptions, entries: Vec<ChunkManifestEntry>, ) -> Result<ChunkManifestIngestResult, MemoryError>

Ingest an externally chunked document manifest and return exact chunk mappings.

This API preserves semantic-memory as the owner of document/chunk storage and embeddings: callers provide chunk boundaries and external IDs, while semantic-memory generates and stores its own document/chunk IDs atomically.

pub async fn ingest_chunk_manifest_with_trace( &self, options: ChunkManifestIngestOptions, entries: Vec<ChunkManifestEntry>, trace_ctx: Option<&TraceCtx>, ) -> Result<ChunkManifestIngestResult, MemoryError>

Ingest an externally chunked document manifest 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<NamespaceDeleteReport, MemoryError>

Delete all memory in a namespace and return a per-surface report.

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 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_with_context( &self, query: &str, top_k: Option<usize>, namespaces: Option<&[&str]>, source_types: Option<&[SearchSourceType]>, context: SearchContext, ) -> Result<SearchResponse, MemoryError>

Hybrid search with an explicit deterministic context and optional receipt.

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_vector_only_with_context( &self, query: &str, top_k: Option<usize>, namespaces: Option<&[&str]>, source_types: Option<&[SearchSourceType]>, context: SearchContext, ) -> Result<SearchResponse, MemoryError>

Vector similarity search with an explicit deterministic context and optional receipt.

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 search_explained_with_context( &self, query: &str, top_k: Option<usize>, namespaces: Option<&[&str]>, source_types: Option<&[SearchSourceType]>, context: SearchContext, ) -> Result<ExplainedSearchResponse, MemoryError>

Search with full score breakdown under an explicit deterministic context.

pub async fn get_search_receipt( &self, receipt_id: &str, ) -> Result<Option<VectorSearchReceiptV1>, MemoryError>

Load a durable search receipt by receipt/request ID.

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

Replay a durable search receipt with caller-supplied query text and filters.

Receipts intentionally do not store query text or filter values. The caller supplies those inputs, and the stored receipt supplies the deterministic evaluation time and retrieval family for comparison.

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.