alter_ego / serving /src /memory.rs
geraldaton20's picture
initial upload: source code (no build artifacts)
f4f166e verified
Raw History Blame Contribute Delete
10.8 kB
//! 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<u32>,
pub output: Vec<u32>,
pub tool_calls: Vec<String>,
pub claims: Vec<String>,
/// SCoRe-style lineage: set on revision attempts pointing at attempt #1.
pub parent_exp_id: Option<String>,
/// 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<u32>,
output: Vec<u32>,
claims: Vec<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: String::new(),
source: source.to_string(),
}
}
/// Build an experience that already carries its digested text form.
pub fn with_text(
input: Vec<u32>,
output: Vec<u32>,
claims: Vec<String>,
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<Experience>,
}
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<Triple>,
}
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<String, Skill>,
}
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<Experience>,
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<String, Vec<&Experience>> = 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::<Vec<_>>())
}
/// 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<String, usize> = 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<String, usize> = 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::<Vec<_>>())
}
}
/// 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<f64> = 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<Experience> {
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}");
}
}