Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
test(hooks): randomized invariants for the session brief
Victor Alencarbd04ec3f4182
diff --git a/crates/ai-memory-hooks/src/brief_tiers.rs b/crates/ai-memory-hooks/src/brief_tiers.rsindex fe69a419..830ff1c3 100644--- a/crates/ai-memory-hooks/src/brief_tiers.rs+++ b/crates/ai-memory-hooks/src/brief_tiers.rs@@ -370,4 +370,112 @@ mod tests {assert_eq!(plan.tiers, Vec::<BriefTier>::new());assert_eq!(plan.omitted_from, 0);}++ /// Randomized invariants over the assignment, driven by a fixed-seed+ /// xorshift (the seed is in every failure message). The `stress_`+ /// prefix keeps it out of the everyday `cargo t` profile; `cargo tf`,+ /// the pre-push hook and CI run it.+ mod stress_assignment {+ use super::*;++ struct Rng(u64);+ impl Rng {+ fn next(&mut self) -> u64 {+ let mut x = self.0;+ x ^= x << 13;+ x ^= x >> 7;+ x ^= x << 17;+ self.0 = x;+ x+ }+ fn below(&mut self, n: usize) -> usize {+ (self.next() % n as u64) as usize+ }+ }++ fn random_page(rng: &mut Rng) -> PageCosts {+ let l0 = 20 + rng.below(320);+ let l1 = l0 + [0, rng.below(300)][rng.below(2)];+ let l2 = [+ l1,+ l1 + rng.below(SHORT_BODY_SLACK * 2),+ l1 + rng.below(20_000),+ ][rng.below(3)];+ PageCosts {+ privileged: rng.below(4) == 0,+ title_only: 10 + rng.below(60),+ tiers: (rng.below(10) != 0).then_some([l0, l1, l2]),+ }+ }++ fn plan(pages: &[PageCosts], ceiling: usize, recent_full: usize) -> BriefPlan {+ assign_tiers(+ pages,+ BriefBudget {+ prefix: 100,+ content_ceiling: ceiling,+ recent_full,+ recent_first: recent_full.min(RECENT_FIRST),+ },+ |from| 40 + LISTED * (pages.len() - from),+ |_| COUNT_ONLY,+ )+ }++ #[test]+ fn assignment_invariants_hold_for_random_pages_and_budgets() {+ let seed = 0x5eed_b41e_f00d_u64;+ let mut rng = Rng(seed);+ for case in 0..3_000 {+ let pages: Vec<_> = (0..rng.below(25)).map(|_| random_page(&mut rng)).collect();+ let ceiling = 300 + rng.below(20_000);+ let recent_full = [0, 50 + rng.below(800)][rng.below(2)];+ let p = plan(&pages, ceiling, recent_full);+ let ctx =+ format!("seed {seed:#x} case {case}: {pages:?} ceiling {ceiling} -> {p:?}");++ // Pages and the reserves never exceed the ceiling.+ assert!(+ 100 + spent(&pages, &p) + p.recent_reserve <= ceiling.max(100),+ "{ctx}"+ );+ // Omitted pages are exactly a suffix.+ assert!(+ p.tiers[..p.omitted_from].iter().all(|t| *t != Omitted),+ "{ctx}"+ );+ assert!(+ p.tiers[p.omitted_from..].iter().all(|t| *t == Omitted),+ "{ctx}"+ );+ // A page with no excerpt is never deepened.+ for (page, tier) in pages.iter().zip(&p.tiers) {+ if page.tiers.is_none() {+ assert!(matches!(tier, TitleOnly | Omitted), "{ctx}");+ }+ }+ // While some page still waits for an L1 that would add+ // something, an unprivileged body is shown whole only when it+ // was within the short-body slack.+ let gate_closed = pages[..p.omitted_from]+ .iter()+ .zip(&p.tiers)+ .any(|(page, tier)| *tier == L0 && page.l1_adds());+ if gate_closed {+ for (page, tier) in pages.iter().zip(&p.tiers) {+ if *tier == L2 && !page.privileged {+ let [l0, l1, l2] = page.tiers.unwrap();+ assert!(l2 <= l0.max(l1) + SHORT_BODY_SLACK, "{ctx}");+ }+ }+ }+ // More budget never covers fewer pages.+ let wider = plan(&pages, ceiling + 1 + rng.below(4_000), recent_full);+ assert!(+ wider.omitted_from >= p.omitted_from,+ "{ctx} wider {wider:?}"+ );+ }+ }+ }}diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex ed67e6f9..4faae530 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -16726,6 +16726,182 @@ mod tests {}}+ /// Randomized end-to-end invariants of the rendered brief, driven by a+ /// fixed-seed xorshift (the seed and case are in every failure). The+ /// `stress_` prefix keeps it out of the everyday `cargo t` profile.+ mod stress_session_brief {+ use super::*;++ struct Rng(u64);+ impl Rng {+ fn next(&mut self) -> u64 {+ let mut x = self.0;+ x ^= x << 13;+ x ^= x >> 7;+ x ^= x << 17;+ self.0 = x;+ x+ }+ fn below(&mut self, n: usize) -> usize {+ (self.next() % n as u64) as usize+ }+ }++ const PIECES: &[&str] = &[+ "rule",+ "keep",+ "it",+ "boring.",+ "🦀",+ "émoji",+ "`code`",+ "- bullet",+ "\n",+ "\n\n",+ "\r\n",+ "# Heading",+ "**Status:** Accepted",+ "---",+ UNTRUSTED_HISTORY_START,+ UNTRUSTED_HISTORY_END,+ "<!--",+ "-->",+ ];++ fn text(rng: &mut Rng, max_words: usize) -> String {+ let words = rng.below(max_words + 1);+ let mut out = String::new();+ for _ in 0..words {+ out.push_str(PIECES[rng.below(PIECES.len())]);+ out.push(' ');+ }+ out+ }++ fn random_core(rng: &mut Rng) -> Vec<ai_memory_store::BriefPageBody> {+ let families = ["_rules", "_slots", "gotchas", "decisions", "notes"];+ (0..rng.below(BRIEF_CORE_PAGES_LIMIT + 1))+ .map(|i| {+ let mut frontmatter = serde_json::Map::new();+ if rng.below(3) == 0 {+ frontmatter.insert("abstract".into(), text(rng, 60).into());+ }+ if rng.below(3) == 0 {+ frontmatter.insert("summary".into(), text(rng, 120).into());+ }+ let body_words = [0, 8, 80, 800, 6_000][rng.below(5)];+ ai_memory_store::BriefPageBody {+ path: format!("{}/p{i:02}-page.md", families[rng.below(families.len())]),+ title: text(rng, 4),+ body: text(rng, body_words),+ pinned: rng.below(4) == 0,+ updated_at: "2026-10-13T00:00:00Z".into(),+ frontmatter_json: serde_json::Value::Object(frontmatter),+ }+ })+ .collect()+ }++ /// How many core pages the omitted section accounts for: the paths it+ /// lists plus any "…and N more" or bare count.+ fn omitted_accounted(section: &str, core: &[ai_memory_store::BriefPageBody]) -> usize {+ let listed = core+ .iter()+ .filter(|p| section.contains(&format!("- `{}`", p.path)))+ .count();+ let number_after = |marker: &str| {+ section.find(marker).and_then(|at| {+ section[at + marker.len()..]+ .chars()+ .take_while(char::is_ascii_digit)+ .collect::<String>()+ .parse::<usize>()+ .ok()+ })+ };+ listed+ + number_after("- …and ").unwrap_or(0)+ + number_after("\n**").filter(|_| listed == 0).unwrap_or(0)+ }++ #[test]+ fn rendered_brief_invariants_hold_for_random_hostile_pages() {+ let seed = 0x000b_41ef_5eed_u64;+ let mut rng = Rng(seed);+ for case in 0..600 {+ let core = random_core(&mut rng);+ let recent: Vec<_> = (0..rng.below(BRIEF_RECENT_PAGES_LIMIT + 1))+ .map(|i| ai_memory_store::BriefingPage {+ path: format!("notes/r{i:02}.md"),+ title: text(&mut rng, 6),+ kind: "fact".into(),+ updated_at: "2026-10-13T00:00:00Z".into(),+ })+ .collect();+ let budget = BRIEF_BUDGET_MIN + rng.below(BRIEF_BUDGET_MAX - BRIEF_BUDGET_MIN + 1);+ let ctx = format!("seed {seed:#x} case {case} budget {budget}");+ let Some(out) = render_session_brief(&core, &recent, budget) else {+ assert!(core.is_empty() && recent.is_empty(), "{ctx}");+ continue;+ };++ assert!(out.len() <= budget, "{ctx}: {} bytes", out.len());+ assert!(+ out.contains(ai_memory_core::UNTRUSTED_MEMORY_NOTICE),+ "{ctx}"+ );+ assert_eq!(out.matches(UNTRUSTED_HISTORY_START).count(), 1, "{ctx}");+ assert_eq!(out.matches(UNTRUSTED_HISTORY_END).count(), 1, "{ctx}");+ assert!(out.ends_with(BRIEF_AGENT_FOOTER), "{ctx}");+ assert!(!out.contains("[truncated by"), "{ctx}");+ assert_eq!(+ render_session_brief(&core, &recent, budget).as_deref(),+ Some(out.as_str()),+ "{ctx}: not deterministic"+ );++ // Every core page is accounted for exactly once: shown in+ // the page region, or reported by the omitted section.+ let fence_end = out.find(UNTRUSTED_HISTORY_END).unwrap();+ let omitted_at = out[..fence_end]+ .find("omitted by budget")+ .map(|at| out[..at].rfind("\n**").unwrap());+ let recent_at = out[..fence_end].find(BRIEF_RECENT_HEADER);+ let pages_end = omitted_at.or(recent_at).unwrap_or(fence_end);+ let pages_region = &out[..pages_end];+ let shown: Vec<usize> = core+ .iter()+ .enumerate()+ .filter(|(_, p)| {+ pages_region.contains(&format!("(`{}`)\n", p.path))+ || pages_region.contains(&format!("- `{}`", p.path))+ })+ .map(|(i, _)| i)+ .collect();+ assert_eq!(+ shown,+ (0..shown.len()).collect::<Vec<_>>(),+ "{ctx}: shown pages must be a prefix of the core"+ );+ let omitted = omitted_at.map_or(0, |at| {+ omitted_accounted(&out[at..recent_at.unwrap_or(fence_end)], &core)+ });+ assert_eq!(+ shown.len() + omitted,+ core.len(),+ "{ctx}: shown {} + omitted {omitted} != core {}\n{out}",+ shown.len(),+ core.len()+ );+ if !recent.is_empty() && omitted == 0 && shown.len() == core.len() {+ // Nothing crowded out: the recent pointers had their+ // share and the first one always fits at these budgets.+ assert!(recent_at.is_some(), "{ctx}: recent pointers dropped\n{out}");+ }+ }+ }+ }+/// A short page is one section of its full text, not an excerpt plus/// the same text again.#[test]