Struct Memory 

pub struct Memory { /* private fields */ }

High-level memory API for AI agents.

Memory wires together fact storage, vector search, graph storage, and an embedding provider. Most callers should construct it via in_memory or open rather than calling new directly.

Implementations

impl Memory

pub fn new( fact_store: Arc<dyn FactStore>, vector_store: Arc<dyn VectorStore>, graph_store: Arc<dyn GraphStore>, embedding: Arc<dyn EmbeddingProvider>, ) -> Self

Construct Memory from explicit store and embedding instances.

pub async fn in_memory( embedding: Box<dyn EmbeddingProvider>, ) -> Result<Self, MemoryError>

Create a fully in-memory Memory instance backed by SQLite :memory:.

Schema migration is applied automatically. Suitable for testing and short-lived agent invocations.

pub async fn open( database_url: &str, embedding: Box<dyn EmbeddingProvider>, ) -> Result<Self, MemoryError>

Open a file-backed Memory instance at database_url.

Uses SQLite for facts and graph data, with an in-process EmbeddedVectorStore for semantic search. Schema migration is applied automatically.

pub async fn add_fact( &self, text: &str, scope: Scope, ) -> Result<FactId, MemoryError>

Embed text, create a Fact, and persist it in both the fact store and the vector store.

Returns the FactId of the newly created fact.

pub async fn recall( &self, query: &RecallQuery, ) -> Result<Vec<Fact>, MemoryError>

Semantically recall facts matching query.

Embeds the query text, performs vector search, fetches full facts from the fact store, filters by validity and scope, and records an access event for each returned fact.

pub async fn list_facts( &self, scope: Option<Scope>, ) -> Result<Vec<Fact>, MemoryError>

List currently-valid facts for the given scope.

pub async fn forget( &self, id: FactId, _reason: Option<&str>, ) -> Result<(), MemoryError>

Invalidate (soft-delete) a fact and remove it from the vector store.

The fact record is preserved for historical queries. reason is currently logged via tracing but not stored (reserved for future use).

pub async fn delete_user_data(&self, scope: Scope) -> Result<u64, MemoryError>

Hard-delete all data (facts, vectors, graph nodes/edges) for scope.

Returns the number of facts deleted. Intended for GDPR / right-to-erasure requests.

pub async fn stats( &self, _scope: Option<Scope>, ) -> Result<StoreStats, MemoryError>

Return aggregate statistics for the fact store.

pub async fn export( &self, scope: Option<Scope>, ) -> Result<Vec<Fact>, MemoryError>

Export all currently-valid facts for scope.

pub async fn import(&self, facts: Vec<Fact>) -> Result<u64, MemoryError>

Import a batch of facts, re-embedding each one.

Returns the number of facts successfully imported (skips duplicates by id).

pub async fn consolidate( &self, scope: &Scope, llm: Option<&dyn LlmClient>, config: ConsolidationConfig, ) -> Result<ConsolidationResult, MemoryError>

Run a consolidation cycle over the given scope.

Operations (decay, promote, dedup, summarize, reflect) are controlled by config.enabled_ops. LLM-dependent operations (summarize, reflect) are skipped when llm is None.

pub async fn context( &self, query: &str, scope: &Scope, config: ContextConfig, ) -> Result<ContextBlock, MemoryError>

Assemble a token-budgeted context block for LLM prompt injection.

Retrieves relevant facts via hybrid search (vector + keyword + graph), ranks by tier priority (Working > Conversation > Knowledge), fills the token budget greedily, and formats the output.

pub async fn add_messages( &self, messages: &[Message], scope: Scope, llm: Box<dyn LlmClient>, config: ExtractionConfig, ) -> Result<Vec<FactId>, MemoryError>

Ingest conversation messages: extract facts via LLM, detect conflicts, store facts + entities + relationships.

Returns the IDs of newly created facts.

pub fn fact_store(&self) -> &Arc<dyn FactStore>

Access the underlying FactStore.

pub fn vector_store(&self) -> &Arc<dyn VectorStore>

Access the underlying VectorStore.

pub fn graph_store(&self) -> &Arc<dyn GraphStore>

Access the underlying GraphStore.