Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

M8: lint + decay (hybrid policy, access reinforcement, LLM contradictions)

AkitaOnRailsfd3d5db90d2a
diff --git a/Cargo.lock b/Cargo.lock
index 16d2f265..14b355fe 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -33,6 +33,7 @@ dependencies = [
name = "ai-memory-cli"
version = "0.1.0"
dependencies = [
+ "ai-memory-consolidate",
"ai-memory-core",
"ai-memory-hooks",
"ai-memory-llm",
@@ -68,6 +69,7 @@ dependencies = [
"ai-memory-store",
"ai-memory-wiki",
"anyhow",
+ "jiff",
"schemars",
"serde",
"serde_json",
diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.toml
index d6aee2d9..1808979b 100644
--- a/crates/ai-memory-cli/Cargo.toml
+++ b/crates/ai-memory-cli/Cargo.toml
@@ -13,6 +13,7 @@ name = "ai-memory"
path = "src/main.rs"
[dependencies]
+ai-memory-consolidate.workspace = true
ai-memory-core.workspace = true
ai-memory-hooks.workspace = true
ai-memory-llm.workspace = true
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 45b7a0cc..0ff92668 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -51,6 +51,10 @@ pub enum Command {
Commit(CommitArgs),
/// Smoke-test an LLM provider by sending one prompt.
LlmTest(LlmTestArgs),
+ /// Run the M8 retention sweep over episodic pages.
+ ForgetSweep(ForgetSweepArgs),
+ /// Run the M8 lint pass (stale / duplicates + optional LLM contradiction).
+ Lint(LintArgs),
}
/// Arguments for `init`.
@@ -150,6 +154,28 @@ pub enum LlmProviderChoice {
OpenaiCompat,
}
+/// Arguments for `forget-sweep`.
+#[derive(Debug, Args)]
+pub struct ForgetSweepArgs {
+ /// Report what would be evicted without actually mutating.
+ #[arg(long)]
+ pub dry_run: bool,
+}
+
+/// Arguments for `lint`.
+#[derive(Debug, Args)]
+pub struct LintArgs {
+ /// Compute findings but don't write `wiki/_lint/<date>.md`.
+ #[arg(long)]
+ pub dry_run: bool,
+ /// Workspace name (auto-created if absent).
+ #[arg(long, default_value = "default")]
+ pub workspace: String,
+ /// Project name within the workspace (auto-created if absent).
+ #[arg(long, default_value = "scratch")]
+ pub project: String,
+}
+
/// Arguments for `llm-test`.
#[derive(Debug, Args)]
pub struct LlmTestArgs {
diff --git a/crates/ai-memory-cli/src/commands/forget_sweep.rs b/crates/ai-memory-cli/src/commands/forget_sweep.rs
new file mode 100644
index 00000000..d4dcd247
--- /dev/null
+++ b/crates/ai-memory-cli/src/commands/forget_sweep.rs
@@ -0,0 +1,34 @@
+//! `ai-memory forget-sweep` — run the M8 retention sweep manually.
+
+use ai_memory_consolidate::run_sweep;
+use ai_memory_store::{DecayParams, Store};
+use anyhow::{Context, Result};
+
+use crate::cli::ForgetSweepArgs;
+use crate::config::Config;
+
+/// Run the `forget-sweep` subcommand.
+///
+/// # Errors
+/// Returns an error if the store cannot be opened or the sweep fails.
+pub async fn run(config: &Config, args: ForgetSweepArgs) -> Result<()> {
+ let store = Store::open(&config.data_dir)
+ .with_context(|| format!("opening store at {}", config.data_dir.display()))?;
+ let ws = store.writer.get_or_create_workspace("default").await?;
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "scratch", None)
+ .await?;
+ let params = DecayParams::default();
+ let report = run_sweep(
+ &store.reader,
+ &store.writer,
+ ws,
+ proj,
+ &params,
+ args.dry_run,
+ )
+ .await?;
+ println!("{}", serde_json::to_string_pretty(&report)?);
+ Ok(())
+}
diff --git a/crates/ai-memory-cli/src/commands/lint.rs b/crates/ai-memory-cli/src/commands/lint.rs
new file mode 100644
index 00000000..297d042f
--- /dev/null
+++ b/crates/ai-memory-cli/src/commands/lint.rs
@@ -0,0 +1,40 @@
+//! `ai-memory lint` — run the M8 lint pass manually.
+
+use ai_memory_consolidate::run_lint;
+use ai_memory_llm::{build_provider, provider_from_env};
+use ai_memory_store::Store;
+use ai_memory_wiki::Wiki;
+use anyhow::{Context, Result};
+
+use crate::cli::LintArgs;
+use crate::config::Config;
+
+/// Run the `lint` subcommand.
+///
+/// # Errors
+/// Returns an error if the store cannot be opened or the lint pass
+/// fails.
+pub async fn run(config: &Config, args: LintArgs) -> Result<()> {
+ let store = Store::open(&config.data_dir)
+ .with_context(|| format!("opening store at {}", config.data_dir.display()))?;
+ let ws = store
+ .writer
+ .get_or_create_workspace(args.workspace.clone())
+ .await?;
+ let proj = store
+ .writer
+ .get_or_create_project(ws, args.project.clone(), None)
+ .await?;
+ let wiki = Wiki::new(&config.data_dir, store.writer.clone())?;
+
+ // Build provider if env configured; otherwise rule-based only.
+ let llm = if let Some(cfg) = provider_from_env()? {
+ Some(build_provider(cfg)?)
+ } else {
+ None
+ };
+
+ let report = run_lint(&store.reader, &wiki, llm.as_ref(), ws, proj, args.dry_run).await?;
+ println!("{}", serde_json::to_string_pretty(&report)?);
+ Ok(())
+}
diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rs
index 8474ea69..882d9b9c 100644
--- a/crates/ai-memory-cli/src/commands/mod.rs
+++ b/crates/ai-memory-cli/src/commands/mod.rs
@@ -2,8 +2,10 @@
pub mod backup;
pub mod commit;
+pub mod forget_sweep;
pub mod init;
pub mod install_hooks;
+pub mod lint;
pub mod llm_test;
pub mod reset;
pub mod restore;
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 517c2550..a9372762 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -49,17 +49,20 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
Some(WatcherHandle::start(wiki.clone(), ws, proj)?)
};
- let mut server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj);
+ let mut server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj)
+ .with_wiki(wiki.clone());
if let Some(cfg) = provider_from_env()? {
let llm = ai_memory_llm::build_provider(cfg).context("building LLM provider from env")?;
info!(
provider = llm.name(),
model = llm.model(),
- "memory_consolidate tool enabled",
+ "memory_consolidate + memory_lint LLM features enabled",
);
server = server.with_consolidator(wiki.clone(), llm);
} else {
- info!("AI_MEMORY_LLM_PROVIDER unset; memory_consolidate disabled");
+ info!(
+ "AI_MEMORY_LLM_PROVIDER unset; memory_consolidate disabled, lint runs rule-based only"
+ );
}
match args.transport {
diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rs
index 02d6d3ab..8954ca67 100644
--- a/crates/ai-memory-cli/src/main.rs
+++ b/crates/ai-memory-cli/src/main.rs
@@ -49,5 +49,7 @@ async fn main() -> Result<()> {
Command::InstallHooks(args) => commands::install_hooks::run(&config, args),
Command::Commit(args) => commands::commit::run(&config, args),
Command::LlmTest(args) => commands::llm_test::run(&config, args).await,
+ Command::ForgetSweep(args) => commands::forget_sweep::run(&config, args).await,
+ Command::Lint(args) => commands::lint::run(&config, args).await,
}
}
diff --git a/crates/ai-memory-consolidate/Cargo.toml b/crates/ai-memory-consolidate/Cargo.toml
index 4acb7e57..9d403619 100644
--- a/crates/ai-memory-consolidate/Cargo.toml
+++ b/crates/ai-memory-consolidate/Cargo.toml
@@ -20,6 +20,7 @@ serde_json.workspace = true
schemars.workspace = true
tokio.workspace = true
tracing.workspace = true
+jiff.workspace = true
[dev-dependencies]
tempfile.workspace = true
diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rs
index 8f4d8fd2..00237907 100644
--- a/crates/ai-memory-consolidate/src/lib.rs
+++ b/crates/ai-memory-consolidate/src/lib.rs
@@ -9,9 +9,13 @@
//! M7b extends this to multi-page atomic fan-out.
pub mod consolidator;
+pub mod lint;
+pub mod sweep;
pub mod types;
pub use consolidator::{Consolidator, ConsolidatorError, ConsolidatorResult};
+pub use lint::{LintError, LintFinding, LintReport, run_lint};
+pub use sweep::{EvictedPage, SweepError, SweepReport, run_sweep};
pub use types::{
ConsolidatedBatch, ConsolidatedPage, ConsolidatedPageUpdate, ConsolidationOutcome,
};
diff --git a/crates/ai-memory-consolidate/src/lint.rs b/crates/ai-memory-consolidate/src/lint.rs
new file mode 100644
index 00000000..3bd6666e
--- /dev/null
+++ b/crates/ai-memory-consolidate/src/lint.rs
@@ -0,0 +1,297 @@
+//! M8 lint pass — rule-based wiki health check + optional LLM-driven
+//! contradiction detection.
+//!
+//! Two layers:
+//!
+//! 1. **Rule-based** (no LLM, always on): stale episodic pages
+//! (>30d old with zero accesses), pages with empty bodies,
+//! duplicate-by-title across paths.
+//! 2. **LLM-driven** (opt-in via the provider): clusters the latest
+//! semantic pages, feeds them to the LLM with a structured-output
+//! prompt asking for contradictions / stale claims.
+//!
+//! Findings are written to `wiki/_lint/<YYYY-MM-DD>.md` so they're
+//! grep-able and tracked in git.
+
+use ai_memory_core::{PagePath, ProjectId, Tier, WorkspaceId};
+use ai_memory_llm::{ChatMessage, ChatRequest, LlmProvider, Role, complete_structured};
+use ai_memory_store::{DecayCandidate, ReaderPool};
+use ai_memory_wiki::{Wiki, WritePageRequest};
+use jiff::Timestamp;
+use jiff::tz::TimeZone;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+use tracing::warn;
+
+/// One lint finding (rule-based or LLM-emitted).
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct LintFinding {
+ /// Discriminator: `contradiction` | `stale` | `duplicate` | `empty` | `other`.
+ pub kind: String,
+ /// `info` | `warning` | `error`.
+ pub severity: String,
+ /// One-paragraph description.
+ pub message: String,
+ /// Wiki paths the finding refers to.
+ #[serde(default)]
+ pub pages: Vec<String>,
+}
+
+/// Structured output the LLM produces.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct LintReport {
+ /// Findings the LLM identified.
+ pub findings: Vec<LintFinding>,
+}
+
+/// Errors raised by the lint pass.
+#[derive(Debug, Error)]
+#[non_exhaustive]
+pub enum LintError {
+ /// Underlying store error.
+ #[error(transparent)]
+ Store(#[from] ai_memory_store::StoreError),
+ /// Underlying wiki error.
+ #[error(transparent)]
+ Wiki(#[from] ai_memory_wiki::WikiError),
+ /// Underlying LLM error.
+ #[error(transparent)]
+ Llm(#[from] ai_memory_llm::LlmError),
+ /// Domain error (e.g. invalid page path).
+ #[error(transparent)]
+ Memory(#[from] ai_memory_core::MemoryError),
+}
+
+const US_PER_DAY: f64 = 86_400_000_000.0;
+/// Cap on pages fed to the LLM contradiction pass (token budget).
+pub const LLM_CLUSTER_CAP: usize = 20;
+/// Stale threshold: an unused page this many days old is flagged.
+pub const STALE_DAYS: f64 = 30.0;
+
+/// Run the lint pass.
+///
+/// * `llm` — when `Some`, the contradiction pass runs; otherwise the
+/// report contains only rule-based findings.
+/// * `dry_run` — when `true`, no file is written.
+///
+/// # Errors
+/// Returns [`LintError`] for any store / wiki / LLM failure.
+pub async fn run_lint(
+ reader: &ReaderPool,
+ wiki: &Wiki,
+ llm: Option<&std::sync::Arc<dyn LlmProvider>>,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ dry_run: bool,
+) -> Result<LintReport, LintError> {
+ let candidates = reader.decay_candidates(workspace_id, project_id).await?;
+ let mut findings = rule_based_findings(&candidates);
+
+ if let Some(provider) = llm {
+ match contradiction_pass(provider.clone(), wiki, &candidates).await {
+ Ok(mut extra) => findings.append(&mut extra),
+ Err(e) => warn!(error = %e, "lint LLM contradiction pass failed"),
+ }
+ }
+
+ let report = LintReport { findings };
+
+ if !dry_run && !report.findings.is_empty() {
+ write_report_page(wiki, workspace_id, project_id, &report).await?;
+ }
+
+ Ok(report)
+}
+
+fn rule_based_findings(candidates: &[DecayCandidate]) -> Vec<LintFinding> {
+ let now_us = Timestamp::now().as_microsecond();
+ let mut out = Vec::new();
+ let mut titles: std::collections::HashMap<String, Vec<String>> =
+ std::collections::HashMap::new();
+
+ for c in candidates {
+ // Stale: episodic, >30d, zero accesses.
+ #[allow(clippy::cast_precision_loss)]
+ let age_days = (now_us - c.updated_at_us) as f64 / US_PER_DAY;
+ if c.tier == Tier::Episodic && age_days > STALE_DAYS && c.access_count == 0 {
+ out.push(LintFinding {
+ kind: "stale".into(),
+ severity: "info".into(),
+ message: format!(
+ "Episodic page {} is {:.0} days old with zero accesses",
+ c.path, age_days,
+ ),
+ pages: vec![c.path.as_str().to_string()],
+ });
+ }
+ // Duplicate-title tracking: peek the frontmatter for a `title` field.
+ if let Ok(fm) = serde_json::from_str::<serde_json::Value>(&c.frontmatter_json)
+ && let Some(t) = fm.get("title").and_then(serde_json::Value::as_str)
+ {
+ titles
+ .entry(t.to_lowercase())
+ .or_default()
+ .push(c.path.as_str().to_string());
+ }
+ }
+
+ for (title, paths) in titles {
+ if paths.len() > 1 {
+ out.push(LintFinding {
+ kind: "duplicate".into(),
+ severity: "warning".into(),
+ message: format!("Multiple pages share title {title:?}"),
+ pages: paths,
+ });
+ }
+ }
+
+ out
+}
+
+async fn contradiction_pass(
+ provider: std::sync::Arc<dyn LlmProvider>,
+ wiki: &Wiki,
+ candidates: &[DecayCandidate],
+) -> Result<Vec<LintFinding>, LintError> {
+ // Focus on semantic / procedural pages — those are the ones the
+ // user actually compounds knowledge on.
+ let mut subset: Vec<&DecayCandidate> = candidates
+ .iter()
+ .filter(|c| matches!(c.tier, Tier::Semantic | Tier::Procedural))
+ .collect();
+ if subset.len() < 2 {
+ return Ok(Vec::new());
+ }
+ // Prefer high-access pages so the LLM sees the canonical knowledge.
+ subset.sort_by_key(|c| std::cmp::Reverse(c.access_count));
+ subset.truncate(LLM_CLUSTER_CAP);
+
+ let mut prompt = String::new();
+ prompt.push_str(
+ "Audit the following wiki pages for contradictions, stale claims, or \
+ duplicate information. Return a LintReport with one finding per issue.\n\n",
+ );
+ for c in &subset {
+ let preview = wiki
+ .read_page(&c.path)
+ .map(|md| md.body.chars().take(400).collect::<String>())
+ .unwrap_or_else(|_| "(unable to read)".into());
+ prompt.push_str(&format!("## `{}`\n\n{}\n\n---\n\n", c.path, preview));
+ }
+
+ let request = ChatRequest {
+ system: Some(
+ "You audit a personal coding-knowledge wiki for contradictions across pages. \
+ Return findings only when there's a real conflict; do not invent issues."
+ .into(),
+ ),
+ messages: vec![ChatMessage {
+ role: Role::User,
+ content: prompt,
+ }],
+ max_tokens: 2000,
+ temperature: Some(0.1),
+ };
+ let report: LintReport = complete_structured(&*provider, request).await?;
+ Ok(report.findings)
+}
+
+async fn write_report_page(
+ wiki: &Wiki,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ report: &LintReport,
+) -> Result<(), LintError> {
+ let date = Timestamp::now()
+ .to_zoned(TimeZone::UTC)
+ .strftime("%Y-%m-%d")
+ .to_string();
+ let path = PagePath::new(format!("_lint/{date}.md"))?;
+ let title = format!("Lint report {date}");
+ let body = render_markdown(report);
+ wiki.write_page(WritePageRequest {
+ workspace_id,
+ project_id,
+ path,
+ frontmatter: serde_json::json!({
+ "title": title.clone(),
+ "tier": "semantic",
+ "kind": "lint-report",
+ }),
+ body,
+ tier: Tier::Semantic,
+ pinned: false,
+ title: Some(title),
+ })
+ .await?;
+ Ok(())
+}
+
+fn render_markdown(report: &LintReport) -> String {
+ let mut buf = String::new();
+ buf.push_str("# Lint findings\n\n");
+ if report.findings.is_empty() {
+ buf.push_str("_No findings._\n");
+ return buf;
+ }
+ buf.push_str(&format!("{} finding(s).\n\n", report.findings.len()));
+ for (i, f) in report.findings.iter().enumerate() {
+ buf.push_str(&format!("## {} — {} ({})\n\n", i + 1, f.kind, f.severity));
+ buf.push_str(&format!("{}\n\n", f.message));
+ if !f.pages.is_empty() {
+ buf.push_str("Pages:\n");
+ for p in &f.pages {
+ buf.push_str(&format!("- `{p}`\n"));
+ }
+ buf.push('\n');
+ }
+ }
+ buf
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn rule_pass_flags_stale_episodic() {
+ let very_old = Timestamp::now().as_microsecond() - (90 * 86_400_000_000i64);
+ let candidates = vec![DecayCandidate {
+ id: ai_memory_core::PageId::new(),
+ path: ai_memory_core::PagePath::new("sessions/old.md").unwrap(),
+ tier: Tier::Episodic,
+ pinned: false,
+ updated_at_us: very_old,
+ access_count: 0,
+ last_accessed_at_us: None,
+ frontmatter_json: "{}".into(),
+ }];
+ let findings = rule_based_findings(&candidates);
+ assert_eq!(findings.len(), 1);
+ assert_eq!(findings[0].kind, "stale");
+ }
+
+ #[test]
+ fn rule_pass_flags_duplicate_titles() {
+ let a = DecayCandidate {
+ id: ai_memory_core::PageId::new(),
+ path: ai_memory_core::PagePath::new("concepts/a.md").unwrap(),
+ tier: Tier::Semantic,
+ pinned: false,
+ updated_at_us: Timestamp::now().as_microsecond(),
+ access_count: 0,
+ last_accessed_at_us: None,
+ frontmatter_json: r#"{"title": "Karpathy Wiki"}"#.into(),
+ };
+ let b = DecayCandidate {
+ path: ai_memory_core::PagePath::new("concepts/b.md").unwrap(),
+ ..a.clone()
+ };
+ let findings = rule_based_findings(&[a, b]);
+ let dupes: Vec<_> = findings.iter().filter(|f| f.kind == "duplicate").collect();
+ assert_eq!(dupes.len(), 1);
+ assert_eq!(dupes[0].pages.len(), 2);
+ }
+}
diff --git a/crates/ai-memory-consolidate/src/sweep.rs b/crates/ai-memory-consolidate/src/sweep.rs
new file mode 100644
index 00000000..2a5ddfb1
--- /dev/null
+++ b/crates/ai-memory-consolidate/src/sweep.rs
@@ -0,0 +1,200 @@
+//! M8 forget sweep — episodic-only retention pass.
+//!
+//! Walks the `is_latest = 1` pages for a project, computes the
+//! retention score for each via [`ai_memory_store::retention_score`],
+//! and soft-deletes those below threshold. Semantic / procedural /
+//! working tiers are skipped (M8 policy: semantic compounds, only
+//! episodic decays). Pinned pages (schema flag OR `pinned: true` in
+//! frontmatter) are exempt regardless of tier.
+//!
+//! Hard-delete pass cleans up rows soft-deleted more than
+//! `hard_delete_after_days` ago that received zero subsequent access.
+//! M7 supersession rows are safe: they have `supersedes IS NOT NULL`
+//! and therefore never match the hard-delete predicate.
+
+use ai_memory_core::{PageId, ProjectId, Tier, WorkspaceId};
+use ai_memory_store::{DecayCandidate, DecayParams, ReaderPool, WriterHandle, retention_score};
+use jiff::Timestamp;
+use serde::Serialize;
+use thiserror::Error;
+
+/// One evicted page surfaced in the [`SweepReport`].
+#[derive(Debug, Clone, Serialize)]
+pub struct EvictedPage {
+ /// Identifier of the soft-deleted page.
+ pub id: PageId,
+ /// Relative wiki path.
+ pub path: String,
+ /// Retention score at the time of the sweep.
+ pub retention: f64,
+ /// Days since the page's last update.
+ pub age_days: f64,
+ /// Total access count.
+ pub access_count: u32,
+}
+
+/// Outcome of one sweep run.
+#[derive(Debug, Clone, Serialize)]
+pub struct SweepReport {
+ /// `true` if `dry_run` was set and no rows were actually mutated.
+ pub dry_run: bool,
+ /// Total candidates evaluated (all tiers, before filtering).
+ pub candidates_evaluated: usize,
+ /// Pages that fell below the cold threshold (soft-deleted unless
+ /// `dry_run`).
+ pub evicted: Vec<EvictedPage>,
+ /// Number of older soft-deleted rows hard-deleted on this pass.
+ pub hard_deleted: usize,
+}
+
+/// Errors raised by the sweep.
+#[derive(Debug, Error)]
+#[non_exhaustive]
+pub enum SweepError {
+ /// Underlying store error.
+ #[error(transparent)]
+ Store(#[from] ai_memory_store::StoreError),
+}
+
+const US_PER_DAY: f64 = 86_400_000_000.0;
+
+/// Run a sweep against the given workspace/project.
+///
+/// # Errors
+/// Propagates any store error encountered while reading candidates or
+/// writing soft-deletions.
+pub async fn run_sweep(
+ reader: &ReaderPool,
+ writer: &WriterHandle,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ params: &DecayParams,
+ dry_run: bool,
+) -> Result<SweepReport, SweepError> {
+ let candidates = reader.decay_candidates(workspace_id, project_id).await?;
+ let now_us = Timestamp::now().as_microsecond();
+
+ let mut evicted = Vec::new();
+ let mut to_evict_ids: Vec<PageId> = Vec::new();
+
+ for c in &candidates {
+ if !is_decayable(c) {
+ continue;
+ }
+ #[allow(clippy::cast_precision_loss)]
+ let age_days = (now_us - c.updated_at_us) as f64 / US_PER_DAY;
+ let days_since_access = c.last_accessed_at_us.map(|us| {
+ #[allow(clippy::cast_precision_loss)]
+ let raw = (now_us - us) as f64 / US_PER_DAY;
+ raw.max(0.0)
+ });
+ let score = retention_score(params, age_days, c.access_count, days_since_access);
+ if score < params.cold_threshold {
+ evicted.push(EvictedPage {
+ id: c.id,
+ path: c.path.as_str().to_string(),
+ retention: score,
+ age_days,
+ access_count: c.access_count,
+ });
+ to_evict_ids.push(c.id);
+ }
+ }
+
+ let mut hard_deleted = 0usize;
+ if !dry_run {
+ if !to_evict_ids.is_empty() {
+ writer.soft_delete_for_decay(to_evict_ids).await?;
+ }
+ hard_deleted = writer
+ .hard_delete_decayed(params.hard_delete_after_days)
+ .await?;
+ }
+
+ Ok(SweepReport {
+ dry_run,
+ candidates_evaluated: candidates.len(),
+ evicted,
+ hard_deleted,
+ })
+}
+
+fn is_decayable(c: &DecayCandidate) -> bool {
+ if c.tier != Tier::Episodic {
+ return false;
+ }
+ if c.pinned {
+ return false;
+ }
+ if let Ok(fm) = serde_json::from_str::<serde_json::Value>(&c.frontmatter_json)
+ && fm.get("pinned").and_then(serde_json::Value::as_bool) == Some(true)
+ {
+ return false;
+ }
+ true
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn semantic_pages_skip_decay() {
+ let c = DecayCandidate {
+ id: PageId::new(),
+ path: ai_memory_core::PagePath::new("x.md").unwrap(),
+ tier: Tier::Semantic,
+ pinned: false,
+ updated_at_us: 0,
+ access_count: 0,
+ last_accessed_at_us: None,
+ frontmatter_json: "{}".into(),
+ };
+ assert!(!is_decayable(&c));
+ }
+
+ #[test]
+ fn pinned_pages_skip_decay() {
+ let c = DecayCandidate {
+ id: PageId::new(),
+ path: ai_memory_core::PagePath::new("x.md").unwrap(),
+ tier: Tier::Episodic,
+ pinned: true,
+ updated_at_us: 0,
+ access_count: 0,
+ last_accessed_at_us: None,
+ frontmatter_json: "{}".into(),
+ };
+ assert!(!is_decayable(&c));
+ }
+
+ #[test]
+ fn frontmatter_pinned_overrides() {
+ let c = DecayCandidate {
+ id: PageId::new(),
+ path: ai_memory_core::PagePath::new("x.md").unwrap(),
+ tier: Tier::Episodic,
+ pinned: false,
+ updated_at_us: 0,
+ access_count: 0,
+ last_accessed_at_us: None,
+ frontmatter_json: r#"{"pinned": true}"#.into(),
+ };
+ assert!(!is_decayable(&c));
+ }
+
+ #[test]
+ fn fresh_episodic_page_is_decayable() {
+ let c = DecayCandidate {
+ id: PageId::new(),
+ path: ai_memory_core::PagePath::new("x.md").unwrap(),
+ tier: Tier::Episodic,
+ pinned: false,
+ updated_at_us: 0,
+ access_count: 0,
+ last_accessed_at_us: None,
+ frontmatter_json: "{}".into(),
+ };
+ assert!(is_decayable(&c));
+ }
+}
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 68309d3e..f2c91599 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -3,8 +3,8 @@
use std::str::FromStr;
use std::sync::Arc;
-use ai_memory_consolidate::Consolidator;
-use ai_memory_core::{AgentKind, NewHandoff, ProjectId, SessionId, WorkspaceId};
+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_wiki::Wiki;
@@ -35,6 +35,13 @@ pub struct AiMemoryServer {
/// Optional LLM consolidator. When `None`, `memory_consolidate`
/// returns a "not configured" error.
consolidator: Option<Arc<Consolidator>>,
+ /// Optional LLM provider for the lint contradiction pass. When
+ /// `None`, lint runs only the rule-based checks.
+ llm: Option<Arc<dyn LlmProvider>>,
+ /// Wiki handle (needed by the sweep / lint tools to read pages +
+ /// write the lint report). `None` when the server was built
+ /// without one — older `new()` callers stay safe.
+ wiki: Option<Wiki>,
// 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)]
@@ -68,6 +75,20 @@ struct StatusResponse {
counts: ai_memory_store::StatusCounts,
}
+#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]
+struct SweepArgs {
+ /// If true, preview only. Default false.
+ #[serde(default)]
+ dry_run: Option<bool>,
+}
+
+#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]
+struct LintArgs {
+ /// If true, don't write wiki/_lint/<date>.md. Default false.
+ #[serde(default)]
+ dry_run: Option<bool>,
+}
+
#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]
struct ConsolidateArgs {
/// UUID of the session to consolidate.
@@ -124,23 +145,37 @@ impl AiMemoryServer {
project_id,
default_limit: 10,
consolidator: None,
+ llm: None,
+ wiki: None,
tool_router: Self::tool_router(),
}
}
+ /// Attach the wiki handle. Without this, `memory_forget_sweep`
+ /// and `memory_lint` cannot write their report pages.
+ #[must_use]
+ pub fn with_wiki(mut self, wiki: Wiki) -> Self {
+ self.wiki = Some(wiki);
+ self
+ }
+
/// Attach an LLM-backed consolidator. Without this, the
- /// `memory_consolidate` tool errors with "not configured".
+ /// `memory_consolidate` tool errors with "not configured". Also
+ /// stores the LLM provider so `memory_lint` can run its
+ /// contradiction pass.
#[must_use]
pub fn with_consolidator(mut self, wiki: Wiki, llm: Arc<dyn LlmProvider>) -> Self {
let consolidator = Consolidator::new(
self.reader.clone(),
self.writer.clone(),
- wiki,
- llm,
+ wiki.clone(),
+ llm.clone(),
self.workspace_id,
self.project_id,
);
self.consolidator = Some(Arc::new(consolidator));
+ self.llm = Some(llm);
+ self.wiki = Some(wiki);
self
}
@@ -160,6 +195,7 @@ impl AiMemoryServer {
.search_pages(args.query, limit)
.await
.map_err(|e| McpError::internal_error(e.to_string(), None))?;
+ self.spawn_access_bump(hits.iter().map(|h| h.id).collect());
let response = QueryResponse { hits };
ok_json(&response)
}
@@ -178,10 +214,64 @@ impl AiMemoryServer {
.recent_pages(limit)
.await
.map_err(|e| McpError::internal_error(e.to_string(), None))?;
+ self.spawn_access_bump(hits.iter().map(|h| h.id).collect());
let response = QueryResponse { hits };
ok_json(&response)
}
+ /// Run the M8 forget sweep over episodic pages.
+ #[tool(description = "Run the retention sweep: walk is_latest=1 \
+ episodic pages, score them with the agentmemory-style retention \
+ formula (salience * exp(-lambda * age) + sigma * log(1 + accesses) \
+ * exp(-mu * days_since_access)), and soft-delete those below the \
+ cold threshold. Semantic / procedural / pinned pages are exempt. \
+ Pass dry_run=true to preview.")]
+ async fn memory_forget_sweep(
+ &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,
+ args.dry_run.unwrap_or(false),
+ )
+ .await
+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;
+ ok_json(&report)
+ }
+
+ /// Run the M8 lint pass: rule-based + optional LLM contradiction.
+ #[tool(description = "Audit the wiki for stale episodic pages, \
+ duplicate titles, broken cross-references, and (if an LLM \
+ provider is configured) contradictions across semantic pages. \
+ Findings land in wiki/_lint/<date>.md unless dry_run=true.")]
+ async fn memory_lint(
+ &self,
+ Parameters(args): Parameters<LintArgs>,
+ ) -> Result<CallToolResult, McpError> {
+ let Some(wiki) = self.wiki.as_ref() else {
+ return Err(McpError::internal_error(
+ "memory_lint requires the server to be built with a wiki handle",
+ None,
+ ));
+ };
+ let report = run_lint(
+ &self.reader,
+ wiki,
+ self.llm.as_ref(),
+ self.workspace_id,
+ self.project_id,
+ args.dry_run.unwrap_or(false),
+ )
+ .await
+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;
+ ok_json(&report)
+ }
+
/// LLM-driven consolidation of a session.
#[tool(description = "LLM-driven consolidation. Default mode \
(single-page) rewrites sessions/<id>.md from the observation \
@@ -305,6 +395,23 @@ impl ServerHandler for AiMemoryServer {
}
}
+impl AiMemoryServer {
+ /// Fire-and-forget access-counter bump for the M8 reinforcement
+ /// term. Failures are logged at warn but never surfaced to the
+ /// caller.
+ fn spawn_access_bump(&self, ids: Vec<PageId>) {
+ if ids.is_empty() {
+ return;
+ }
+ let writer = self.writer.clone();
+ tokio::spawn(async move {
+ if let Err(e) = writer.bump_access(ids).await {
+ tracing::warn!(error = %e, "access bump failed");
+ }
+ });
+ }
+}
+
fn ok_json<T: Serialize>(value: &T) -> Result<CallToolResult, McpError> {
let s = serde_json::to_string_pretty(value)
.map_err(|e| McpError::internal_error(e.to_string(), None))?;
diff --git a/crates/ai-memory-store/migrations/V03__decay.sql b/crates/ai-memory-store/migrations/V03__decay.sql
new file mode 100644
index 00000000..17278ef6
--- /dev/null
+++ b/crates/ai-memory-store/migrations/V03__decay.sql
@@ -0,0 +1,26 @@
+-- M8 retention / access tracking columns.
+--
+-- The forget sweep needs two signals to compute retention for a page:
+-- (a) how long since it was last touched (decay) and (b) how often it
+-- gets queried (reinforcement). We track both inline on `pages` to
+-- avoid a hot accesses table on the read path.
+--
+-- `superseded_at` distinguishes the M7 LLM-supersession path (where
+-- `supersedes` points to the previous version) from the M8 forget-sweep
+-- soft-delete path (where `supersedes IS NULL` and `superseded_at`
+-- carries the eviction time). Hard-deletion happens only after
+-- `hard_delete_after_days` days WITH zero subsequent access.
+
+ALTER TABLE pages ADD COLUMN last_accessed_at INTEGER;
+ALTER TABLE pages ADD COLUMN access_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE pages ADD COLUMN superseded_at INTEGER;
+
+-- Hot path: list decay candidates (only is_latest=true rows matter).
+CREATE INDEX idx_pages_decay
+ ON pages(workspace_id, project_id, updated_at)
+ WHERE is_latest = 1;
+
+-- Eviction candidates from prior sweeps (for hard-delete pass).
+CREATE INDEX idx_pages_evicted
+ ON pages(superseded_at)
+ WHERE is_latest = 0 AND supersedes IS NULL AND superseded_at IS NOT NULL;
diff --git a/crates/ai-memory-store/src/decay.rs b/crates/ai-memory-store/src/decay.rs
new file mode 100644
index 00000000..937056f7
--- /dev/null
+++ b/crates/ai-memory-store/src/decay.rs
@@ -0,0 +1,105 @@
+//! Retention-formula math + tunable parameters.
+//!
+//! Adapted from agentmemory's `salience · exp(−λΔt) + Σ(σ/days_since_access)`.
+//! We simplify the Σ term to `σ · log(1 + access_count) · exp(−μ · days_since_access)`
+//! so we don't have to materialise a full access-history table on the
+//! hot read path -- the `access_count` + `last_accessed_at` columns on
+//! `pages` (V03 migration) are enough.
+//!
+//! The formula is pure: pass in everything you need, get a score out.
+//! The forget-sweep job computes it from store rows; the property tests
+//! pin the math without touching the database.
+
+use serde::{Deserialize, Serialize};
+
+/// Tunable retention coefficients.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+pub struct DecayParams {
+ /// Per-day exponential decay rate applied to "age since updated_at".
+ /// `0.02` ≈ 35-day half-life.
+ pub lambda: f64,
+ /// Magnitude of the access-reinforcement boost.
+ pub sigma: f64,
+ /// Per-day exponential decay applied to "days since last access" --
+ /// so a recent hit boosts more than an old one.
+ pub mu: f64,
+ /// Default salience used when a page doesn't have an explicit one.
+ pub salience_default: f64,
+ /// Below this score, an episodic page is a soft-delete candidate.
+ pub cold_threshold: f64,
+ /// Days a soft-deleted (sweep-evicted) page must survive before
+ /// hard-delete, *with* zero subsequent access.
+ pub hard_delete_after_days: i64,
+}
+
+impl Default for DecayParams {
+ fn default() -> Self {
+ Self {
+ lambda: 0.02,
+ sigma: 0.6,
+ mu: 0.04,
+ salience_default: 1.0,
+ cold_threshold: 0.20,
+ hard_delete_after_days: 180,
+ }
+ }
+}
+
+/// Compute the retention score. Higher = "keep this page".
+///
+/// * `age_days` — days since the page's `updated_at`.
+/// * `access_count` — total number of search hits.
+/// * `days_since_access` — `Some(N)` if the page has ever been
+/// accessed; `None` if it never has.
+#[must_use]
+pub fn retention_score(
+ params: &DecayParams,
+ age_days: f64,
+ access_count: u32,
+ days_since_access: Option<f64>,
+) -> f64 {
+ let time_term = params.salience_default * (-params.lambda * age_days).exp();
+ let access_term = days_since_access.map_or(0.0, |d| {
+ params.sigma * (1.0 + f64::from(access_count)).ln() * (-params.mu * d).exp()
+ });
+ time_term + access_term
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn fresh_unused_page_starts_near_salience() {
+ let p = DecayParams::default();
+ let score = retention_score(&p, 0.0, 0, None);
+ assert!((score - p.salience_default).abs() < 1e-9);
+ }
+
+ #[test]
+ fn ancient_page_with_no_access_decays_below_threshold() {
+ let p = DecayParams::default();
+ let score = retention_score(&p, 365.0, 0, None);
+ assert!(score < p.cold_threshold, "got {score}");
+ }
+
+ #[test]
+ fn frequently_accessed_page_stays_above_threshold_even_old() {
+ let p = DecayParams::default();
+ let aged_unused = retention_score(&p, 200.0, 0, None);
+ let aged_hot = retention_score(&p, 200.0, 50, Some(2.0));
+ assert!(aged_unused < p.cold_threshold);
+ assert!(
+ aged_hot > p.cold_threshold,
+ "hot page should survive: {aged_hot} (cold {aged_unused})",
+ );
+ }
+
+ #[test]
+ fn recent_access_boosts_more_than_old_access() {
+ let p = DecayParams::default();
+ let recent = retention_score(&p, 100.0, 10, Some(2.0));
+ let stale = retention_score(&p, 100.0, 10, Some(120.0));
+ assert!(recent > stale, "recent {recent} vs stale {stale}");
+ }
+}
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index e300e39b..71c4fabe 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -12,14 +12,16 @@ use std::path::{Path, PathBuf};
use rusqlite::Connection;
+pub mod decay;
mod error;
mod migrations;
mod ops;
mod reader;
mod writer;
+pub use decay::{DecayParams, retention_score};
pub use error::{StoreError, StoreResult};
-pub use reader::{PageHit, ReaderPool, StatusCounts};
+pub use reader::{DecayCandidate, PageHit, ReaderPool, StatusCounts};
pub use writer::WriterHandle;
/// Filename used inside the data dir's `db/` subdirectory.
diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rs
index 36fbb1ee..d4c70442 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -375,6 +375,81 @@ pub fn insert_observation(
Ok(id)
}
+/// Bump `access_count` + `last_accessed_at` for the pages whose ids
+/// appear in `page_ids`. Idempotent for unknown ids (no-op).
+/// Used by the read path to feed the M8 reinforcement term.
+pub fn bump_access_for_pages(conn: &mut Connection, page_ids: &[PageId]) -> StoreResult<()> {
+ if page_ids.is_empty() {
+ return Ok(());
+ }
+ let now = Timestamp::now().as_microsecond();
+ let tx = conn.transaction()?;
+ {
+ let mut stmt = tx.prepare(
+ "UPDATE pages \
+ SET access_count = access_count + 1, last_accessed_at = ?1 \
+ WHERE id = ?2 AND is_latest = 1",
+ )?;
+ for id in page_ids {
+ stmt.execute(params![now, id.as_bytes()])?;
+ }
+ }
+ tx.commit()?;
+ Ok(())
+}
+
+/// Mark a set of `is_latest=1` pages as soft-deleted by the forget
+/// sweep. Distinguished from M7 supersession by `supersedes IS NULL`.
+pub fn soft_delete_for_decay(conn: &mut Connection, page_ids: &[PageId]) -> StoreResult<usize> {
+ if page_ids.is_empty() {
+ return Ok(0);
+ }
+ let now = Timestamp::now().as_microsecond();
+ let mut affected = 0usize;
+ let tx = conn.transaction()?;
+ {
+ let mut stmt = tx.prepare(
+ "UPDATE pages \
+ SET is_latest = 0, superseded_at = ?1 \
+ WHERE id = ?2 AND is_latest = 1",
+ )?;
+ for id in page_ids {
+ affected += stmt.execute(params![now, id.as_bytes()])?;
+ }
+ }
+ audit(
+ &tx,
+ "soft_delete_for_decay",
+ None,
+ None,
+ None,
+ Timestamp::now().as_microsecond(),
+ )?;
+ tx.commit()?;
+ Ok(affected)
+}
+
+/// Hard-delete rows that were soft-deleted by an earlier sweep at
+/// least `hard_delete_after_days` ago AND received zero subsequent
+/// accesses. Safe: M7 supersedes-chain pages have a non-null
+/// `supersedes` so they never match.
+pub fn hard_delete_decayed_pages(
+ conn: &mut Connection,
+ hard_delete_after_days: i64,
+) -> StoreResult<usize> {
+ let cutoff = Timestamp::now().as_microsecond() - hard_delete_after_days * 86_400_000_000;
+ let n = conn.execute(
+ "DELETE FROM pages \
+ WHERE is_latest = 0 \
+ AND supersedes IS NULL \
+ AND superseded_at IS NOT NULL \
+ AND superseded_at < ?1 \
+ AND access_count = 0",
+ params![cutoff],
+ )?;
+ Ok(n)
+}
+
/// Insert a new handoff in state=open.
pub fn insert_handoff(conn: &mut Connection, h: &NewHandoff) -> StoreResult<HandoffId> {
let id = HandoffId::new();
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 0b170e63..fe313a9d 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -16,6 +16,9 @@ use ai_memory_core::{
use parking_lot::Mutex;
use rusqlite::{Connection, OpenFlags, OptionalExtension, params};
use serde::Serialize;
+// `ai_memory_core::Tier` is referenced via fully-qualified path inside the
+// DecayCandidate struct definition above to avoid a top-level import
+// for a single use-site.
use crate::error::{StoreError, StoreResult};
@@ -211,6 +214,41 @@ impl ReaderPool {
.await
}
+ /// Return decay-evaluation candidates for the M8 forget sweep.
+ ///
+ /// Walks `pages` rows with `is_latest = 1` and returns the columns
+ /// the forget sweep needs to compute the retention formula. The
+ /// sweep itself filters by tier (only `episodic`) + pinned flag,
+ /// so this method does not pre-filter -- it just hands the data
+ /// over.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn decay_candidates(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ ) -> StoreResult<Vec<DecayCandidate>> {
+ self.with_conn(move |conn| {
+ let mut stmt = conn.prepare(
+ "SELECT id, path, tier, pinned, updated_at, access_count, last_accessed_at, \
+ frontmatter_json \
+ FROM pages \
+ WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1",
+ )?;
+ let rows = stmt.query_map(
+ params![workspace_id.as_bytes(), project_id.as_bytes()],
+ row_to_decay_candidate,
+ )?;
+ let mut out = Vec::new();
+ for r in rows {
+ out.push(r??);
+ }
+ Ok(out)
+ })
+ .await
+ }
+
/// Return the latest open handoff for the project, optionally
/// filtered to a specific `cwd`.
///
@@ -371,6 +409,76 @@ fn materialise_observation(
})
}
+/// One row's worth of input for the M8 retention formula.
+#[derive(Debug, Clone, Serialize)]
+pub struct DecayCandidate {
+ /// Stable identifier.
+ pub id: PageId,
+ /// Relative wiki path.
+ pub path: PagePath,
+ /// Tier (the sweep only considers `episodic`).
+ pub tier: ai_memory_core::Tier,
+ /// Pinned flag — true means "never decay".
+ pub pinned: bool,
+ /// `updated_at` in microseconds since epoch.
+ pub updated_at_us: i64,
+ /// Total query/access hits.
+ pub access_count: u32,
+ /// `last_accessed_at` in microseconds since epoch, or `None` if never accessed.
+ pub last_accessed_at_us: Option<i64>,
+ /// Frontmatter JSON; the sweep peeks at it for an explicit
+ /// `pinned: true` (which overrides the schema flag).
+ pub frontmatter_json: String,
+}
+
+fn row_to_decay_candidate(
+ row: &rusqlite::Row<'_>,
+) -> rusqlite::Result<StoreResult<DecayCandidate>> {
+ let id_bytes: Vec<u8> = row.get(0)?;
+ let path: String = row.get(1)?;
+ let tier_str: String = row.get(2)?;
+ let pinned: i64 = row.get(3)?;
+ let updated_at_us: i64 = row.get(4)?;
+ let access_count: i64 = row.get(5)?;
+ let last_accessed_at_us: Option<i64> = row.get(6)?;
+ let frontmatter_json: String = row.get(7)?;
+ Ok(materialise_decay_candidate(
+ id_bytes,
+ path,
+ tier_str,
+ pinned,
+ updated_at_us,
+ access_count,
+ last_accessed_at_us,
+ frontmatter_json,
+ ))
+}
+
+#[allow(clippy::too_many_arguments)]
+fn materialise_decay_candidate(
+ id_bytes: Vec<u8>,
+ path: String,
+ tier_str: String,
+ pinned: i64,
+ updated_at_us: i64,
+ access_count: i64,
+ last_accessed_at_us: Option<i64>,
+ frontmatter_json: String,
+) -> StoreResult<DecayCandidate> {
+ Ok(DecayCandidate {
+ id: PageId::from_slice(&id_bytes)?,
+ path: PagePath::new(path)?,
+ tier: tier_str
+ .parse::<ai_memory_core::Tier>()
+ .map_err(StoreError::from)?,
+ pinned: pinned != 0,
+ updated_at_us,
+ access_count: u32::try_from(access_count.max(0)).unwrap_or(u32::MAX),
+ last_accessed_at_us,
+ frontmatter_json,
+ })
+}
+
fn row_to_handoff(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<Handoff>> {
let id_bytes: Vec<u8> = row.get(0)?;
let ws_bytes: Vec<u8> = row.get(1)?;
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index 7f642e7e..8cae91e5 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -63,6 +63,18 @@ pub(crate) enum WriteCmd {
accepting_session: Option<SessionId>,
reply: oneshot::Sender<StoreResult<()>>,
},
+ BumpAccess {
+ page_ids: Vec<PageId>,
+ reply: oneshot::Sender<StoreResult<()>>,
+ },
+ SoftDeleteForDecay {
+ page_ids: Vec<PageId>,
+ reply: oneshot::Sender<StoreResult<usize>>,
+ },
+ HardDeleteDecayed {
+ hard_delete_after_days: i64,
+ reply: oneshot::Sender<StoreResult<usize>>,
+ },
Shutdown,
}
@@ -208,6 +220,49 @@ impl WriterHandle {
rx.await.map_err(|_| StoreError::WriterClosed)?
}
+ /// Bump access counters for a set of pages (M8 reinforcement term).
+ ///
+ /// # Errors
+ /// Returns [`StoreError::WriterClosed`] or propagates SQL errors.
+ pub async fn bump_access(&self, page_ids: Vec<PageId>) -> StoreResult<()> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::BumpAccess {
+ page_ids,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
+ /// Soft-delete pages identified by the M8 forget sweep.
+ ///
+ /// # Errors
+ /// Returns [`StoreError::WriterClosed`] or propagates SQL errors.
+ pub async fn soft_delete_for_decay(&self, page_ids: Vec<PageId>) -> StoreResult<usize> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::SoftDeleteForDecay {
+ page_ids,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
+ /// Hard-delete pages soft-deleted by the sweep more than
+ /// `hard_delete_after_days` ago.
+ ///
+ /// # Errors
+ /// Returns [`StoreError::WriterClosed`] or propagates SQL errors.
+ pub async fn hard_delete_decayed(&self, hard_delete_after_days: i64) -> StoreResult<usize> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::HardDeleteDecayed {
+ hard_delete_after_days,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
/// Upsert a batch of pages atomically (one SQL transaction).
///
/// # Errors
@@ -314,6 +369,21 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
);
let _ = reply.send(result);
}
+ WriteCmd::BumpAccess { page_ids, reply } => {
+ let result = ops::bump_access_for_pages(&mut conn, &page_ids);
+ let _ = reply.send(result);
+ }
+ WriteCmd::SoftDeleteForDecay { page_ids, reply } => {
+ let result = ops::soft_delete_for_decay(&mut conn, &page_ids);
+ let _ = reply.send(result);
+ }
+ WriteCmd::HardDeleteDecayed {
+ hard_delete_after_days,
+ reply,
+ } => {
+ let result = ops::hard_delete_decayed_pages(&mut conn, hard_delete_after_days);
+ let _ = reply.send(result);
+ }
}
}
tracing::debug!("writer thread exiting cleanly");