Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
M8 verification: lifecycle integration test + configurable DecayParams
AkitaOnRails28fe973c3346
diff --git a/Cargo.lock b/Cargo.lockindex 14b355fe..399dfc73 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -70,6 +70,7 @@ dependencies = ["ai-memory-wiki","anyhow","jiff",+ "rusqlite","schemars","serde","serde_json",diff --git a/crates/ai-memory-cli/src/commands/forget_sweep.rs b/crates/ai-memory-cli/src/commands/forget_sweep.rsindex d4dcd247..36704bee 100644--- a/crates/ai-memory-cli/src/commands/forget_sweep.rs+++ b/crates/ai-memory-cli/src/commands/forget_sweep.rs@@ -1,7 +1,7 @@//! `ai-memory forget-sweep` — run the M8 retention sweep manually.use ai_memory_consolidate::run_sweep;-use ai_memory_store::{DecayParams, Store};+use ai_memory_store::Store;use anyhow::{Context, Result};use crate::cli::ForgetSweepArgs;@@ -19,13 +19,12 @@ pub async fn run(config: &Config, args: ForgetSweepArgs) -> Result<()> {.writer.get_or_create_project(ws, "scratch", None).await?;- let params = DecayParams::default();let report = run_sweep(&store.reader,&store.writer,ws,proj,- ¶ms,+ &config.decay,args.dry_run,).await?;diff --git a/crates/ai-memory-cli/src/commands/init.rs b/crates/ai-memory-cli/src/commands/init.rsindex fec84e13..097a38cd 100644--- a/crates/ai-memory-cli/src/commands/init.rs+++ b/crates/ai-memory-cli/src/commands/init.rs@@ -56,8 +56,7 @@ mod tests {fn cfg_in(dir: &std::path::Path) -> Config {Config {data_dir: dir.to_path_buf(),- bind: "127.0.0.1:7777".into(),- log_level: "info".into(),+ ..Config::default()}}diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex a9372762..b9659c2a 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -50,7 +50,8 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {};let mut server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj)- .with_wiki(wiki.clone());+ .with_wiki(wiki.clone())+ .with_decay_params(config.decay);if let Some(cfg) = provider_from_env()? {let llm = ai_memory_llm::build_provider(cfg).context("building LLM provider from env")?;info!(diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex af0e9fda..66b7b273 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -25,6 +25,12 @@ pub struct Config {pub bind: String,/// Per-subsystem log filter (overridable by `RUST_LOG`).pub log_level: String,+ /// M8 retention-sweep parameters. The defaults give an ~80-day+ /// "survival floor" for unused episodic content (above the cold+ /// threshold), followed by ~180 days of soft-delete buffer before+ /// hard-deletion. Tune `decay.lambda` down to slow decay or+ /// `decay.cold_threshold` to evict more / less aggressively.+ pub decay: ai_memory_store::DecayParams,}impl Default for Config {@@ -33,6 +39,7 @@ impl Default for Config {data_dir: default_data_dir(),bind: "127.0.0.1:7777".into(),log_level: "info".into(),+ decay: ai_memory_store::DecayParams::default(),}}}diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.tomlindex 4634808a..bfa0f123 100644--- a/crates/ai-memory-cli/templates/config.default.toml+++ b/crates/ai-memory-cli/templates/config.default.toml@@ -11,3 +11,25 @@ bind = "127.0.0.1:7777"# Default tracing filter (overridable by RUST_LOG).log_level = "info"++# M8 retention-sweep parameters.+#+# Formula:+# retention = salience * exp(-lambda * age_days)+# + sigma * log(1 + access_count) * exp(-mu * days_since_access)+#+# With the defaults below, an unused episodic page drops below+# `cold_threshold = 0.20` at ~80 days; recent accesses bump it back up.+# Semantic / pinned pages are exempt from decay entirely. Tune to taste:+#+# - Slow decay (forget less aggressively): lambda = 0.01 (~140d floor)+# - Faster decay (clean up more aggressively): lambda = 0.04 (~40d floor)+# - Bigger access boost (frequently-used stuff lasts longer): sigma = 1.0+# - Bigger time-pressure on access: mu = 0.08+[decay]+lambda = 0.02+sigma = 0.6+mu = 0.04+salience_default = 1.0+cold_threshold = 0.20+hard_delete_after_days = 180diff --git a/crates/ai-memory-consolidate/Cargo.toml b/crates/ai-memory-consolidate/Cargo.tomlindex 9d403619..8ffa3a53 100644--- a/crates/ai-memory-consolidate/Cargo.toml+++ b/crates/ai-memory-consolidate/Cargo.toml@@ -24,6 +24,7 @@ jiff.workspace = true[dev-dependencies]tempfile.workspace = true+rusqlite.workspace = true[lints]workspace = truediff --git a/crates/ai-memory-consolidate/tests/lifecycle.rs b/crates/ai-memory-consolidate/tests/lifecycle.rsnew file mode 100644index 00000000..18794a9a--- /dev/null+++ b/crates/ai-memory-consolidate/tests/lifecycle.rs@@ -0,0 +1,420 @@+//! End-to-end retention-lifecycle integration test.+//!+//! Demonstrates that M8's hybrid policy actually does what the docs+//! claim: episodic pages decay over time unless they get queried;+//! semantic concept pages compound forever; pinned anything survives;+//! and after sweep, the FTS5 index actually loses the evicted content+//! while keeping everything else searchable.+//!+//! Time travel is simulated by backdating the `updated_at` /+//! `access_count` / `last_accessed_at` columns via a secondary+//! `rusqlite::Connection`. WAL mode + a busy_timeout means we can+//! safely write while the writer actor is idle between operations.++use std::collections::HashSet;++use ai_memory_consolidate::{run_lint, run_sweep};+use ai_memory_core::{PageId, PagePath, Tier};+use ai_memory_store::{DecayParams, Store};+use ai_memory_wiki::{Wiki, WritePageRequest};+use rusqlite::params;+use tempfile::TempDir;++const US_PER_DAY: i64 = 86_400_000_000;++/// One page in the lifecycle fixture.+struct Fixture {+ /// Wiki-relative path.+ path: &'static str,+ /// Body — chosen to give FTS5 a distinct keyword per page.+ body: &'static str,+ /// Tier.+ tier: Tier,+ /// `true` if frontmatter should carry `pinned: true`.+ pinned: bool,+ /// Days since `updated_at`.+ age_days: i64,+ /// Total accesses simulated.+ access_count: u32,+ /// Days since `last_accessed_at`, or `None` to leave NULL.+ days_since_access: Option<i64>,+ /// Whether the sweep should evict this page.+ expected_evicted: bool,+}++const FIXTURES: &[Fixture] = &[+ Fixture {+ path: "sessions/fresh.md",+ body: "Started exploring rmcp tool routing patterns today",+ tier: Tier::Episodic,+ pinned: false,+ age_days: 2,+ access_count: 0,+ days_since_access: None,+ expected_evicted: false,+ },+ // Mid-term untouched: 60 days old, never queried. The point of+ // including this is to demonstrate the formula isn't too eager:+ // an unused episodic page should still survive in the 2-month+ // window when default params are in play. With lambda=0.02 the+ // time-term at 60d is exp(-1.2) = 0.30, still well above the+ // cold_threshold of 0.20.+ Fixture {+ path: "sessions/midterm-untouched.md",+ body: "Notes on dyn dispatch trade-offs and downcast overhead, midterm reference",+ tier: Tier::Episodic,+ pinned: false,+ age_days: 60,+ access_count: 0,+ days_since_access: None,+ expected_evicted: false,+ },+ Fixture {+ path: "sessions/hot-old.md",+ body: "Investigation of writer-actor backpressure design and tokio mpsc bounded channels",+ tier: Tier::Episodic,+ pinned: false,+ age_days: 120,+ access_count: 50,+ days_since_access: Some(2),+ expected_evicted: false,+ },+ Fixture {+ path: "sessions/cold-old.md",+ body: "Quick spike on swapping jiff for an older datetime crate, abandoned mid-experiment",+ tier: Tier::Episodic,+ pinned: false,+ age_days: 120,+ access_count: 0,+ days_since_access: None,+ expected_evicted: true,+ },+ Fixture {+ path: "sessions/very-cold.md",+ body: "Tried bolting cognee's pipeline shape onto the rust workspace, didn't pan out",+ tier: Tier::Episodic,+ pinned: false,+ age_days: 200,+ access_count: 0,+ days_since_access: None,+ expected_evicted: true,+ },+ Fixture {+ path: "sessions/pinned-ancient.md",+ body: "Decision log: never re-add the iii-engine sidecar dependency",+ tier: Tier::Episodic,+ pinned: true,+ age_days: 300,+ access_count: 0,+ days_since_access: None,+ expected_evicted: false,+ },+ Fixture {+ path: "concepts/karpathy-wiki.md",+ body: "Karpathy LLM Wiki principle: compile knowledge into the artifact, do not re-retrieve",+ tier: Tier::Semantic,+ pinned: false,+ age_days: 300,+ access_count: 5,+ days_since_access: Some(60),+ expected_evicted: false,+ },+ Fixture {+ path: "concepts/single-writer.md",+ body: "All SQLite mutations flow through one writer actor backed by mpsc",+ tier: Tier::Semantic,+ pinned: false,+ age_days: 200,+ access_count: 0,+ days_since_access: None,+ expected_evicted: false,+ },+ Fixture {+ path: "concepts/wiki-conventions.md",+ body: "Wiki path conventions: sessions/, concepts/, decisions/, gotchas/",+ tier: Tier::Semantic,+ pinned: false,+ age_days: 30,+ access_count: 0,+ days_since_access: None,+ expected_evicted: false,+ },+];++/// Backdate one page's timestamps + access counters via a secondary+/// SQLite connection. WAL mode lets us write while the writer actor+/// is idle between operations.+fn backdate(db_path: &std::path::Path, now_us: i64, fixture: &Fixture, id: PageId) {+ let conn = rusqlite::Connection::open(db_path).expect("open aux conn");+ conn.pragma_update(None, "busy_timeout", 5_000).unwrap();+ let updated_at = now_us - fixture.age_days * US_PER_DAY;+ let last_access_us = fixture.days_since_access.map(|d| now_us - d * US_PER_DAY);+ conn.execute(+ "UPDATE pages \+ SET created_at = ?1, updated_at = ?1, access_count = ?2, last_accessed_at = ?3 \+ WHERE id = ?4",+ params![+ updated_at,+ i64::from(fixture.access_count),+ last_access_us,+ id.as_bytes(),+ ],+ )+ .expect("backdate update");+}++#[tokio::test]+async fn m8_retention_lifecycle_end_to_end() {+ // ── Phase 1 — bootstrap a fresh wiki + store ─────────────────+ let tmp = TempDir::new().expect("tempdir");+ let store = Store::open(tmp.path()).expect("open store");+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .expect("ws");+ let proj = store+ .writer+ .get_or_create_project(ws, "lifecycle-test", None)+ .await+ .expect("proj");+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).expect("wiki");++ // ── Phase 2 — seed the 8 fixtures through the normal write path ─+ let mut ids: Vec<(&'static str, PageId)> = Vec::new();+ for fx in FIXTURES {+ let title = format!("Page {}", fx.path);+ let mut frontmatter = serde_json::Map::new();+ frontmatter.insert("title".into(), serde_json::Value::String(title.clone()));+ if fx.pinned {+ frontmatter.insert("pinned".into(), serde_json::Value::Bool(true));+ }+ let id = wiki+ .write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new(fx.path.to_string()).expect("page path"),+ frontmatter: serde_json::Value::Object(frontmatter),+ body: fx.body.to_string(),+ tier: fx.tier,+ pinned: false,+ title: Some(title),+ })+ .await+ .expect("write page");+ ids.push((fx.path, id));+ }++ // ── Phase 3 — time-travel via direct SQL ────────────────────+ let now_us = jiff::Timestamp::now().as_microsecond();+ let db_path = tmp.path().join("db/memory.sqlite");+ for (fx, (_, id)) in FIXTURES.iter().zip(&ids) {+ backdate(&db_path, now_us, fx, *id);+ }++ // ── Phase 4 — dry-run sweep; verify the formula's verdict ───+ let params = DecayParams::default();+ let dry = run_sweep(+ &store.reader,+ &store.writer,+ ws,+ proj,+ ¶ms,+ /* dry_run */ true,+ )+ .await+ .expect("dry sweep");+ assert!(dry.dry_run);+ assert_eq!(+ dry.candidates_evaluated,+ FIXTURES.len(),+ "all {} pages should be considered as candidates",+ FIXTURES.len(),+ );++ let evicted: HashSet<&str> = dry.evicted.iter().map(|e| e.path.as_str()).collect();+ for fx in FIXTURES {+ let got = evicted.contains(fx.path);+ assert_eq!(+ got,+ fx.expected_evicted,+ "page {} expected_evicted={} but sweep said {} \+ (tier={:?}, pinned={}, age={}, access={}, days_since_access={:?})",+ fx.path,+ fx.expected_evicted,+ got,+ fx.tier,+ fx.pinned,+ fx.age_days,+ fx.access_count,+ fx.days_since_access,+ );+ }++ // ── Phase 5 — real sweep; verify row counts ─────────────────+ let counts_before = store.reader.status_counts().await.expect("counts before");+ assert_eq!(counts_before.pages_latest as usize, FIXTURES.len());+ assert_eq!(counts_before.pages_all as usize, FIXTURES.len());++ let real = run_sweep(+ &store.reader,+ &store.writer,+ ws,+ proj,+ ¶ms,+ /* dry_run */ false,+ )+ .await+ .expect("real sweep");+ assert!(!real.dry_run);+ let expected_evicted_count = FIXTURES.iter().filter(|f| f.expected_evicted).count();+ assert_eq!(real.evicted.len(), expected_evicted_count);++ let counts_after = store.reader.status_counts().await.expect("counts after");+ assert_eq!(+ counts_after.pages_latest as usize,+ FIXTURES.len() - expected_evicted_count,+ "is_latest=1 should drop by exactly the evicted count",+ );+ assert_eq!(+ counts_after.pages_all as usize,+ FIXTURES.len(),+ "soft-delete preserves the row (kept for 180d hard-delete window)",+ );++ // ── Phase 6 — FTS5 invariants ───────────────────────────────+ // Keywords unique to evicted pages should disappear from search.+ let cognee_hits = store+ .reader+ .search_pages("cognee".into(), 5)+ .await+ .expect("search cognee");+ assert!(+ cognee_hits.is_empty(),+ "evicted page 'very-cold' mentioned cognee; should be unsearchable now, got: {cognee_hits:?}",+ );++ let jiff_hits = store+ .reader+ .search_pages("jiff".into(), 5)+ .await+ .expect("search jiff");+ assert!(+ jiff_hits.is_empty(),+ "evicted page 'cold-old' mentioned jiff; should be unsearchable",+ );++ // Hot + semantic + pinned pages should still be searchable.+ // Note on FTS5: our tokenizer is `unicode61 tokenchars '/_-'`, so+ // `writer-actor` and `single-writer` are *single* tokens. We pick+ // distinct standalone keywords to test each page independently.+ let backpressure_hits = store+ .reader+ .search_pages("backpressure".into(), 5)+ .await+ .expect("search backpressure");+ let bp_paths: HashSet<&str> = backpressure_hits.iter().map(|h| h.path.as_str()).collect();+ assert!(+ bp_paths.contains("sessions/hot-old.md"),+ "hot reinforced page (with 'backpressure') should remain searchable: {bp_paths:?}",+ );++ let mutations_hits = store+ .reader+ .search_pages("mutations".into(), 5)+ .await+ .expect("search mutations");+ let mut_paths: HashSet<&str> = mutations_hits.iter().map(|h| h.path.as_str()).collect();+ assert!(+ mut_paths.contains("concepts/single-writer.md"),+ "semantic concept page (with 'mutations') should remain searchable: {mut_paths:?}",+ );++ let karpathy_hits = store+ .reader+ .search_pages("karpathy".into(), 5)+ .await+ .expect("search karpathy");+ let karpathy_paths: HashSet<&str> = karpathy_hits.iter().map(|h| h.path.as_str()).collect();+ assert!(+ karpathy_paths.contains("concepts/karpathy-wiki.md"),+ "300-day-old semantic page survives forever (no tier decay)",+ );++ // Note: our FTS5 tokenizer keeps `-` inside tokens, but the FTS5+ // *query parser* still treats a bare `-` as the NOT prefix. Search+ // for a standalone token from the body instead of `iii-engine`.+ let sidecar_hits = store+ .reader+ .search_pages("sidecar".into(), 5)+ .await+ .expect("search sidecar");+ let sidecar_paths: HashSet<&str> = sidecar_hits.iter().map(|h| h.path.as_str()).collect();+ assert!(+ sidecar_paths.contains("sessions/pinned-ancient.md"),+ "pinned ancient page survives regardless of age",+ );++ // The mid-term untouched page deserves its own assertion to make+ // the "don't forget too fast" property explicit — searching for a+ // term unique to that page should still return it.+ let midterm_hits = store+ .reader+ .search_pages("dyn".into(), 5)+ .await+ .expect("search dyn");+ let midterm_paths: HashSet<&str> = midterm_hits.iter().map(|h| h.path.as_str()).collect();+ assert!(+ midterm_paths.contains("sessions/midterm-untouched.md"),+ "60-day-old untouched episodic page should still be discoverable \+ (the formula isn't supposed to forget mid-term knowledge): {midterm_paths:?}",+ );++ // ── Phase 7 — lint catches the residual stale + duplicate signals ─+ let lint_report = run_lint(+ &store.reader,+ &wiki,+ None,+ ws,+ proj,+ /* dry_run */ true,+ )+ .await+ .expect("lint dry-run");+ // We added rule-based 'stale' detection for episodic pages >30d+ // with zero accesses. After sweep, the cold pages are no longer+ // is_latest=1 so they don't appear; but lint is a safety net for+ // anything that slipped through (e.g. user disabled sweep). Just+ // confirm the report shape is well-formed.+ for f in &lint_report.findings {+ assert!(+ !f.message.is_empty(),+ "every finding must have a human-readable message",+ );+ assert!(+ ["info", "warning", "error"].contains(&f.severity.as_str()),+ "severity must be one of info/warning/error, got {}",+ f.severity,+ );+ }++ // ── Phase 8 — retention scores ordering sanity check ────────+ // The dry-run report carries the actual scores. Verify they're+ // ordered the way the docs imply: hot pages > pinned-skipped+ // (which is absent) > cold pages (which got evicted).+ if let (Some(very_cold), Some(cold_old)) = (+ dry.evicted+ .iter()+ .find(|e| e.path == "sessions/very-cold.md"),+ dry.evicted+ .iter()+ .find(|e| e.path == "sessions/cold-old.md"),+ ) {+ assert!(+ very_cold.retention < cold_old.retention,+ "200d cold should score below 120d cold: very_cold={} cold_old={}",+ very_cold.retention,+ cold_old.retention,+ );+ }+}diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex f2c91599..c3c95cf6 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -6,7 +6,7 @@ use std::sync::Arc;use ai_memory_consolidate::{Consolidator, run_lint, run_sweep};use ai_memory_core::{AgentKind, NewHandoff, PageId, ProjectId, SessionId, WorkspaceId};use ai_memory_llm::LlmProvider;-use ai_memory_store::{ReaderPool, WriterHandle};+use ai_memory_store::{DecayParams, ReaderPool, WriterHandle};use ai_memory_wiki::Wiki;use rmcp::handler::server::router::tool::ToolRouter;use rmcp::handler::server::wrapper::Parameters;@@ -42,6 +42,9 @@ pub struct AiMemoryServer {/// write the lint report). `None` when the server was built/// without one — older `new()` callers stay safe.wiki: Option<Wiki>,+ /// M8 retention parameters. Defaults if not overridden by the+ /// caller (typically from the user's config.toml `[decay]` block).+ decay_params: DecayParams,// Read by the `#[tool_handler]` macro expansion; rustc's dead-code// analysis can't see that, so the lint must be allowed explicitly.#[allow(dead_code)]@@ -147,10 +150,19 @@ impl AiMemoryServer {consolidator: None,llm: None,wiki: None,+ decay_params: DecayParams::default(),tool_router: Self::tool_router(),}}+ /// Override the retention-sweep parameters (typically populated+ /// from the user's config.toml `[decay]` table).+ #[must_use]+ pub fn with_decay_params(mut self, params: DecayParams) -> Self {+ self.decay_params = params;+ self+ }+/// Attach the wiki handle. Without this, `memory_forget_sweep`/// and `memory_lint` cannot write their report pages.#[must_use]@@ -230,13 +242,12 @@ impl AiMemoryServer {&self,Parameters(args): Parameters<SweepArgs>,) -> Result<CallToolResult, McpError> {- let params = ai_memory_store::DecayParams::default();let report = run_sweep(&self.reader,&self.writer,self.workspace_id,self.project_id,- ¶ms,+ &self.decay_params,args.dry_run.unwrap_or(false),).await