Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs+tests: post-merge follow-up for memory_read_page
AkitaOnRails3e4b5192ebf0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3c0aa69d..b12dcb9c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- **`memory_read_page` MCP tool** (`read-only`) for fetching the FULL body of a+ wiki page — pass `path` for a direct lookup or `query` to fetch the top FTS5+ hit's full body. Complements `memory_query`'s 24-word snippets when an agent+ needs to read an entire decision page end-to-end. Also exposed as+ `GET /admin/read-page?workspace=…&project=…&path=…` (admin HTTP) and the new+ `ai-memory read-page` CLI subcommand (thin HTTP client). All three surfaces+ scope to the current project by default and route user-supplied paths through+ `PagePath::new`, so traversal attempts (`../etc/passwd`) are rejected with+ 400. ARCHITECTURE.md's MCP-tool table grows from 12 to 13 rows ([#49]).- `_slots/*.md` pages can now declare `slot_kind: state` or`slot_kind: invariant` frontmatter. `state` remains the default for existingslots; `invariant` marks high-resistance project context or preferences thatdiff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex d3f37e71..02db1737 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -1673,4 +1673,130 @@ mod tests {assert_eq!(json["providers"]["llm"]["status"], "disabled");assert_eq!(json["providers"]["embedding"]["status"], "disabled");}++ fn read_page_test_router() -> (TempDir, Router) {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ let router = admin_router(AdminState {+ writer: store.writer.clone(),+ reader: store.reader.clone(),+ wiki,+ llm: None,+ embedder: None,+ provider_health: ProviderHealth::default(),+ decay_params: DecayParams::default(),+ data_dir: tmp.path().to_path_buf(),+ db_path: store.db_path().to_path_buf(),+ bind: "127.0.0.1:49374".to_string(),+ bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),+ });+ (tmp, router)+ }++ async fn post_write_page(router: &Router, ws: &str, project: &str, path: &str, body: &str) {+ let req_body = serde_json::json!({+ "workspace": ws,+ "project": project,+ "path": path,+ "body": body,+ "title": "Read-back fixture",+ });+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/write-page")+ .header("content-type", "application/json")+ .body(Body::from(serde_json::to_vec(&req_body).unwrap()))+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK, "write-page setup failed");+ }++ #[tokio::test]+ async fn read_page_path_mode_returns_full_body() {+ let (_tmp, router) = read_page_test_router();+ post_write_page(&router, "default", "audit", "notes/foo.md", "hello body").await;++ let resp = router+ .oneshot(+ Request::builder()+ .uri("/admin/read-page?workspace=default&project=audit&path=notes/foo.md")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();++ assert_eq!(resp.status(), StatusCode::OK);+ let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();+ let json: serde_json::Value = serde_json::from_slice(&body).unwrap();+ assert_eq!(json["path"], "notes/foo.md");+ assert_eq!(json["title"], "Read-back fixture");+ assert!(+ json["body"]+ .as_str()+ .unwrap_or_default()+ .contains("hello body"),+ "body must round-trip; got {:?}",+ json["body"]+ );+ assert_eq!(json["workspace"], "default");+ assert_eq!(json["project"], "audit");+ }++ #[tokio::test]+ async fn read_page_missing_path_returns_404() {+ let (_tmp, router) = read_page_test_router();++ let resp = router+ .oneshot(+ Request::builder()+ .uri("/admin/read-page?workspace=default&project=audit&path=notes/nope.md")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();++ assert_eq!(resp.status(), StatusCode::NOT_FOUND);+ }++ #[tokio::test]+ async fn read_page_traversal_rejected_with_400() {+ let (_tmp, router) = read_page_test_router();++ let resp = router+ .oneshot(+ Request::builder()+ .uri("/admin/read-page?workspace=default&project=audit&path=../etc/passwd")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();++ assert_eq!(resp.status(), StatusCode::BAD_REQUEST);+ }++ #[tokio::test]+ async fn read_page_without_path_or_query_returns_400() {+ let (_tmp, router) = read_page_test_router();++ let resp = router+ .oneshot(+ Request::builder()+ .uri("/admin/read-page?workspace=default&project=audit")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();++ assert_eq!(resp.status(), StatusCode::BAD_REQUEST);+ }}diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex bd9b09be..d93a9bf8 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -330,7 +330,7 @@ struct ReadPageArgs {#[serde(default)]path: Option<String>,/// Project to read from. Omit to target the project you're currently- /// working in (resolved from recent hook activity).+ /// working in (resolved from recent hook activity). **Omit unless the user explicitly names a *different* project.**#[serde(default)]project: Option<String>,}diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 9513364d..6964e359 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -203,12 +203,13 @@ Each crate has a single responsibility and exposes a typed API. Nocircular deps. Inter-crate boundaries enforce the cross-cuttinginvariants below.-## MCP tool surface (12 tools)+## MCP tool surface (13 tools)| Tool | Hint | Purpose ||---|---|---|| `memory_query` | read-only | FTS5 + graph RRF + optional vector RRF search, with raw fallback. Bumps access counters for page hits. || `memory_recent` | read-only | Most-recently-updated `is_latest=1` pages. |+| `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`. Use when an agent needs more than the 24-word snippets from `memory_query`. || `memory_status` | read-only | Counts, paths, version. || `memory_briefing` | read-only | Structured counts/activity/rules/slots/recent snapshot. || `memory_explore` | read-only | LLM prose digest over the briefing snapshot, degrading to JSON without a provider. |@@ -220,16 +221,18 @@ invariants below.| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. || `memory_install_self_routing` | read-only | Return the canonical routing snippet for CLAUDE.md / AGENTS.md. |-`memory_briefing`, `memory_explore`, `memory_write_page`, and-`memory_install_self_routing`+`memory_briefing`, `memory_explore`, `memory_write_page`,+`memory_install_self_routing`, and `memory_read_page`post-date the original "narrow on purpose" cut (§10 of`design-decisions.md`): briefing/explore separate the structured vs.prose halves of "what's going on", `memory_write_page` covers explicit-durable annotations without abusing single-use handoffs, and+durable annotations without abusing single-use handoffs,`memory_install_self_routing` exists for the meta case where the agentmust re-write its own routing rules into a project's `CLAUDE.md` /-`AGENTS.md`. The narrow-surface discipline still holds — every new tool-has to earn its slot — but the v1 count is 12, not 10.+`AGENTS.md`, and `memory_read_page` complements `memory_query` for the+"I need the full page, not a snippet" case (e.g. opening a decision page+end-to-end). The narrow-surface discipline still holds — every new tool+has to earn its slot — but the v1 count is 13, not 10.MCP parameter aliases are intentionally sparse: `memory_query.query` accepts`q|search`, and limit fields accept `n` / `top_k` where shipped. Project and