Skip to content

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.md
index 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 existing
slots; `invariant` marks high-resistance project context or preferences that
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 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.rs
index 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.md
index 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. No
circular deps. Inter-crate boundaries enforce the cross-cutting
invariants 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 agent
must 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