ceylon_next/memory/advanced/
mod.rs

1//! Advanced Memory Management System
2//!
3//! This module provides sophisticated memory management capabilities including:
4//! - Short-term vs Long-term Memory
5//! - Episodic, Semantic, and Working Memory types
6//! - Automatic conversation summarization
7//! - Memory consolidation and compression
8//! - Duplicate detection and merging
9//! - Memory aging and decay
10//!
11//! # Architecture
12//!
13//! The advanced memory system is built on top of the core memory backends and
14//! adds intelligent processing and organization:
15//!
16//! ```text
17//! ┌─────────────────────────────────────────────────────┐
18//! │           Advanced Memory Manager                    │
19//! ├──────────────┬──────────────┬──────────────┬────────┤
20//! │   Working    │   Episodic   │   Semantic   │ Config │
21//! │   Memory     │   Memory     │   Memory     │        │
22//! └──────┬───────┴──────┬───────┴──────┬───────┴────────┘
23//!        │              │              │
24//!        ├──────────────┴──────────────┤
25//!        │   Summarization Engine      │
26//!        │   Consolidation Engine      │
27//!        │   Aging & Decay System      │
28//!        └─────────────┬───────────────┘
29//!                      │
30//!        ┌─────────────┴───────────────┐
31//!        │   Core Memory Backend       │
32//!        │  (SQLite/InMemory/File)     │
33//!        └─────────────────────────────┘
34//! ```
35//!
36//! # Memory Types
37//!
38//! - **Working Memory**: Recent context, kept in fast-access storage
39//! - **Episodic Memory**: Past conversations, indexed by time
40//! - **Semantic Memory**: Extracted facts, knowledge, and entities
41//!
42//! # Features
43//!
44//! - **Automatic Summarization**: Compress long conversations into summaries
45//! - **Important Moment Extraction**: Identify and preserve key information
46//! - **Background Processing**: Asynchronous memory consolidation
47//! - **Duplicate Detection**: Merge similar memories to reduce redundancy
48//! - **Memory Decay**: Age out less important memories over time
49//!
50//! # Examples
51//!
52//! ```rust,no_run
53//! use ceylon_next::memory::advanced::{AdvancedMemoryManager, MemoryConfig};
54//! use ceylon_next::memory::SqliteStore;
55//! use std::sync::Arc;
56//!
57//! #[tokio::main]
58//! async fn main() -> Result<(), String> {
59//!     let backend = Arc::new(SqliteStore::new("memory.db").await?);
60//!     let config = MemoryConfig::default();
61//!
62//!     let memory = AdvancedMemoryManager::new(backend, config).await?;
63//!
64//!     // Use advanced memory features...
65//!     Ok(())
66//! }
67//! ```
68
69use crate::memory::MemoryEntry;
70use serde::{Deserialize, Serialize};
71
72// ============================================
73// Core Types
74// ============================================
75
76/// Types of memory in the system
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
78pub enum MemoryType {
79    /// Working memory - recent context, fast access
80    Working,
81    /// Episodic memory - past conversations, time-indexed
82    Episodic,
83    /// Semantic memory - facts, knowledge, entities
84    Semantic,
85}
86
87/// Importance level of a memory
88#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
89pub enum ImportanceLevel {
90    Low = 1,
91    Medium = 2,
92    High = 3,
93    Critical = 4,
94}
95
96/// Enhanced memory entry with metadata
97#[derive(Debug, Clone, Serialize, Deserialize)]
98pub struct EnhancedMemoryEntry {
99    /// Base memory entry
100    pub entry: MemoryEntry,
101    /// Type of memory
102    pub memory_type: MemoryType,
103    /// Importance level
104    pub importance: ImportanceLevel,
105    /// Summary of the conversation
106    pub summary: Option<String>,
107    /// Extracted key points
108    pub key_points: Vec<String>,
109    /// Extracted entities (people, places, things mentioned)
110    pub entities: Vec<String>,
111    /// Related memory IDs
112    pub related_memories: Vec<String>,
113    /// Last accessed timestamp
114    pub last_accessed: u64,
115    /// Access count
116    pub access_count: u32,
117    /// Decay factor (0.0 to 1.0, 1.0 = fresh, 0.0 = fully decayed)
118    pub decay_factor: f32,
119}
120
121impl EnhancedMemoryEntry {
122    /// Create a new enhanced memory entry
123    pub fn new(entry: MemoryEntry, memory_type: MemoryType) -> Self {
124        Self {
125            entry,
126            memory_type,
127            importance: ImportanceLevel::Medium,
128            summary: None,
129            key_points: Vec::new(),
130            entities: Vec::new(),
131            related_memories: Vec::new(),
132            last_accessed: Self::current_timestamp(),
133            access_count: 0,
134            decay_factor: 1.0,
135        }
136    }
137
138    /// Update access information
139    pub fn mark_accessed(&mut self) {
140        self.last_accessed = Self::current_timestamp();
141        self.access_count += 1;
142    }
143
144    /// Calculate relevance score based on importance, recency, and access frequency
145    pub fn relevance_score(&self) -> f32 {
146        let importance_weight = self.importance as u32 as f32 / 4.0;
147        let recency_weight = self.recency_score();
148        // Handle access_count = 0 case: treat 0 accesses as 0.0 weight, not negative infinity
149        let access_weight = if self.access_count == 0 {
150            0.0
151        } else {
152            (self.access_count as f32).log2().min(1.0)
153        };
154
155        (importance_weight * 0.4 + recency_weight * 0.3 + access_weight * 0.3) * self.decay_factor
156    }
157
158    /// Calculate recency score (1.0 for very recent, 0.0 for old)
159    fn recency_score(&self) -> f32 {
160        let current = Self::current_timestamp();
161        let age_seconds = current.saturating_sub(self.entry.created_at);
162
163        // Exponential decay over 30 days
164        let decay_rate = 0.00002; // Decay constant
165        (-decay_rate * age_seconds as f32).exp()
166    }
167
168    fn current_timestamp() -> u64 {
169        std::time::SystemTime::now()
170            .duration_since(std::time::UNIX_EPOCH)
171            .unwrap()
172            .as_secs()
173    }
174}
175
176/// Configuration for advanced memory management
177#[derive(Debug, Clone, Serialize, Deserialize)]
178pub struct MemoryConfig {
179    /// Maximum number of working memory entries
180    pub working_memory_limit: usize,
181    /// Maximum number of episodic memory entries before consolidation
182    pub episodic_memory_limit: usize,
183    /// Enable automatic summarization
184    pub auto_summarize: bool,
185    /// Minimum conversation length (in messages) to trigger summarization
186    pub min_summary_length: usize,
187    /// Enable background consolidation
188    pub auto_consolidate: bool,
189    /// Consolidation interval in seconds
190    pub consolidation_interval: u64,
191    /// Similarity threshold for duplicate detection (0.0 to 1.0)
192    pub duplicate_threshold: f32,
193    /// Enable memory decay
194    pub enable_decay: bool,
195    /// Decay rate (per day)
196    pub decay_rate: f32,
197    /// Minimum importance level to prevent decay
198    pub min_importance_for_preservation: ImportanceLevel,
199}
200
201impl Default for MemoryConfig {
202    fn default() -> Self {
203        Self {
204            working_memory_limit: 10,
205            episodic_memory_limit: 100,
206            auto_summarize: true,
207            min_summary_length: 4,
208            auto_consolidate: true,
209            consolidation_interval: 3600, // 1 hour
210            duplicate_threshold: 0.85,
211            enable_decay: true,
212            decay_rate: 0.05, // 5% per day
213            min_importance_for_preservation: ImportanceLevel::High,
214        }
215    }
216}
217
218// ============================================
219// Module Declarations
220// ============================================
221
222mod manager;
223mod working;
224mod episodic;
225mod semantic;
226mod summarization;
227mod consolidation;
228mod utils;
229
230#[cfg(test)]
231mod tests;
232
233// ============================================
234// Public Exports
235// ============================================
236
237pub use manager::{AdvancedMemoryManager, MemoryStatistics};
238pub use working::WorkingMemory;
239pub use episodic::{EpisodicMemory, TimeRange, ActivitySummary};
240pub use semantic::{SemanticMemory, Entity, EntityType, Fact, Relationship, KnowledgeSummary, SemanticMemoryStats};
241pub use summarization::{Summarizer, SummaryStrategy, SummaryResult, ExtractedEntity, ExtractedFact, ImportantMoment};
242pub use consolidation::{Consolidator, ConsolidationTask, ConsolidationResult};
ceylon_next/memory/advanced/mod.rs

ceylon_next/memory/advanced/
mod.rs
