lean_ctx/core/
memory_lifecycle.rs

1//! Memory Lifecycle Management — consolidation, decay, compaction, archival.
2//!
3//! Runs automatically on knowledge stores to keep memory healthy:
4//! - Confidence decay over time
5//! - Semantic consolidation of similar facts
6//! - Compaction when limits are exceeded
7//! - Archival of old/unused facts
8
9use chrono::{DateTime, Duration, Utc};
10use serde::{Deserialize, Serialize};
11use std::path::PathBuf;
12
13use super::knowledge::KnowledgeFact;
14
15const DEFAULT_DECAY_RATE: f32 = 0.01;
16const DEFAULT_MAX_FACTS: usize = 1000;
17const LOW_CONFIDENCE_THRESHOLD: f32 = 0.3;
18const STALE_DAYS: i64 = 30;
19
20#[derive(Debug, Clone)]
21pub struct LifecycleConfig {
22    pub decay_rate_per_day: f32,
23    pub max_facts: usize,
24    pub low_confidence_threshold: f32,
25    pub stale_days: i64,
26    pub consolidation_similarity: f32,
27}
28
29impl Default for LifecycleConfig {
30    fn default() -> Self {
31        Self {
32            decay_rate_per_day: DEFAULT_DECAY_RATE,
33            max_facts: DEFAULT_MAX_FACTS,
34            low_confidence_threshold: LOW_CONFIDENCE_THRESHOLD,
35            stale_days: STALE_DAYS,
36            consolidation_similarity: 0.85,
37        }
38    }
39}
40
41#[derive(Debug, Default)]
42pub struct LifecycleReport {
43    pub decayed_count: usize,
44    pub consolidated_count: usize,
45    pub archived_count: usize,
46    pub compacted_count: usize,
47    pub remaining_facts: usize,
48}
49
50pub fn apply_confidence_decay(facts: &mut [KnowledgeFact], config: &LifecycleConfig) -> usize {
51    let now = Utc::now();
52    let mut count = 0;
53
54    for fact in facts.iter_mut() {
55        if !fact.is_current() {
56            continue;
57        }
58
59        if let Some(valid_until) = fact.valid_until {
60            if valid_until < now && fact.confidence > 0.1 {
61                fact.confidence = 0.1;
62                count += 1;
63                continue;
64            }
65        }
66
67        let days_since_confirmed = now.signed_duration_since(fact.last_confirmed).num_days() as f32;
68        let days_since_retrieved = fact
69            .last_retrieved
70            .map_or(3650.0, |t| now.signed_duration_since(t).num_days() as f32);
71        let retrieval_count = fact.retrieval_count as f32;
72
73        if days_since_confirmed > 0.0 {
74            // FadeMem-inspired: protect frequently/recently retrieved facts.
75            // Deterministic, local-only signals; never hard-delete (archive-only elsewhere).
76            let freq_protect = 1.0 / (1.0 + retrieval_count.ln_1p()); // 1.0 .. ~0.2
77            let recency_protect = (1.0 - (days_since_retrieved / 30.0).min(1.0)).max(0.0); // 1.0 if today, 0.0 after 30d
78            let protect = (freq_protect * (1.0 - 0.5 * recency_protect)).max(0.05);
79            let decay = config.decay_rate_per_day * days_since_confirmed * protect;
80            let new_confidence = (fact.confidence - decay).max(0.05);
81            if (new_confidence - fact.confidence).abs() > 0.001 {
82                fact.confidence = new_confidence;
83                count += 1;
84            }
85        }
86    }
87
88    count
89}
90
91pub fn consolidate_similar(facts: &mut Vec<KnowledgeFact>, similarity_threshold: f32) -> usize {
92    let mut to_remove: Vec<usize> = Vec::new();
93    let len = facts.len();
94
95    for i in 0..len {
96        if to_remove.contains(&i) || !facts[i].is_current() {
97            continue;
98        }
99
100        for j in (i + 1)..len {
101            if to_remove.contains(&j) || !facts[j].is_current() {
102                continue;
103            }
104
105            if facts[i].category != facts[j].category {
106                continue;
107            }
108
109            let sim = word_similarity(&facts[i].value, &facts[j].value);
110            if sim >= similarity_threshold {
111                if facts[i].confidence >= facts[j].confidence {
112                    facts[i].confirmation_count += facts[j].confirmation_count;
113                    if facts[j].last_confirmed > facts[i].last_confirmed {
114                        facts[i].last_confirmed = facts[j].last_confirmed;
115                    }
116                    to_remove.push(j);
117                } else {
118                    facts[j].confirmation_count += facts[i].confirmation_count;
119                    if facts[i].last_confirmed > facts[j].last_confirmed {
120                        facts[j].last_confirmed = facts[i].last_confirmed;
121                    }
122                    to_remove.push(i);
123                    break;
124                }
125            }
126        }
127    }
128
129    to_remove.sort_unstable();
130    to_remove.dedup();
131    let count = to_remove.len();
132
133    for idx in to_remove.into_iter().rev() {
134        facts.remove(idx);
135    }
136
137    count
138}
139
140pub fn compact(
141    facts: &mut Vec<KnowledgeFact>,
142    config: &LifecycleConfig,
143) -> (usize, Vec<KnowledgeFact>) {
144    let mut archived: Vec<KnowledgeFact> = Vec::new();
145    let now = Utc::now();
146    let stale_threshold = now - Duration::days(config.stale_days);
147
148    let mut to_archive: Vec<usize> = Vec::new();
149
150    for (i, fact) in facts.iter().enumerate() {
151        let recently_retrieved = fact
152            .last_retrieved
153            .is_some_and(|t| now.signed_duration_since(t).num_days() < 14);
154        let frequently_retrieved = fact.retrieval_count >= 5;
155
156        if fact.confidence < config.low_confidence_threshold {
157            to_archive.push(i);
158            continue;
159        }
160
161        if fact.last_confirmed < stale_threshold
162            && fact.confirmation_count <= 1
163            && fact.confidence < 0.5
164            && !recently_retrieved
165            && !frequently_retrieved
166        {
167            to_archive.push(i);
168        }
169    }
170
171    to_archive.sort_unstable();
172    to_archive.dedup();
173    let count = to_archive.len();
174
175    for idx in to_archive.into_iter().rev() {
176        archived.push(facts.remove(idx));
177    }
178
179    if facts.len() > config.max_facts {
180        facts.sort_by(|a, b| {
181            b.confidence
182                .partial_cmp(&a.confidence)
183                .unwrap_or(std::cmp::Ordering::Equal)
184        });
185        let excess: Vec<KnowledgeFact> = facts.drain(config.max_facts..).collect();
186        archived.extend(excess);
187    }
188
189    (count, archived)
190}
191
192pub fn run_lifecycle(facts: &mut Vec<KnowledgeFact>, config: &LifecycleConfig) -> LifecycleReport {
193    let decayed = apply_confidence_decay(facts, config);
194    let consolidated = consolidate_similar(facts, config.consolidation_similarity);
195    let (compacted, archived) = compact(facts, config);
196
197    if !archived.is_empty() {
198        let _ = archive_facts(&archived);
199    }
200
201    LifecycleReport {
202        decayed_count: decayed,
203        consolidated_count: consolidated,
204        archived_count: archived.len(),
205        compacted_count: compacted,
206        remaining_facts: facts.len(),
207    }
208}
209
210#[derive(Debug, Serialize, Deserialize)]
211struct ArchivedFacts {
212    pub archived_at: DateTime<Utc>,
213    pub facts: Vec<KnowledgeFact>,
214}
215
216fn archive_facts(facts: &[KnowledgeFact]) -> Result<(), String> {
217    let dir = crate::core::data_dir::lean_ctx_data_dir()?
218        .join("memory")
219        .join("archive");
220    std::fs::create_dir_all(&dir).map_err(|e| format!("{e}"))?;
221
222    let filename = format!("archive-{}.json", Utc::now().format("%Y%m%d-%H%M%S"));
223    let archive = ArchivedFacts {
224        archived_at: Utc::now(),
225        facts: facts.to_vec(),
226    };
227    let json = serde_json::to_string_pretty(&archive).map_err(|e| format!("{e}"))?;
228    std::fs::write(dir.join(filename), json).map_err(|e| format!("{e}"))
229}
230
231pub fn restore_archive(archive_path: &str) -> Result<Vec<KnowledgeFact>, String> {
232    let data = std::fs::read_to_string(archive_path).map_err(|e| format!("{e}"))?;
233    let archive: ArchivedFacts = serde_json::from_str(&data).map_err(|e| format!("{e}"))?;
234    Ok(archive.facts)
235}
236
237pub fn list_archives() -> Vec<PathBuf> {
238    let dir = match crate::core::data_dir::lean_ctx_data_dir() {
239        Ok(d) => d.join("memory").join("archive"),
240        Err(_) => return Vec::new(),
241    };
242
243    if !dir.exists() {
244        return Vec::new();
245    }
246
247    let mut archives: Vec<PathBuf> = std::fs::read_dir(&dir)
248        .into_iter()
249        .flatten()
250        .flatten()
251        .filter(|e| e.path().extension().is_some_and(|ext| ext == "json"))
252        .map(|e| e.path())
253        .collect();
254
255    archives.sort();
256    archives
257}
258
259fn word_similarity(a: &str, b: &str) -> f32 {
260    let a_lower = a.to_lowercase();
261    let b_lower = b.to_lowercase();
262    let a_words: std::collections::HashSet<&str> = a_lower.split_whitespace().collect();
263    let b_words: std::collections::HashSet<&str> = b_lower.split_whitespace().collect();
264
265    if a_words.is_empty() && b_words.is_empty() {
266        return 1.0;
267    }
268
269    let intersection = a_words.intersection(&b_words).count();
270    let union = a_words.union(&b_words).count();
271
272    if union == 0 {
273        return 0.0;
274    }
275
276    intersection as f32 / union as f32
277}
278
279#[cfg(test)]
280mod tests {
281    use super::*;
282
283    fn make_fact(category: &str, key: &str, value: &str, confidence: f32) -> KnowledgeFact {
284        KnowledgeFact {
285            category: category.to_string(),
286            key: key.to_string(),
287            value: value.to_string(),
288            source_session: "s1".to_string(),
289            confidence,
290            created_at: Utc::now(),
291            last_confirmed: Utc::now(),
292            retrieval_count: 0,
293            last_retrieved: None,
294            valid_from: Some(Utc::now()),
295            valid_until: None,
296            supersedes: None,
297            confirmation_count: 1,
298        }
299    }
300
301    fn make_old_fact(
302        category: &str,
303        key: &str,
304        value: &str,
305        confidence: f32,
306        days_old: i64,
307    ) -> KnowledgeFact {
308        let past = Utc::now() - Duration::days(days_old);
309        KnowledgeFact {
310            category: category.to_string(),
311            key: key.to_string(),
312            value: value.to_string(),
313            source_session: "s1".to_string(),
314            confidence,
315            created_at: past,
316            last_confirmed: past,
317            retrieval_count: 0,
318            last_retrieved: None,
319            valid_from: Some(past),
320            valid_until: None,
321            supersedes: None,
322            confirmation_count: 1,
323        }
324    }
325
326    #[test]
327    fn decay_reduces_confidence() {
328        let config = LifecycleConfig::default();
329        let mut facts = vec![make_old_fact("arch", "db", "PostgreSQL", 0.9, 10)];
330
331        let count = apply_confidence_decay(&mut facts, &config);
332        assert_eq!(count, 1);
333        assert!(facts[0].confidence < 0.9);
334        assert!(facts[0].confidence > 0.7);
335    }
336
337    #[test]
338    fn decay_skips_recent_facts() {
339        let config = LifecycleConfig::default();
340        let mut facts = vec![make_fact("arch", "db", "PostgreSQL", 0.9)];
341
342        let count = apply_confidence_decay(&mut facts, &config);
343        assert_eq!(count, 0);
344    }
345
346    #[test]
347    fn consolidate_similar_facts() {
348        let mut facts = vec![
349            make_fact("arch", "db", "uses PostgreSQL database", 0.8),
350            make_fact("arch", "db2", "uses PostgreSQL database system", 0.6),
351            make_fact("ops", "deploy", "docker compose up", 0.9),
352        ];
353
354        let count = consolidate_similar(&mut facts, 0.7);
355        assert!(count > 0, "Should consolidate similar facts");
356        assert!(facts.len() < 3);
357    }
358
359    #[test]
360    fn consolidate_keeps_different_categories() {
361        let mut facts = vec![
362            make_fact("arch", "db", "PostgreSQL", 0.8),
363            make_fact("ops", "db", "PostgreSQL", 0.8),
364        ];
365
366        let count = consolidate_similar(&mut facts, 0.9);
367        assert_eq!(count, 0, "Different categories should not consolidate");
368    }
369
370    #[test]
371    fn compact_removes_low_confidence() {
372        let config = LifecycleConfig::default();
373        let mut facts = vec![
374            make_fact("arch", "db", "PostgreSQL", 0.9),
375            make_fact("arch", "cache", "Redis", 0.1),
376        ];
377
378        let (count, archived) = compact(&mut facts, &config);
379        assert_eq!(count, 1);
380        assert_eq!(facts.len(), 1);
381        assert_eq!(archived.len(), 1);
382        assert_eq!(archived[0].key, "cache");
383    }
384
385    #[test]
386    fn compact_archives_stale_facts() {
387        let config = LifecycleConfig::default();
388        let mut facts = vec![
389            make_fact("arch", "db", "PostgreSQL", 0.9),
390            make_old_fact("arch", "old", "ancient thing", 0.4, 60),
391        ];
392
393        let (count, archived) = compact(&mut facts, &config);
394        assert_eq!(count, 1);
395        assert_eq!(archived[0].key, "old");
396    }
397
398    #[test]
399    fn full_lifecycle_run() {
400        let config = LifecycleConfig {
401            max_facts: 5,
402            ..Default::default()
403        };
404
405        let mut facts = vec![
406            make_fact("arch", "db", "PostgreSQL", 0.9),
407            make_fact("arch", "cache", "Redis", 0.8),
408            make_old_fact("arch", "old1", "thing1", 0.2, 50),
409            make_old_fact("arch", "old2", "thing2", 0.15, 60),
410            make_fact("ops", "deploy", "docker compose", 0.7),
411        ];
412
413        let report = run_lifecycle(&mut facts, &config);
414        assert!(report.remaining_facts <= config.max_facts);
415        assert!(report.decayed_count > 0 || report.compacted_count > 0);
416    }
417
418    #[test]
419    fn word_similarity_identical() {
420        assert!((word_similarity("hello world", "hello world") - 1.0).abs() < 0.01);
421    }
422
423    #[test]
424    fn word_similarity_partial() {
425        let sim = word_similarity("uses PostgreSQL database", "PostgreSQL database system");
426        assert!(sim >= 0.5, "Expected >= 0.5 but got {sim}");
427        assert!(sim < 1.0);
428    }
429
430    #[test]
431    fn word_similarity_different() {
432        let sim = word_similarity("Redis cache", "Docker compose");
433        assert!(sim < 0.1);
434    }
435}
lean_ctx/core/memory_lifecycle.rs

lean_ctx/core/
memory_lifecycle.rs
