//! Tri-memory system: the shared resident store the student and alter ego //! read from and write to. Four stores, one ecosystem. use std::collections::{HashMap, VecDeque}; use uuid::Uuid; /// A single captured interaction (raw diary entry). #[derive(Debug, Clone)] pub struct Experience { pub id: String, pub input: Vec, pub output: Vec, pub tool_calls: Vec, pub claims: Vec, /// SCoRe-style lineage: set on revision attempts pointing at attempt #1. pub parent_exp_id: Option, /// Episode advantage (delta-trust / task bonus) for weighted updates. pub advantage: f32, /// Natural-language form produced by the digestion pipeline. The alter-ego /// judge (cactus-needle) operates on *text*, so this must be populated for /// the real judge to score meaningfully. pub text: String, pub source: String, } impl Experience { pub fn new( input: Vec, output: Vec, claims: Vec, source: &str, ) -> Self { Self { id: Uuid::new_v4().to_string(), input, output, tool_calls: Vec::new(), claims, parent_exp_id: None, advantage: 1.0, text: String::new(), source: source.to_string(), } } /// Build an experience that already carries its digested text form. pub fn with_text( input: Vec, output: Vec, claims: Vec, text: String, source: &str, ) -> Self { Self { id: Uuid::new_v4().to_string(), input, output, tool_calls: Vec::new(), claims, parent_exp_id: None, advantage: 1.0, text, source: source.to_string(), } } } /// A validated fact: subject → relation → object. #[derive(Debug, Clone)] pub struct Triple { pub subject: String, pub relation: String, pub object: String, pub source_exp: String, } /// A reusable procedure tracked for success rate + staleness. #[derive(Debug, Clone)] pub struct Skill { pub name: String, pub successes: u32, pub attempts: u32, pub last_used_ts: f64, } impl Skill { pub fn success_rate(&self) -> f32 { if self.attempts == 0 { 0.0 } else { self.successes as f32 / self.attempts as f32 } } } /// Episodic memory — the raw diary of every interaction. #[derive(Debug, Default)] pub struct EpisodicMemory { pub entries: Vec, } impl EpisodicMemory { pub fn record(&mut self, e: Experience) { self.entries.push(e); } pub fn len(&self) -> usize { self.entries.len() } } /// Semantic memory — validated graph triples. #[derive(Debug, Default)] pub struct SemanticMemory { pub triples: Vec, } impl SemanticMemory { pub fn add(&mut self, t: Triple) { self.triples.push(t); } pub fn len(&self) -> usize { self.triples.len() } } /// Skill registry — procedures with success-rate + staleness tracking. #[derive(Debug, Default)] pub struct SkillRegistry { pub skills: HashMap, } impl SkillRegistry { pub fn observe(&mut self, name: &str, success: bool, now: f64) { let s = self .skills .entry(name.to_string()) .or_insert(Skill { name: name.to_string(), successes: 0, attempts: 0, last_used_ts: now, }); s.attempts += 1; if success { s.successes += 1; } s.last_used_ts = now; } pub fn staleness(&self, name: &str, now: f64) -> f64 { match self.skills.get(name) { Some(s) => (now - s.last_used_ts).max(0.0), None => f64::INFINITY, } } } /// Replay buffer — the anti-forgetting anchor set. Diversity-enforced: /// stratified by source so no single stream dominates. #[derive(Debug, Default)] pub struct ReplayBuffer { pub items: VecDeque, pub max: usize, } impl ReplayBuffer { pub fn new(max: usize) -> Self { Self { items: VecDeque::new(), max, } } pub fn push(&mut self, e: Experience) { self.items.push_back(e); while self.items.len() > self.max { self.items.pop_front(); } } /// Stratified sample: round-robin across distinct sources. pub fn sample(&self, n: usize) -> Vec<&Experience> { if self.items.is_empty() { return Vec::new(); } let mut by_src: HashMap> = HashMap::new(); for e in &self.items { by_src.entry(e.source.clone()).or_default().push(e); } let mut out = Vec::new(); let mut idx: HashMap<&str, usize> = HashMap::new(); while out.len() < n { let before = out.len(); for src in by_src.keys() { let i = idx.get(src.as_str()).copied().unwrap_or(0); if let Some(list) = by_src.get(src.as_str()) { if i < list.len() { out.push(list[i]); idx.insert(src.as_str(), i + 1); } } if out.len() >= n { break; } } if out.len() == before { break; // exhausted } } out } /// Gini coefficient of the source mix currently buffered (telemetry). pub fn gini_by_source(&self) -> f32 { let mut counts: HashMap<&str, usize> = HashMap::new(); for e in &self.items { *counts.entry(e.source.as_str()).or_default() += 1; } gini(&counts.values().copied().collect::>()) } /// Gini over a sampling run (PRD section 10: < 0.4 after stress). pub fn sample_gini(&self, batches: usize, n: usize) -> f32 { let mut picks: HashMap = HashMap::new(); for _ in 0..batches { // rotate start to emulate drift through the buffer for e in self.sample(n) { *picks.entry(e.id.clone()).or_default() += 1; } } let per_source: HashMap<&str, usize> = HashMap::new(); let _ = per_source; // aggregate picks by source let mut by_src: HashMap = HashMap::new(); for e in self.items.iter() { let c = picks.get(&e.id).copied().unwrap_or(0); *by_src.entry(e.source.clone()).or_default() += c; } gini(&by_src.values().copied().collect::>()) } } /// Gini coefficient of a count distribution (0 = perfectly equal). pub fn gini(counts: &[usize]) -> f32 { let n = counts.len(); if n <= 1 { return 0.0; } let total: usize = counts.iter().sum(); if total == 0 { return 0.0; } let mut vals: Vec = counts.iter().map(|&c| c as f64).collect(); vals.sort_by(|a, b| a.partial_cmp(b).unwrap()); let cum: f64 = vals .iter() .enumerate() .map(|(i, v)| (i as f64 + 1.0) * v) .sum(); let t = total as f64; ((2.0 * cum) / (t * n as f64) - ((n as f64 + 1.0) / n as f64)) as f32 } /// Pending-revalidation store (PRD verdict table: QUEUE = "store for /// re-validation, don't discard"). Committed-only replay stays pure; queued /// experiences wait here for a later pass. #[derive(Debug, Default)] pub struct ValidationLedger { pub pending: VecDeque<(Experience, f64)>, // (exp, enqueued_ts) pub cap: usize, } impl ValidationLedger { pub fn with_capacity_default(cap: usize) -> Self { Self { pending: VecDeque::new(), cap } } pub fn push(&mut self, e: Experience, now: f64) { self.pending.push_back((e, now)); while self.pending.len() > self.cap { self.pending.pop_front(); } } pub fn len(&self) -> usize { self.pending.len() } pub fn is_empty(&self) -> bool { self.pending.is_empty() } /// Drain up to `n` oldest for a re-validation pass. pub fn drain(&mut self, n: usize) -> Vec { let mut out = Vec::with_capacity(n); for _ in 0..n { match self.pending.pop_front() { Some((e, _)) => out.push(e), None => break, } } out } } /// The unified tri-memory ecosystem. #[derive(Debug)] pub struct TriMemory { pub episodic: EpisodicMemory, pub semantic: SemanticMemory, pub skills: SkillRegistry, pub replay: ReplayBuffer, pub ledger: ValidationLedger, } impl TriMemory { pub fn new(replay_max: usize) -> Self { Self::with_ledger(replay_max, 100_000) } pub fn with_ledger(replay_max: usize, ledger_cap: usize) -> Self { Self { episodic: EpisodicMemory::default(), semantic: SemanticMemory::default(), skills: SkillRegistry::default(), replay: ReplayBuffer::new(replay_max), ledger: ValidationLedger::with_capacity_default(ledger_cap), } } } #[cfg(test)] mod tests { use super::*; #[test] fn replay_gini_stays_under_prd_gate() { // 10k committed experiences across 5 skewed sources (PRD section 10: // 10k micro-step stress => stratified sampler keeps Gini < 0.4) let mut m = TriMemory::new(20_000); let counts = [("s0", 5000usize), ("s1", 3000), ("s2", 1000), ("s3", 600), ("s4", 400)]; let mut id = 0usize; for (src, n) in counts { for _ in 0..n { m.replay.push(Experience::with_text( vec![(id % 61) as u32], vec![((id + 7) % 61) as u32], vec![format!("fact {id}")], format!("doc {id} about {src}"), src, )); id += 1; } } assert_eq!(m.replay.items.len(), 10_000); let buffered = m.replay.gini_by_source(); assert!(buffered > 0.2, "fixture should be skewed: {buffered}"); let sampled = m.replay.sample_gini(200, 50); assert!(sampled < 0.4, "stratified sampling must keep Gini < 0.4, got {sampled}"); } }