Skip to content

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.md
index 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 from
Honcho's reasoning-effort ladder; targets the 2.4 line). The knob is a schema
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.md
index 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 distinct
operators. 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.
+ 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 are
hard-deleted through the wiki layer (file + rows, pin or not);