Skip to content

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.lock
index 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.rs
index 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,
- &params,
+ &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.rs
index 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.rs
index 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.rs
index 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.toml
index 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 = 180
diff --git a/crates/ai-memory-consolidate/Cargo.toml b/crates/ai-memory-consolidate/Cargo.toml
index 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 = true
diff --git a/crates/ai-memory-consolidate/tests/lifecycle.rs b/crates/ai-memory-consolidate/tests/lifecycle.rs
new file mode 100644
index 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,
+ &params,
+ /* 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,
+ &params,
+ /* 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.rs
index 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,
- &params,
+ &self.decay_params,
args.dry_run.unwrap_or(false),
)
.await