Struct MemoryManager 

pub struct MemoryManager { /* private fields */ }

Agent memory manager.

Stores and retrieves memory entries using a pluggable storage backend. Supports embedding-based vector search via an in-memory TF-IDF index that is rebuilt on startup.

Implementations

impl MemoryManager

pub async fn semantic_search( &self, query: &str, memory_type: Option<MemoryType>, limit: usize, hnsw_index: &HnswMemoryIndex, ) -> Result<Vec<SemanticHit>, Error>

Semantic search using HNSW index.

Unlike search() which uses brute-force cosine similarity over the in-memory HashMap, semantic_search() uses the HNSW approximate nearest neighbor index for sub-linear time complexity.

pub async fn rebuild_hnsw_index( &self, hnsw_index: &HnswMemoryIndex, ) -> Result<usize, Error>

Rebuild the HNSW index from all stored memories.

Call this at startup or after bulk operations.

pub async fn list_by_tier( &self, tier: MemoryTier, limit: usize, ) -> Result<Vec<MemoryEntry>, Error>

List memories by tier (loads all types, filters by tier field).

pub async fn get_by_id(&self, id: &str) -> Result<Option<MemoryEntry>, Error>

Get a memory entry by ID (searches all types).

pub async fn load_by_reference( &self, reference: &str, ) -> Result<Option<MemoryEntry>, Error>

Load a memory entry by reference string (ID or category/id).

pub async fn select_by_manifest( &self, query: &str, limit: usize, ) -> Result<Vec<MemoryEntry>, Error>

Select memories by manifest (keyword matching against content).

pub async fn build_hot_context( &self, token_budget: usize, ) -> Result<String, Error>

Build the Hot tier context for agent prompt injection.

pub async fn build_full_context( &self, _query: &str, system_prompt: &str, token_budget: usize, ) -> Result<String, Error>

Build full context: hot context + proactive recall blended into system prompt.

pub async fn shift_tier( &self, id: &str, from: MemoryTier, to: MemoryTier, ) -> Result<(), Error>

Shift a memory entry between tiers.

pub async fn pin(&self, id: &str) -> Result<(), Error>

Pin a memory (set permanent protection).

pub async fn unpin(&self, id: &str) -> Result<(), Error>

Unpin a memory (revert to auto-computed protection).

pub async fn set_importance( &self, id: &str, importance: f32, ) -> Result<(), Error>

Set importance for a memory entry.

pub async fn recompute_all_decay(&self, multiplier: f32) -> Result<usize, Error>

Recompute decay scores for all entries.

Returns the number of entries updated.

pub async fn immediate_hot_overflow( &self, hot_max: usize, ) -> Result<usize, Error>

Immediate Hot overflow handling.

impl MemoryManager

pub async fn total_entries(&self) -> usize

Returns total entries across all memory types (from disk).

pub async fn rebuild_index(&self) -> Result<(), Error>

Rebuild the vector index from all stored memories.

Call once at startup to populate the in-memory index from persisted memory entries.

pub async fn save_index_snapshot(&self) -> Result<(), Error>

Save the current vector index to disk as a snapshot.

pub async fn load_index_snapshot(&self) -> Result<usize, Error>

Load a previously saved vector index snapshot from disk.

pub async fn remember(&self, entry: MemoryEntry) -> Result<String, Error>

Store a memory entry. Returns the entry ID.

When SQLite backend is enabled, delegates to SqliteMemoryStore. Otherwise computes and stores the entry’s text vector in the in-memory index for future semantic search.

pub async fn get( &self, id: &str, memory_type: MemoryType, ) -> Result<Option<MemoryEntry>, Error>

Retrieve a single memory by ID.

Records access for auto-protection tracking.

pub async fn forget( &self, id: &str, memory_type: MemoryType, ) -> Result<bool, Error>

Delete a memory entry.

pub async fn list( &self, memory_type: MemoryType, limit: usize, ) -> Result<Vec<MemoryEntry>, Error>

List memories of a given type, most recent first.

pub async fn search( &self, query: &str, memory_type: Option<MemoryType>, limit: usize, ) -> Result<Vec<MemoryEntry>, Error>

Search memories by semantic similarity (vector search).

Falls back to keyword search when the vector index is empty or yields no results above the similarity threshold.

pub async fn recall(&self, query: &str) -> Result<Vec<MemoryEntry>, Error>

Recall relevant memories for a new session.

Combines recent conversation summaries, session summaries, and keyword-matched facts/episodes.

pub fn blend_into_prompt( &self, memories: &[MemoryEntry], system_prompt: &str, ) -> String

Blend recalled memories into the system prompt.

pub async fn recall_with_rerank( &self, query: &str, ) -> Result<Vec<MemoryEntry>, Error>

Recall with Flash Attention re-ranking (Phase 6).

pub async fn is_duplicate(&self, content: &str) -> bool

Check if a memory entry with identical content already exists.

Uses a fast hash comparison against the in-memory vector index.

pub async fn remember_unique( &self, entry: MemoryEntry, ) -> Result<Option<String>, Error>

Store a memory entry only if no duplicate content exists.

Returns the entry ID if stored, or None if duplicate.

pub async fn recall_with_proactive( &self, query: &str, recall_timing: &mut Option<RecallTiming>, ) -> Result<Vec<MemoryEntry>, Error>

Recall with proactive enhancement.

Extends the standard recall() with proactive memory injection based on RecallTiming triggers.

impl MemoryManager

pub fn new(storage: Arc<dyn MemoryStorage>) -> MemoryManager

Create a new MemoryManager with a storage backend.

pub fn set_git_layer(&mut self, gl: Arc<dyn MemoryGit>)

Attach a git layer for version-controlled saves.

pub fn set_sqlite_store(&mut self, store: Arc<SqliteMemoryStore>)

Attach a SQLite-backed memory store (RFC-012).

pub fn sqlite_store(&self) -> &Option<Arc<SqliteMemoryStore>>

Get a reference to the SQLite store (if configured).

pub fn set_sona_engine(&mut self, engine: Arc<SonaEngine>)

Attach a SONA learning engine (RFC-020 Phase 2).

pub fn sona_engine(&self) -> Option<&Arc<SonaEngine>>

Get a reference to the SONA engine (if configured).

pub fn set_hnsw_index(&self, index: Arc<HnswMemoryIndex>)

Attach an HNSW index for fast semantic search.

pub fn with_max_recall(self, n: usize) -> MemoryManager

Set max memories returned by recall.

pub fn set_max_recall(&mut self, n: usize)

Set max_recall in-place.

pub fn vector_index_size(&self) -> usize

Returns the number of entries in the vector index.

pub fn effective_importance(entry: &MemoryEntry) -> f32

Compute effective importance of a memory entry.

pub async fn curate( &self, budget: &MemoryBudget, ) -> Result<CurationReport, Error>

Curate memories: identify candidates for removal based on budget.

pub fn spawn_curation_task(self: &Arc<MemoryManager>, budget: MemoryBudget)

Spawn a background curation task.

Trait Implementations

impl Debug for MemoryManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.