Struct TieredMemory 

pub struct TieredMemory {
    pub hot: Arc<MessageStore>,
    /* private fields */
}

Three-tier memory storage system with persistence

Fields

hot: Arc<MessageStore>

Hot tier: Full messages (LanceDB-backed)

Implementations

impl TieredMemory

pub async fn new( hot_store: Arc<MessageStore>, db: Arc<LanceDatabase>, embeddings: Arc<CachedEmbeddingProvider>, config: TieredMemoryConfig, ) -> Self

Create a new tiered memory system with persistent storage

pub async fn with_defaults( hot_store: Arc<MessageStore>, db: Arc<LanceDatabase>, embeddings: Arc<CachedEmbeddingProvider>, ) -> Self

Create with default configuration

pub async fn add_message( &mut self, message: MessageMetadata, importance: f32, ) -> Result<()>

Add a message to the hot tier with Session authority.

If TieredMemoryConfig::session_ttl_secs is set, the message will be assigned an expiry timestamp and will be removed by Self::evict_expired after the configured duration.

pub async fn add_canonical_message( &mut self, message: MessageMetadata, importance: f32, _token: CanonicalWriteToken, ) -> Result<()>

Add a message to the hot tier with Canonical authority.

Canonical entries are long-lived and immune to session-TTL eviction. A CanonicalWriteToken is required to call this method; obtain one through an authorised entry point in the CLI layer.

pub async fn evict_expired(&self) -> Result<usize>

Delete all hot-tier messages whose TTL has expired.

Returns the number of entries evicted. Call this at agent run completion or on a periodic background schedule.

Canonical-authority messages are never evicted here regardless of any expires_at value, because they are expected to have None.

pub async fn record_access(&mut self, message_id: &str) -> Result<()>

Record access to a message (for promotion/retention decisions)

pub async fn search_adaptive( &mut self, query: &str, conversation_id: Option<&str>, ) -> Result<Vec<TieredSearchResult>>

Search across all tiers with adaptive resolution

pub async fn search_adaptive_multi_factor( &mut self, query: &str, conversation_id: Option<&str>, ) -> Result<Vec<TieredSearchResult>>

Search across all tiers and score results using combined similarity, recency, and importance signals.

This is the preferred retrieval method for long-horizon agent tasks where a pure similarity score can surface stale or low-importance results.

The returned results are sorted by MultiFactorScore::combined (descending). Each result has multi_factor_score populated.

pub async fn demote_to_warm( &mut self, message_id: &str, summary: MessageSummary, ) -> Result<()>

Demote a message from hot to warm tier

pub async fn demote_to_cold( &mut self, summary_id: &str, fact: KeyFact, ) -> Result<()>

Demote a summary from warm to cold tier

pub async fn promote_to_hot( &mut self, message_id: &str, ) -> Result<Option<MessageMetadata>>

Promote a message back to hot tier (re-fetch full content)

pub async fn get_demotion_candidates( &self, tier: MemoryTier, count: usize, ) -> Result<Vec<String>>

Get messages that should be considered for demotion

pub async fn get_stats(&self) -> Result<TieredMemoryStats>

Get statistics about tier distribution

pub fn fallback_summarize(&self, content: &str) -> String

Fallback summarization without LLM

pub fn fallback_fact(&self, summary: &MessageSummary) -> KeyFact

Create a fallback fact from a summary

pub async fn synthesize_mental_model( &mut self, fact_ids: &[String], model_text: String, model_type: ModelType, conversation_id: String, ) -> Result<String>

Synthesise and store a new mental model from a set of source fact IDs.

Returns the new model’s ID.

The table is created on first call; subsequent calls reuse it.

pub async fn search_mental_models( &self, query: &str, limit: usize, ) -> Result<Vec<TieredSearchResult>>

Semantic search over the mental model tier.