Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
perf(mcp): throttle M8 access-counter bumps to once per page per minute
Samir Hanna Verza46b42e6fbf38
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3183aca0..f5c5dbb2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,6 +15,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0client of the running server; the command now requires a reachableserver and no longer works against an offline data directory.+### Changed+- The M8 access-counter reinforcement is now throttled: a page's+ `access_count` / `last_accessed_at` is bumped at most once per minute+ instead of on every search that returns it. `memory_query` previously+ spawned a writer command per hit on each of its three search paths, so+ repeated or overlapping queries flooded the single writer actor with+ redundant reinforcement writes. A page's first sighting still bumps+ immediately, and a continuously-hot page keeps earning one bump per+ window, so recency ordering is unaffected; only the magnitude of+ `access_count` grows more slowly under bursty search. The cooldown map+ self-prunes, staying bounded by the pages searched within the window.+## [1.18.0] - 2026-07-23### Addeddiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex ab30474c..e434bf0b 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -2,7 +2,8 @@use std::collections::HashMap;use std::str::FromStr;-use std::sync::Arc;+use std::sync::{Arc, Mutex};+use std::time::{Duration, Instant};use ai_memory_consolidate::{AutoImproveReviewConfig, Consolidator, projection::cap_text_with_marker,@@ -345,6 +346,14 @@ pub struct AiMemoryServer {/// keeps manual runs at least as strict as the operator's configured/// Phase 1/2 budgets instead of falling back to compiled defaults.auto_improve_review_config: AutoImproveReviewConfig,+ /// Cooldown clock for the M8 access-bump reinforcement: the last+ /// instant each page's access counter was bumped. A page returned by+ /// many searches in quick succession is bumped at most once per+ /// [`ACCESS_BUMP_COOLDOWN`] instead of on every search, which keeps+ /// repeated or overlapping queries from flooding the single writer+ /// actor with redundant reinforcement writes. Shared across `Clone`s+ /// so every request handler consults the same clock.+ access_bump_seen: Arc<Mutex<HashMap<PageId, Instant>>>,// 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)]@@ -794,6 +803,7 @@ impl AiMemoryServer {sanitizer: ai_memory_core::Sanitizer::builtin(),auto_improve_require_approval: false,auto_improve_review_config: default_auto_improve_review_config(),+ access_bump_seen: Arc::new(Mutex::new(HashMap::new())),tool_router: Self::tool_router(),}}@@ -2567,17 +2577,64 @@ fn moonshot_safe_tool_list(tools: Vec<Tool>) -> Vec<Tool> {.collect()}+/// A page's access counter is bumped at most once per this window. Repeated+/// or overlapping searches routinely return the same hot pages; without a+/// cooldown every search spawned a writer command per page, so a burst of+/// queries flooded the single writer actor with redundant M8 reinforcement+/// writes. One bump per minute is ample resolution for a signal that feeds+/// day/week-scale retention scoring.+const ACCESS_BUMP_COOLDOWN: Duration = Duration::from_secs(60);++/// Pick the page ids due for an access bump, updating the cooldown clock in+/// place: a page is due when it has not been bumped within `cooldown`.+/// Entries that have aged past `cooldown` are pruned in the same pass, so the+/// map stays bounded by the recent working set rather than growing with every+/// distinct page ever searched. Kept pure and synchronous so the throttle+/// policy is unit-testable without a store or async runtime.+fn select_bumpable(+ seen: &mut HashMap<PageId, Instant>,+ ids: Vec<PageId>,+ now: Instant,+ cooldown: Duration,+) -> Vec<PageId> {+ use std::collections::hash_map::Entry;++ seen.retain(|_, last| now.duration_since(*last) < cooldown);+ let mut fresh = Vec::new();+ for id in ids {+ // After the prune, an occupied slot means "still within cooldown" —+ // skip it, and do not refresh its timestamp: refreshing would starve+ // a continuously-hot page of its once-per-window bump entirely.+ if let Entry::Vacant(slot) = seen.entry(id) {+ slot.insert(now);+ fresh.push(id);+ }+ }+ fresh+}+impl AiMemoryServer {- /// Fire-and-forget access-counter bump for the M8 reinforcement- /// term. Failures are logged at warn but never surfaced to the- /// caller.+ /// Fire-and-forget access-counter bump for the M8 reinforcement term,+ /// throttled to at most one bump per page per [`ACCESS_BUMP_COOLDOWN`]+ /// (see [`select_bumpable`]). 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 fresh = {+ let mut seen = self+ .access_bump_seen+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner());+ select_bumpable(&mut seen, ids, Instant::now(), ACCESS_BUMP_COOLDOWN)+ };+ if fresh.is_empty() {+ return;+ }let writer = self.writer.clone();tokio::spawn(async move {- if let Err(e) = writer.bump_access(ids).await {+ if let Err(e) = writer.bump_access(fresh).await {tracing::warn!(error = %e, "access bump failed");}});@@ -6658,4 +6715,40 @@ mod tests {);}}++ #[test]+ fn access_bump_throttle_dedups_within_cooldown_and_reallows_after() {+ let cooldown = Duration::from_secs(60);+ let t0 = Instant::now();+ let a = PageId::new();+ let b = PageId::new();+ let c = PageId::new();+ let mut seen = HashMap::new();++ // First sighting of both pages → both due, in input order.+ assert_eq!(+ select_bumpable(&mut seen, vec![a, b], t0, cooldown),+ vec![a, b]+ );++ // The same hot pages 30s later (inside the window) → nothing due, so+ // the writer actor is spared the redundant reinforcement writes.+ let t30 = t0 + Duration::from_secs(30);+ assert!(select_bumpable(&mut seen, vec![a, b], t30, cooldown).is_empty());++ // A fresh page mixed in with the cooling ones → only the fresh one.+ assert_eq!(+ select_bumpable(&mut seen, vec![a, b, c], t30, cooldown),+ vec![c]+ );++ // Past the window, `a` is due again.+ let t90 = t0 + Duration::from_secs(90);+ assert_eq!(select_bumpable(&mut seen, vec![a], t90, cooldown), vec![a]);++ // Aged-out entries are pruned, so the map never grows without bound.+ let t_far = t0 + Duration::from_secs(1_000);+ assert!(select_bumpable(&mut seen, Vec::new(), t_far, cooldown).is_empty());+ assert!(seen.is_empty(), "aged-out entries must be pruned");+ }}diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 82d36fb5..7f184e2d 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -99,7 +99,9 @@ from hook paths.explicit project, or explicit `scopes` mode, bounded raw observationFTS returns fallback `raw_hits`; `global=true` searches compiled wikipages across projects only. Page hits bump `access_count` +- `last_accessed_at` - the M8 reinforcement term.+ `last_accessed_at` - the M8 reinforcement term. That bump is throttled+ to at most once per page per minute, so a burst of overlapping searches+ does not flood the writer actor with redundant reinforcement writes.7. The forget sweep runs on demand and on the server's `[maintenance]`schedule: pages with `retention < cold_threshold` are soft-deleted;soft-deletions older than `hard_delete_after_days` with no subsequent