Struct MemorySystem 

pub struct MemorySystem { /* private fields */ }

Main memory system

Implementations

impl MemorySystem

pub fn new(config: MemoryConfig, shared_cache: Option<&Cache>) -> Result<Self>

Create a new memory system.

If shared_cache is provided, all per-user RocksDB instances share the same LRU block cache (multi-tenant server mode). Pass None for standalone / test use — each DB gets a small local cache.

pub fn set_graph_memory(&mut self, graph: Arc<RwLock<GraphMemory>>)

Wire up GraphMemory for entity relationships and spreading activation

When GraphMemory is set, the remember() method will:

1. Extract entities from memory content
2. Add them to the knowledge graph
3. Create edges between co-occurring entities

This enables spreading activation retrieval and Hebbian learning

pub fn graph_memory(&self) -> Option<&Arc<RwLock<GraphMemory>>>

Get reference to the optional graph memory

pub fn set_feedback_store(&mut self, feedback: Arc<RwLock<FeedbackStore>>)

Set the feedback store for momentum-based scoring (PIPE-9)

When set, retrieval automatically applies feedback momentum:

• Positive momentum (frequently helpful) → boost score
• Negative momentum (frequently ignored) → suppress score (up to 20%)

This provides consistent feedback integration across all retrieval paths.

pub fn feedback_store(&self) -> Option<&Arc<RwLock<FeedbackStore>>>

Get reference to the optional feedback store

pub fn remember_with_id( &self, memory_id: MemoryId, experience: Experience, created_at: Option<DateTime<Utc>>, ) -> Result<MemoryId>

Store a new memory with an explicit ID.

Used by MIF import to preserve original UUIDs. Stores the memory with embedding generation and vector indexing, but skips graph entity extraction (imported memories already have their entity relationships established).

pub fn remember( &self, experience: Experience, created_at: Option<DateTime<Utc>>, ) -> Result<MemoryId>

Store a new memory (takes ownership to avoid clones) Thread-safe: uses interior mutability for all internal state If created_at is None, uses current time (Utc::now())

pub fn remember_with_agent( &self, experience: Experience, created_at: Option<DateTime<Utc>>, agent_id: Option<String>, run_id: Option<String>, ) -> Result<MemoryId>

Remember with agent context for multi-agent systems

Same as remember but tracks which agent created the memory, enabling agent-specific retrieval and hierarchical memory tracking.

pub fn recall(&self, query: &Query) -> Result<Vec<SharedMemory>>

Search and retrieve relevant memories (zero-copy with Arc)

PRODUCTION IMPLEMENTATION:

• Semantic search: Uses embeddings + vector similarity across ALL tiers
• Non-semantic search: Uses importance * temporal decay
• Zero shortcuts, no TODOs, enterprise-grade

pub fn paginated_recall( &self, query: &Query, ) -> Result<PaginatedResults<SharedMemory>>

Paginated memory recall with “has_more” indicator (SHO-69)

Returns a PaginatedResults struct containing:

• The page of results
• Whether there are more results beyond this page
• The total count (if computed)
• Pagination metadata (offset, limit)

Uses the limit+1 trick: requests one extra result to detect if there are more.

pub fn recall_by_tags( &self, tags: &[String], limit: usize, ) -> Result<Vec<Memory>>

Recall memories by tags (fast, no embedding required)

Returns memories that have ANY of the specified tags.

pub fn recall_by_date( &self, start: DateTime<Utc>, end: DateTime<Utc>, limit: usize, ) -> Result<Vec<Memory>>

Recall memories within a date range

Returns memories created between start and end (inclusive).

pub fn apply_learning_boost( &self, user_id: &str, memories: Vec<SharedMemory>, ) -> Vec<SharedMemory>

Apply learning velocity boost to retrieved memories

This method should be called after recall() when user_id is known. It boosts memories that have been recently learned/reinforced, implementing the principle that “learning should improve retrieval over time”.

Boost factors:

• Base boost for any learning activity (5%)
• Velocity boost for rapid learning (up to 15%)
• Potentiation bonus for LTP’d edges (10%)
• Total max boost: 30%

The memories are re-sorted by adjusted score after boosting.

pub fn recall_for_user( &self, user_id: &str, query: &Query, ) -> Result<Vec<SharedMemory>>

Recall with learning boost applied

Convenience method that combines recall() with apply_learning_boost(). Use this when you have the user_id available at recall time.

pub fn get_learning_velocity( &self, user_id: &str, memory_id: &str, hours: i64, ) -> Result<LearningVelocity>

Get learning velocity statistics for a memory

Returns information about recent learning activity for this memory, useful for debugging/introspection.

pub fn get_learning_stats(&self, user_id: &str) -> Result<LearningStats>

Get learning history statistics for a user

pub fn get_learning_events( &self, user_id: &str, since: DateTime<Utc>, limit: usize, ) -> Result<Vec<StoredLearningEvent>>

Get recent learning events for a user

pub fn store_temporal_facts_for_memory( &self, user_id: &str, memory_id: &MemoryId, content: &str, entities: &[String], created_at: DateTime<Utc>, ) -> Result<usize>

Extract and store temporal facts from a memory

Call this after remember() when you have access to user_id. Extracts facts like “Melanie is planning camping next month” and stores them with resolved absolute dates for accurate multi-hop retrieval.

pub fn find_temporal_facts( &self, user_id: &str, entity: &str, event_keywords: &[&str], event_type: Option<EventType>, ) -> Result<Vec<TemporalFact>>

Find temporal facts by entity and event keywords

Used for multi-hop queries like “When did Melanie paint a sunrise?” Returns facts sorted by conversation date (earliest first for planning queries).

pub fn list_temporal_facts( &self, user_id: &str, limit: usize, ) -> Result<Vec<TemporalFact>>

List all temporal facts for a user

pub fn forget(&self, criteria: ForgetCriteria) -> Result<usize>

Forget memories based on criteria Thread-safe: uses interior mutability for all internal state

pub fn stats(&self) -> MemoryStats

Get memory statistics

Returns current stats with fresh average_importance calculated from storage. Most counters are cached in-memory for performance, but importance is recalculated to ensure accuracy after memory modifications.

pub fn export_visualization_dot(&self) -> String

Export visualization graph as DOT format for Graphviz

pub fn build_visualization_graph(&self) -> Result<GraphStats>

Build visualization graph from current memory state Call this to populate the visualization graph with all current memories

pub fn get_embedder(&self) -> &dyn Embedder

Get reference to embedder for graph-aware retrieval

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

Compute embedding for arbitrary text (for external use like prospective memory)

pub fn get_all_memories(&self) -> Result<Vec<SharedMemory>>

Get all memories across all tiers for graph-aware retrieval Deduplicates by memory ID, preferring working > session > long-term

pub fn find_memory_by_prefix( &self, id_prefix: &str, ) -> Result<Option<SharedMemory>>

Find a memory by UUID prefix across all tiers.

Accepts both full UUIDs and 8+ char hex prefixes (as displayed by MCP tools). Searches working → session → long-term memory with deduplication. Returns Err for ambiguous prefixes (multiple matches).

pub fn get_working_memories(&self) -> Vec<SharedMemory>

Get memories from working memory tier (highest activation, most recent)

pub fn get_session_memories(&self) -> Vec<SharedMemory>

Get memories from session memory tier (medium-term, consolidated)

pub fn get_longterm_memories(&self, limit: usize) -> Result<Vec<Memory>>

Get memories from long-term memory tier (persistent, lower activation) Returns up to limit memories to avoid overwhelming responses

pub fn apply_edge_promotion_boosts( &self, boosts: &[EdgePromotionBoost], ) -> Result<usize>

Apply importance boosts to memories whose edges were promoted (Direction 1).

When an edge promotes from L1→L2 or L2→L3, the memories involved get a small importance boost, reflecting that they participate in a consolidating relationship. Uses interior mutability — set_importance works through Arc.

pub fn compensate_orphaned_memories( &self, orphaned_entity_ids: &[String], ) -> Result<usize>

Apply compensatory boost to memories that lost all graph edges (Direction 2).

When graph decay prunes edges and leaves entities orphaned, the memories referencing those entities get a small importance boost to prevent immediate decay death. This gives them one more maintenance cycle to prove value.

pub fn show_visualization(&self)

Show memory visualization (ASCII art of memory graph)

pub fn export_graph(&self, path: &Path) -> Result<()>

Export memory graph as DOT file for Graphviz

pub fn get_visualization_stats(&self) -> GraphStats

Get visualization statistics

pub fn flush_storage(&self) -> Result<()>

Flush long-term storage to ensure data persistence (critical for graceful shutdown)

pub fn get_db(&self) -> Arc<DB>

Get the underlying RocksDB database handle for backup operations

Warning

This provides direct access to the database. Use with caution. Primarily intended for backup/restore operations.

pub fn advanced_search(&self, criteria: SearchCriteria) -> Result<Vec<Memory>>

Advanced search using storage criteria

pub fn get_memory(&self, id: &MemoryId) -> Result<Memory>

Get memory by ID from long-term storage

pub fn update_memory(&self, memory: &Memory) -> Result<()>

Update a memory in storage with full re-indexing

This properly updates the memory by:

1. Removing stale secondary indices and re-storing in RocksDB
2. Re-indexing in vector DB (semantic search) if embeddings changed
3. Re-indexing in BM25 (keyword/hybrid search)
4. Updating working/session memory caches if the memory is cached

pub fn set_memory_parent( &self, memory_id: &MemoryId, parent_id: Option<MemoryId>, ) -> Result<()>

Set or update the parent of a memory for hierarchical organization

This enables memory trees where memories can have parent-child relationships. Example: “71-research” -> “algebraic” -> “21×27≡-1”

Pass None as parent_id to remove the parent (make it a root memory).

pub fn get_memory_children(&self, parent_id: &MemoryId) -> Result<Vec<Memory>>

Get children of a memory

pub fn get_memory_ancestors(&self, memory_id: &MemoryId) -> Result<Vec<Memory>>

Get ancestors (parent chain) of a memory

pub fn get_memory_hierarchy( &self, memory_id: &MemoryId, ) -> Result<(Vec<Memory>, Memory, Vec<Memory>)>

Get full hierarchy context (ancestors, memory, children)

pub fn decompress_memory(&self, memory: &Memory) -> Result<Memory>

Decompress a memory

pub fn get_storage_stats(&self) -> Result<StorageStats>

Get storage statistics

pub fn get_uncompressed_older_than( &self, cutoff: DateTime<Utc>, ) -> Result<Vec<Memory>>

Get uncompressed old memories

pub fn rebuild_vector_index(&self) -> Result<()>

Rebuild vector index from all existing long-term memories (startup initialization)

pub fn repair_vector_index(&self) -> Result<(usize, usize, usize, usize)>

Repair vector index by finding and re-indexing orphaned memories

Orphaned memories are those stored in RocksDB but missing from the vector index. This can happen if embedding generation fails during record().

Returns: (total_storage, indexed, repaired, failed)

pub fn verify_index_integrity(&self) -> Result<IndexIntegrityReport>

Verify index integrity and return diagnostic information

Returns a struct with:

• total_storage: memories in RocksDB
• total_indexed: memories in vector index
• orphaned_count: memories missing from index
• orphaned_ids: list of orphaned memory IDs (first 100)

pub fn cleanup_corrupted(&self) -> Result<usize>

Cleanup corrupted memories that fail to deserialize Returns the number of entries deleted

pub fn migrate_legacy(&self) -> Result<(usize, usize, usize)>

Migrate legacy memories to current format for improved performance Returns (migrated_count, already_current_count, failed_count)

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

Rebuild vector index from scratch using only valid memories in storage This removes orphaned index entries and rebuilds with proper ID mappings Returns (total_memories, total_indexed)

pub fn save_vector_index(&self, _path: &Path) -> Result<()>

Save vector index to disk (shutdown persistence) Uses Vamana persistence format for instant startup on restart

pub fn index_health(&self) -> IndexHealth

Get vector index health information

Returns metrics about the Vamana index including total vectors, incremental inserts since last build, and whether rebuild is recommended.

pub fn auto_rebuild_index_if_needed(&self) -> Result<bool>

Auto-rebuild vector index if degradation threshold is exceeded

Returns Ok(true) if rebuild was performed, Ok(false) if not needed. Thread-safe: concurrent calls are no-ops while rebuild is in progress.

pub fn recall_tracked(&self, query: &Query) -> Result<TrackedRetrieval>

Retrieve memories with tracking for later feedback

Use this when you want to provide feedback on retrieval quality. Returns a TrackedRetrieval that can be used with reinforce_recall.

Example

let tracked = memory_system.recall_tracked(&query)?;
// Use memories...
// Later, after task completion:
memory_system.reinforce_recall(&tracked.memory_ids(), RetrievalOutcome::Helpful)?;

pub fn reinforce_recall( &self, memory_ids: &[MemoryId], outcome: RetrievalOutcome, ) -> Result<ReinforcementStats>

Reinforce memories based on task outcome (core feedback loop)

This is THE key method that closes the Hebbian loop:

• If outcome is Helpful: strengthen associations, boost importance
• If outcome is Misleading: weaken associations, reduce importance
• If outcome is Neutral: just record access (mild reinforcement)

CACHE COHERENCY: This method updates BOTH the in-memory caches AND persistent storage to ensure importance changes are visible immediately through cached references (via Arc interior mutability) AND survive restarts.

Arguments

• memory_ids - IDs of memories that were used in the task
• outcome - Whether the memories were helpful, misleading, or neutral

Returns

Statistics about what was reinforced

pub fn reinforce_recall_tracked( &self, tracked: &TrackedRetrieval, outcome: RetrievalOutcome, ) -> Result<ReinforcementStats>

Reinforce using a tracked recall (convenience wrapper)

pub fn graph_maintenance(&self)

Perform graph maintenance (decay old edges, prune weak ones)

Call this periodically (e.g., every hour or on user logout) to let unused associations naturally fade.

pub fn graph_stats(&self) -> MemoryGraphStats

Get memory graph statistics

pub fn upsert( &self, external_id: String, experience: Experience, change_type: ChangeType, changed_by: Option<String>, change_reason: Option<String>, ) -> Result<(MemoryId, bool)>

Upsert a memory: create if new, update with history tracking if exists

When a memory with the same external_id exists:

1. Old content is pushed to history (audit trail)
2. Content is updated with new content
3. Version is incremented
4. Embeddings are regenerated for new content
5. Vector index is updated

Arguments

• external_id - External system identifier (e.g., “linear:SHO-39”, “github:pr-123”)
• experience - The experience data to store
• change_type - Type of change (ContentUpdated, StatusChanged, etc.)
• changed_by - Optional: who/what triggered the change
• change_reason - Optional: description of why this changed

Returns

• (MemoryId, bool) - Memory ID and whether it was an update (true) or create (false)

pub fn get_memory_history( &self, memory_id: &MemoryId, ) -> Result<Vec<MemoryRevision>>

Get the history of a memory (audit trail of changes)

Returns the full revision history for memories with external linking. Returns empty vec for regular (non-mutable) memories.

pub fn find_by_external_id(&self, external_id: &str) -> Result<Option<Memory>>

Find a memory by external ID

Used to check if a memory already exists for an external entity

pub fn run_maintenance( &self, decay_factor: f32, user_id: &str, is_heavy: bool, ) -> Result<MaintenanceResult>

Run periodic maintenance (consolidation, activation decay, graph maintenance)

Call this periodically (e.g., every 5 minutes) to:

1. Promote memories between tiers based on thresholds
2. Decay activation levels on all memories
3. Run graph maintenance (prune weak edges)

is_heavy: when true, runs expensive operations (fact extraction, auto-repair) that require full RocksDB scans. Light cycles only touch in-memory data.

Returns the number of memories processed for activation decay. Also records consolidation events for introspection.

pub fn get_consolidation_report( &self, since: DateTime<Utc>, until: Option<DateTime<Utc>>, ) -> ConsolidationReport

Get a consolidation report for a time period

Shows what the memory system has been learning:

• Which memories strengthened or decayed
• What associations formed or were pruned
• What facts were extracted or reinforced

Arguments

• since - Start of the time period
• until - End of the time period (default: now)

pub fn get_consolidation_report_for_user( &self, user_id: &str, since: DateTime<Utc>, until: Option<DateTime<Utc>>, ) -> Result<ConsolidationReport>

Get a consolidation report for a user using persisted history

Unlike get_consolidation_report, this method uses persisted learning history and can generate reports spanning across restarts. It combines:

• Persisted significant events from learning_history (survives restarts)
• Ephemeral events from the event buffer (current session)

Use this when you need historical reports beyond the current session.

pub fn get_consolidation_events_since( &self, since: DateTime<Utc>, ) -> Vec<ConsolidationEvent>

Get all consolidation events since a timestamp

Returns raw events for detailed analysis

pub fn get_all_consolidation_events(&self) -> Vec<ConsolidationEvent>

Get all consolidation events in the buffer

pub fn record_consolidation_event(&self, event: ConsolidationEvent)

Record a consolidation event

Used internally by the memory system to log learning events. Also available for external callers that want to track custom events.

pub fn record_consolidation_event_for_user( &self, user_id: &str, event: ConsolidationEvent, )

Record a consolidation event for a specific user

This method both:

1. Pushes to the ephemeral event buffer (for real-time introspection)
2. Persists significant events to learning_history (for retrieval boosting)

Use this instead of record_consolidation_event when you have a user_id.

pub fn clear_consolidation_events(&self)

Clear all consolidation events

pub fn consolidation_event_count(&self) -> usize

Get the number of consolidation events in the buffer

pub fn distill_facts( &self, user_id: &str, min_support: usize, min_age_days: i64, ) -> Result<ConsolidationResult>

Distill semantic facts from episodic memories

Runs the consolidation process to extract durable knowledge:

1. Find patterns appearing in multiple memories
2. Create or reinforce semantic facts
3. Store facts in the fact store

Arguments

• user_id - User whose memories to consolidate
• min_support - Minimum memories needed to form a fact (default: 3)
• min_age_days - Minimum age of memories to consider (default: 7)

Returns

ConsolidationResult with stats and newly extracted facts

pub fn get_facts( &self, user_id: &str, limit: usize, ) -> Result<Vec<SemanticFact>>

Get semantic facts for a user

Arguments

• user_id - User whose facts to retrieve
• limit - Maximum number of facts to return

pub fn get_facts_by_entity( &self, user_id: &str, entity: &str, limit: usize, ) -> Result<Vec<SemanticFact>>

Get facts related to a specific entity

Arguments

• user_id - User whose facts to search
• entity - Entity to search for (e.g., “authentication”, “JWT”)
• limit - Maximum number of facts to return

pub fn get_facts_by_type( &self, user_id: &str, fact_type: FactType, limit: usize, ) -> Result<Vec<SemanticFact>>

Get facts of a specific type

Arguments

• user_id - User whose facts to search
• fact_type - Type of fact (Preference, Procedure, Definition, etc.)
• limit - Maximum number of facts to return

pub fn search_facts( &self, user_id: &str, query: &str, limit: usize, ) -> Result<Vec<SemanticFact>>

Search facts by keyword

Arguments

• user_id - User whose facts to search
• query - Search query
• limit - Maximum number of facts to return

pub fn get_fact_stats(&self, user_id: &str) -> Result<FactStats>

Get statistics about stored facts

pub fn get_facts_for_graph_entities( &self, user_id: &str, entity_names: &[String], limit_per_entity: usize, ) -> Result<Vec<SemanticFact>>

Get facts associated with graph entity names.

Bridges graph traversal → fact retrieval: when spreading activation discovers entity nodes, this method returns the semantic facts linked to those entities. Results are deduplicated and sorted by confidence (highest first).

pub fn reinforce_fact( &self, user_id: &str, fact_id: &str, memory_id: &MemoryId, ) -> Result<bool>

Reinforce a fact with new supporting evidence

Called when a new memory supports an existing fact. Increments support_count and boosts confidence.

pub fn delete_fact(&self, user_id: &str, fact_id: &str) -> Result<bool>

Delete a fact (soft delete or hard delete)

pub fn fact_store(&self) -> &Arc<SemanticFactStore>

Get the fact store for direct access

pub fn lineage_graph(&self) -> &Arc<LineageGraph>

Get the lineage graph for direct access

pub fn infer_lineage_for_memory( &self, user_id: &str, new_memory: &Memory, candidate_memories: &[Memory], ) -> Result<Vec<LineageEdge>>

Infer and store lineage between a new memory and existing memories

Called after storing a new memory to automatically detect causal relationships. Uses entity overlap, temporal proximity, and memory type patterns.

pub fn trace_lineage( &self, user_id: &str, memory_id: &MemoryId, direction: TraceDirection, max_depth: usize, ) -> Result<LineageTrace>

Trace lineage from a memory

pub fn find_root_cause( &self, user_id: &str, memory_id: &MemoryId, ) -> Result<Option<MemoryId>>

Find the root cause of a memory

pub fn lineage_stats(&self, user_id: &str) -> Result<LineageStats>

Get lineage statistics

Trait Implementations

impl Drop for MemorySystem

Automatic persistence on drop - ensures vector index and ID mappings survive restarts

This is CRITICAL for local memory: when the system shuts down (gracefully or via drop), all in-memory state (vector index, ID mappings) must be persisted to disk.

fn drop(&mut self)

Executes the destructor for this type.