Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(mcp): reinforce retention on read_page, related-walk, and explore (C1)
AkitaOnRails5bac224a5849
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5a6c1e84..0bfec8ac 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- Access reinforcement on the remaining read paths (design-memory-aging.md+ bucket C1): `memory_read_page` (a direct by-path/by-query read), its+ `include_related` link-graph walk (the walked neighbours, not just the seed),+ and `memory_explore` (the pages it surfaces — rules, slots, recent, pinned,+ settled) now bump `access_count` + `last_accessed_at` exactly as+ `memory_query` and `memory_recent` already do. A page a human opens directly,+ or one the graph surfaces, is *used* and now resists decay like a search hit.+ Reuses the sanctioned reinforcement path: fire-and-forget on the single-writer+ actor, throttled to ≤1 per (page, operator) per minute, and FTS-exempt. It is+ strictly additive — reinforcement only raises retention scores, never blocks,+ never touches the response payloads, and adds no new MCP tool (still 23)+ (#NNN).- Reasoning tier on the LLM synthesis paths: an opt-in `reasoning` argument on`memory_query` (its `answer` path) and `memory_explore` (borrowed fromHoncho's reasoning-effort ladder; targets the 2.4 line). The knob is a schemadiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 17ad2a2d..1e2157ce 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -3702,7 +3702,27 @@ impl AiMemoryServer {value};- match wiki.read_page(ws, proj, &page_path) {+ // Access reinforcement (C1): a page opened directly by path/query, and+ // any page the graph surfaces via the related walk, is *used* and should+ // resist decay exactly as a `memory_query`/`memory_recent` hit does.+ // Resolve the seed id and the walked ids up front; the fire-and-forget,+ // per-(page,operator)-throttled, FTS-exempt `spawn_access_bump` is fired+ // only on the success paths below, so an error read reinforces nothing.+ let bump_actor = Self::bump_actor_from_parts(&parts);+ let mut bump_ids: Vec<PageId> = Vec::new();+ if let Some(seed_id) = self+ .reader+ .latest_page_id_by_ids(ws, proj, page_path.to_string())+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?+ {+ bump_ids.push(seed_id);+ }+ if let Some(nodes) = &related {+ bump_ids.extend(nodes.iter().map(|n| n.id));+ }++ let result = match wiki.read_page(ws, proj, &page_path) {Ok(md) => {// Derive the title so an empty/absent frontmatter `title`// falls back to the body's H1 (then the path stem), instead@@ -3766,7 +3786,11 @@ impl AiMemoryServer {}}Err(disk_err) => Err(McpError::internal_error(disk_err.to_string(), None)),+ };+ if result.is_ok() {+ self.spawn_access_bump(bump_ids, bump_actor.as_ref());}+ result}/// Read one session's raw lifecycle observations, in scope, paged and@@ -4727,6 +4751,31 @@ impl AiMemoryServer {.await.map_err(|e| McpError::internal_error(e.to_string(), None))?;+ // Access reinforcement (C1): `memory_explore` surfaces a bounded set of+ // pages (rules, slots, recent, pinned, settled) — those pages are used+ // and should resist decay like a `memory_query`/`memory_recent` hit.+ // The snapshot carries paths, not ids; resolve them in one batched read+ // (no per-page N+1, invariant #2), then fire the sanctioned throttled,+ // FTS-exempt, fire-and-forget bump. Same set whether or not an LLM digest+ // runs — the pages were read either way.+ let surfaced_paths: Vec<String> = snapshot+ .rules+ .iter()+ .chain(snapshot.slots.iter())+ .chain(snapshot.recent_pages.iter())+ .chain(snapshot.pinned.iter())+ .map(|p| p.path.clone())+ .chain(snapshot.settled.iter().map(|p| p.path.clone()))+ .collect();+ if !surfaced_paths.is_empty() {+ let ids = self+ .reader+ .latest_page_ids_by_paths(ws, proj, surfaced_paths)+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;+ self.spawn_access_bump(ids, Self::bump_actor_from_parts(&parts).as_ref());+ }+let Some(llm) = &self.consolidator else {// No LLM configured — return the structured snapshot.// Caller can render prose itself if it wants.diff --git a/crates/ai-memory-mcp/tests/suite/access_reinforcement.rs b/crates/ai-memory-mcp/tests/suite/access_reinforcement.rsnew file mode 100644index 00000000..1f0546e5--- /dev/null+++ b/crates/ai-memory-mcp/tests/suite/access_reinforcement.rs@@ -0,0 +1,291 @@+//! Access reinforcement on the read paths that previously reinforced nothing+//! (design-memory-aging.md, bucket C1). A page a client opens by+//! `memory_read_page`, a page the link graph surfaces through the+//! `include_related` walk, and the pages `memory_explore` surfaces should each+//! bump `access_count` + `last_accessed_at` exactly as a `memory_query` /+//! `memory_recent` hit already does — the M8 reinforcement term that feeds the+//! decay formula's `access_term`.+//!+//! The bump reuses the sanctioned `spawn_access_bump` path: fire-and-forget on+//! the single-writer actor, throttled to ≤1 per (page, operator) per+//! `ACCESS_BUMP_COOLDOWN`, FTS-exempt. It is strictly additive — the response+//! payloads must stay byte-identical.++use ai_memory_core::WorkspaceId;+use ai_memory_mcp::AiMemoryServer;+use ai_memory_store::Store;+use ai_memory_wiki::Wiki;+use axum::Router;+use axum::body::Body;+use axum::http::Request;+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;+use rmcp::transport::streamable_http_server::{StreamableHttpServerConfig, StreamableHttpService};+use serde_json::{Value, json};+use std::time::Duration;+use tempfile::TempDir;+use tower::ServiceExt;++const WS: &str = "default";+const PROJ: &str = "scratch";++struct Harness {+ router: Router,+ store: Store,+ ws: WorkspaceId,+ proj: ai_memory_core::ProjectId,+ _tmp: TempDir,+}++fn mount(server: AiMemoryServer) -> Router {+ let service = StreamableHttpService::new(+ move || Ok(server.clone()),+ LocalSessionManager::default().into(),+ StreamableHttpServerConfig::default()+ .with_stateful_mode(false)+ .with_json_response(true),+ );+ Router::new().nest_service("/mcp", service)+}++async fn harness() -> Harness {+ let tmp = TempDir::new().expect("tempdir");+ let store = Store::open(tmp.path()).expect("store");+ let ws = store.writer.get_or_create_workspace(WS).await.expect("ws");+ let proj = store+ .writer+ .get_or_create_project(ws, PROJ, None)+ .await+ .expect("proj");+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).expect("wiki");+ let server =+ AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj).with_wiki(wiki);++ Harness {+ router: mount(server),+ store,+ ws,+ proj,+ _tmp: tmp,+ }+}++async fn call(router: &Router, name: &str, arguments: Value) -> Value {+ let body = json!({+ "jsonrpc": "2.0",+ "id": 1,+ "method": "tools/call",+ "params": { "name": name, "arguments": arguments },+ });+ let req = Request::builder()+ .method("POST")+ .uri("/mcp")+ .header("host", "localhost")+ .header("content-type", "application/json")+ .header("accept", "application/json, text/event-stream")+ .body(Body::from(body.to_string()))+ .expect("mcp req");+ let resp = router.clone().oneshot(req).await.expect("oneshot");+ let bytes = axum::body::to_bytes(resp.into_body(), 4_000_000)+ .await+ .expect("body");+ let text = String::from_utf8(bytes.to_vec()).expect("utf8");+ let v: Value = serde_json::from_str(&text).unwrap_or_else(|e| panic!("non-JSON: {text}: {e}"));+ if let Some(err) = v.get("error") {+ panic!("JSON-RPC error: {err}\nfull: {text}");+ }+ let joined = v+ .pointer("/result/content")+ .and_then(|c| c.as_array())+ .unwrap_or_else(|| panic!("missing result.content: {text}"))+ .iter()+ .filter_map(|i| i.get("text").and_then(|t| t.as_str()))+ .collect::<Vec<_>>()+ .join("\n");+ serde_json::from_str(&joined).unwrap_or_else(|e| panic!("tool text not JSON: {joined}: {e}"))+}++async fn write_page(router: &Router, path: &str, body: &str) {+ let resp = call(+ router,+ "memory_write_page",+ json!({ "workspace": WS, "project": PROJ, "path": path, "body": body }),+ )+ .await;+ assert!(resp.get("page_id").is_some(), "page not written: {resp}");+}++/// Read the current `access_count` for one page via the same read path the+/// forget sweep uses, so the assertion sees the committed single-writer state.+async fn access_count(h: &Harness, path: &str) -> u32 {+ let cands = h+ .store+ .reader+ .decay_candidates(h.ws, h.proj)+ .await+ .expect("decay_candidates");+ cands+ .into_iter()+ .find(|c| c.path.as_str() == path)+ .unwrap_or_else(|| panic!("page {path} not among decay candidates"))+ .access_count+}++/// Poll until `access_count` for `path` reaches `want`, or give up. The bump is+/// spawned fire-and-forget onto the writer actor, so a read is not synchronous —+/// mirror how the writer lands asynchronously by polling the committed value.+async fn wait_for_access(h: &Harness, path: &str, want: u32) -> u32 {+ for _ in 0..200 {+ let got = access_count(h, path).await;+ if got >= want {+ return got;+ }+ tokio::time::sleep(Duration::from_millis(10)).await;+ }+ access_count(h, path).await+}++/// A direct by-path `memory_read_page` reinforces the page it returns.+#[tokio::test]+async fn read_page_bumps_access_count() {+ let h = harness().await;+ write_page(&h.router, "notes/a.md", "# A\n\nbody").await;+ assert_eq!(+ access_count(&h, "notes/a.md").await,+ 0,+ "seeded page starts at 0"+ );++ let resp = call(+ &h.router,+ "memory_read_page",+ json!({ "workspace": WS, "project": PROJ, "path": "notes/a.md" }),+ )+ .await;+ assert_eq!(+ resp.get("path").and_then(|p| p.as_str()),+ Some("notes/a.md")+ );++ let got = wait_for_access(&h, "notes/a.md", 1).await;+ assert_eq!(got, 1, "a by-path read must reinforce the page it returns");+}++/// The `include_related` walk reinforces the seed AND the walked neighbours —+/// a graph-surfaced page was used and should resist decay too.+#[tokio::test]+async fn read_page_include_related_bumps_related() {+ let h = harness().await;+ write_page(&h.router, "notes/b.md", "# B\n\nleaf").await;+ write_page(&h.router, "notes/a.md", "# A\n\nsee [[notes/b.md]]").await;++ let resp = call(+ &h.router,+ "memory_read_page",+ json!({+ "workspace": WS, "project": PROJ, "path": "notes/a.md",+ "include_related": true,+ }),+ )+ .await;+ let related = resp+ .get("related")+ .and_then(|r| r.as_array())+ .expect("related array present");+ assert!(+ related+ .iter()+ .any(|n| n.get("path").and_then(|p| p.as_str()) == Some("notes/b.md")),+ "walk should reach notes/b.md: {resp}"+ );++ assert_eq!(+ wait_for_access(&h, "notes/a.md", 1).await,+ 1,+ "seed reinforced"+ );+ assert_eq!(+ wait_for_access(&h, "notes/b.md", 1).await,+ 1,+ "the walked neighbour must be reinforced, not just the seed"+ );+}++/// `memory_explore` surfaces pages (via the briefing snapshot); those pages are+/// reinforced. With no LLM configured the tool returns the structured briefing,+/// which is enough to exercise the reinforcement.+#[tokio::test]+async fn explore_bumps_surfaced_pages() {+ let h = harness().await;+ write_page(&h.router, "notes/topic.md", "# Topic\n\nrecent work").await;+ assert_eq!(access_count(&h, "notes/topic.md").await, 0);++ let resp = call(+ &h.router,+ "memory_explore",+ json!({ "workspace": WS, "project": PROJ }),+ )+ .await;+ // No LLM in tests → structured briefing is returned unchanged.+ assert!(+ resp.get("briefing").is_some(),+ "explore returns briefing: {resp}"+ );++ let got = wait_for_access(&h, "notes/topic.md", 1).await;+ assert_eq!(got, 1, "explore must reinforce the pages it surfaced");+}++/// Two reads inside the cooldown window bump only once — the per-(page,operator)+/// throttle inside `spawn_access_bump` bounds read-amplification.+#[tokio::test]+async fn read_page_throttle_no_double_bump() {+ let h = harness().await;+ write_page(&h.router, "notes/a.md", "# A\n\nbody").await;++ call(+ &h.router,+ "memory_read_page",+ json!({ "workspace": WS, "project": PROJ, "path": "notes/a.md" }),+ )+ .await;+ assert_eq!(wait_for_access(&h, "notes/a.md", 1).await, 1);++ // A second read within the 60s cooldown must not bump again.+ call(+ &h.router,+ "memory_read_page",+ json!({ "workspace": WS, "project": PROJ, "path": "notes/a.md" }),+ )+ .await;+ // Give any (erroneously) spawned second bump time to land, then assert it+ // did not.+ tokio::time::sleep(Duration::from_millis(80)).await;+ assert_eq!(+ access_count(&h, "notes/a.md").await,+ 1,+ "the cooldown must suppress a double bump within the window"+ );+}++/// The bump is additive: a plain read's response payload is exactly the four+/// documented fields, unchanged by reinforcement.+#[tokio::test]+async fn read_page_response_payload_unchanged() {+ let h = harness().await;+ write_page(&h.router, "notes/a.md", "# A\n\nbody text").await;++ let resp = call(+ &h.router,+ "memory_read_page",+ json!({ "workspace": WS, "project": PROJ, "path": "notes/a.md" }),+ )+ .await;+ let obj = resp.as_object().expect("object response");+ let mut keys: Vec<&str> = obj.keys().map(String::as_str).collect();+ keys.sort_unstable();+ assert_eq!(+ keys,+ vec!["body", "frontmatter", "path", "title"],+ "reinforcement must not add fields to the read_page payload: {resp}"+ );+}diff --git a/crates/ai-memory-mcp/tests/suite/mod.rs b/crates/ai-memory-mcp/tests/suite/mod.rsindex 4bcff315..1ef69bf8 100644--- a/crates/ai-memory-mcp/tests/suite/mod.rs+++ b/crates/ai-memory-mcp/tests/suite/mod.rs@@ -4,6 +4,7 @@mod common;+mod access_reinforcement;mod admin_audit_log;mod admin_backup;mod admin_bootstrap;diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 8ffbcf52..0d223001 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -1522,6 +1522,13 @@ pub const RELATED_WALK_MAX_NODES: usize = 50;/// first reached it.#[derive(Debug, Clone, Serialize)]pub struct RelatedNode {+ /// Stable id of the related page's latest version. Carried for access+ /// reinforcement (C1): `memory_read_page`'s related walk bumps the walked+ /// pages, not just the seed. `#[serde(skip)]` keeps the wire payload+ /// byte-identical to a plain `page_links` entry — the id is an internal+ /// handle, never part of the tool response.+ #[serde(skip)]+ pub id: PageId,/// Identity of the related page (path/title/kind/workspace/project),/// flattened so a node serializes exactly like a `page_links` entry with/// two extra fields.@@ -6811,6 +6818,7 @@ impl ReaderPool {continue;}results.push(RelatedNode {+ id: PageId::from_slice(&id)?,page,depth: hop,direction,@@ -7408,6 +7416,56 @@ impl ReaderPool {.await}+ /// Resolve the latest-version page ids for a batch of paths within one+ /// scope, in a single query. Missing/duplicate paths are simply absent from+ /// the result. Used by `memory_explore` for access reinforcement (C1): it+ /// surfaces a bounded set of pages by path (rules, slots, recent, pinned,+ /// settled) and bumps them all through one round-trip rather than a per-page+ /// N+1 (invariant #2).+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn latest_page_ids_by_paths(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ paths: Vec<String>,+ ) -> StoreResult<Vec<PageId>> {+ if paths.is_empty() {+ return Ok(Vec::new());+ }+ self.with_conn(move |conn| {+ // De-duplicate placeholders and bind (ws, proj) + each distinct path.+ let mut distinct: Vec<String> = paths;+ distinct.sort();+ distinct.dedup();+ let placeholders = std::iter::repeat_n("?", distinct.len())+ .collect::<Vec<_>>()+ .join(", ");+ let sql = format!(+ "SELECT id FROM pages \+ WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 \+ AND path IN ({placeholders})"+ );+ let mut stmt = conn.prepare(&sql)?;+ let ws_bytes = workspace_id.as_bytes();+ let proj_bytes = project_id.as_bytes();+ let mut binds: Vec<&dyn rusqlite::ToSql> = Vec::with_capacity(distinct.len() + 2);+ binds.push(ws_bytes as &dyn rusqlite::ToSql);+ binds.push(proj_bytes as &dyn rusqlite::ToSql);+ for p in &distinct {+ binds.push(p as &dyn rusqlite::ToSql);+ }+ let rows = stmt.query_map(binds.as_slice(), |row| row.get::<_, Vec<u8>>(0))?;+ let mut ids = Vec::new();+ for r in rows {+ ids.push(PageId::from_slice(&r?)?);+ }+ Ok(ids)+ })+ .await+ }+/// Return whether the latest version of one fully scoped page is expired./// Returns `None` when the path has no latest indexed row.///diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 81414be0..238a504b 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -137,7 +137,12 @@ from hook paths.`[decay] breadth_weight` can reward pages reinforced by several distinctoperators. That bump is throttled to at most once per page per minute, so aburst of overlapping searches does not flood the writer actor with- redundant reinforcement writes.+ redundant reinforcement writes. The same reinforcement fires from every+ read path that surfaces a page, not just search: `memory_read_page` (and its+ `include_related` walk, which reinforces the walked neighbours too) and+ `memory_explore` (the pages it surfaces) bump the same counters through the+ same throttled, FTS-exempt path, so a page a human opens directly or the+ graph surfaces resists decay like a query hit (design-memory-aging.md C1).7. The forget sweep runs on demand and on the server's `[maintenance]`schedule: pages past their frontmatter `expires_at:` TTL arehard-deleted through the wiki layer (file + rows, pin or not);