Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(mcp): make read_page reliable — cross-workspace scope + DB fallback
Djalma Júniorb3bd998576b8
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex a76de943..0af277a2 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -461,10 +461,40 @@ async fn handle_read_page(Json(serde_json::to_value(&resp).unwrap_or_else(|_| serde_json::json!({}))),)}- Err(e) => (- StatusCode::NOT_FOUND,- Json(serde_json::json!({ "error": e.to_string() })),- ),+ // On-disk read failed — fall back to the DB's faithful copy before+ // 404ing (index/disk skew; see gotchas/read-page-by-query-misses).+ Err(disk_err) => match state+ .reader+ .page_body_by_ids(ws, proj, page_path.as_str())+ .await+ {+ Ok(Some(stored)) => {+ let frontmatter: serde_json::Value = serde_json::from_str(&stored.frontmatter_json)+ .unwrap_or(serde_json::Value::Null);+ let title = frontmatter+ .get("title")+ .and_then(|v| v.as_str())+ .map(str::to_string)+ .or(Some(stored.title));+ let resp = ReadPageResponse {+ path: page_path.to_string(),+ workspace: query.workspace,+ project: query.project,+ title,+ body: stored.body,+ frontmatter,+ };+ (+ StatusCode::OK,+ Json(serde_json::to_value(&resp).unwrap_or_else(|_| serde_json::json!({}))),+ )+ }+ Ok(None) => (+ StatusCode::NOT_FOUND,+ Json(serde_json::json!({ "error": disk_err.to_string() })),+ ),+ Err(e) => internal_err(e.to_string()),+ },}}diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex d5057754..e70c2945 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -379,6 +379,12 @@ struct ReadPageArgs {/// working in (resolved from recent hook activity). **Omit unless the user explicitly names a *different* project.**#[serde(default)]project: Option<String>,+ /// Workspace to read together with `project`. Omit to use the+ /// current/default workspace resolution chain. Provide both to read a+ /// page that lives in a *different* workspace (e.g. a sibling project on+ /// a shared server).+ #[serde(default)]+ workspace: Option<String>,}#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]@@ -1028,7 +1034,12 @@ impl AiMemoryServer {None,));};- let (ws, proj) = self.effective_ids(args.project.as_deref()).await;+ // Same scope resolution as memory_query: an explicit workspace+project+ // can target a page in a DIFFERENT workspace (a sibling project on a+ // shared server). Plain `project` keeps the active-project chain.+ let (ws, proj) = self+ .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .await?;let page_path = if let Some(p) = args.path {PagePath::new(p)@@ -1055,22 +1066,53 @@ impl AiMemoryServer {));};- let md = wiki- .read_page(ws, proj, &page_path)- .map_err(|e| McpError::internal_error(e.to_string(), None))?;-- let title = md- .frontmatter- .get("title")- .and_then(|v| v.as_str())- .map(str::to_string);-- ok_json(&serde_json::json!({- "path": page_path.to_string(),- "title": title,- "body": md.body,- "frontmatter": md.frontmatter,- }))+ // Markdown on disk is the source of truth, but the on-disk read can+ // fail when the index is momentarily ahead of disk (recently-written+ // page, or a known watcher/disk skew — gotchas/read-page-by-query-misses).+ // Fall back to the DB's faithful copy before surfacing an error so the+ // agent never wrongly concludes a page it can see in search is gone.+ match wiki.read_page(ws, proj, &page_path) {+ Ok(md) => {+ let title = md+ .frontmatter+ .get("title")+ .and_then(|v| v.as_str())+ .map(str::to_string);+ ok_json(&serde_json::json!({+ "path": page_path.to_string(),+ "title": title,+ "body": md.body,+ "frontmatter": md.frontmatter,+ }))+ }+ Err(disk_err) => {+ match self+ .reader+ .page_body_by_ids(ws, proj, page_path.as_str())+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?+ {+ Some(stored) => {+ let frontmatter: serde_json::Value =+ serde_json::from_str(&stored.frontmatter_json)+ .unwrap_or(serde_json::Value::Null);+ let title = frontmatter+ .get("title")+ .and_then(|v| v.as_str())+ .map(str::to_string)+ .or(Some(stored.title));+ ok_json(&serde_json::json!({+ "path": page_path.to_string(),+ "title": title,+ "body": stored.body,+ "frontmatter": frontmatter,+ "served_from": "db-fallback",+ }))+ }+ None => Err(McpError::internal_error(disk_err.to_string(), None)),+ }+ }+ }}/// Create a handoff snapshot for the next agent CLI.diff --git a/crates/ai-memory-mcp/tests/admin_read_page.rs b/crates/ai-memory-mcp/tests/admin_read_page.rsnew file mode 100644index 00000000..ab7740cd--- /dev/null+++ b/crates/ai-memory-mcp/tests/admin_read_page.rs@@ -0,0 +1,175 @@+//! Integration tests for `GET /admin/read-page`, focused on the DB-backed+//! fallback: when the on-disk markdown read fails (index ahead of disk), the+//! handler serves the store's faithful copy instead of 404ing+//! (gotchas/read-page-by-query-misses).++use ai_memory_core::{NewPage, PagePath, Tier};+use ai_memory_mcp::{AdminState, admin_router};+use ai_memory_store::{DecayParams, Store};+use ai_memory_wiki::{Wiki, WritePageRequest};+use axum::body::Body;+use axum::http::{Request, StatusCode};+use tempfile::TempDir;+use tower::ServiceExt;++async fn make_state(tmp: &TempDir) -> (AdminState, Store) {+ let store = Store::open(tmp.path()).unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ let db_path = store.db_path().to_path_buf();+ let state = AdminState {+ writer: store.writer.clone(),+ reader: store.reader.clone(),+ wiki,+ llm: None,+ embedder: None,+ provider_health: ai_memory_llm::ProviderHealth::default(),+ decay_params: DecayParams::default(),+ data_dir: tmp.path().to_path_buf(),+ db_path,+ bind: "127.0.0.1:49374".to_string(),+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),+ token_pepper: None,+ };+ (state, store)+}++async fn body_json(resp: axum::response::Response) -> serde_json::Value {+ let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)+ .await+ .unwrap();+ serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null)+}++async fn get(state: AdminState, uri: &str) -> axum::response::Response {+ let router = admin_router(state);+ let req = Request::builder()+ .method("GET")+ .uri(uri)+ .body(Body::empty())+ .unwrap();+ router.oneshot(req).await.unwrap()+}++/// A page present in the store but NOT on disk (the index is ahead of the+/// filesystem) is still served — from the DB copy — rather than 404ing.+#[tokio::test]+async fn read_page_falls_back_to_db_when_file_missing() {+ let tmp = TempDir::new().unwrap();+ let (state, store) = make_state(&tmp).await;++ // Seed straight through the store writer: this writes the DB row + FTS+ // index but NEVER touches disk, so the on-disk read will fail.+ let ws = store+ .writer+ .get_or_create_workspace("default".to_string())+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "scratch".to_string(), None)+ .await+ .unwrap();+ store+ .writer+ .upsert_page(NewPage {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new("notes/db-only.md").unwrap(),+ title: "DB Only".to_string(),+ body: "this body lives only in the database".to_string(),+ tier: Tier::Semantic,+ frontmatter_json: serde_json::json!({"title": "DB Only"}),+ pinned: false,+ links: Vec::new(),+ author_id: None,+ })+ .await+ .unwrap();++ let resp = get(+ state,+ "/admin/read-page?workspace=default&project=scratch&path=notes%2Fdb-only.md",+ )+ .await;+ assert_eq!(resp.status(), StatusCode::OK, "must serve from DB fallback");+ let body = body_json(resp).await;+ assert_eq!(+ body["body"].as_str().unwrap_or(""),+ "this body lives only in the database",+ "{body}"+ );+ assert_eq!(body["title"], "DB Only", "{body}");+}++/// Sanity: a page written through the wiki (disk + index) is served from disk+/// and reads back its body. Guards the happy path the fallback wraps.+#[tokio::test]+async fn read_page_serves_on_disk_page() {+ let tmp = TempDir::new().unwrap();+ let (state, store) = make_state(&tmp).await;+ let ws = store+ .writer+ .get_or_create_workspace("default".to_string())+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "scratch".to_string(), None)+ .await+ .unwrap();+ state+ .wiki+ .write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new("notes/on-disk.md").unwrap(),+ frontmatter: serde_json::json!({"title": "On Disk"}),+ body: "written to disk via the wiki".to_string(),+ tier: Tier::Semantic,+ pinned: false,+ title: Some("On Disk".into()),+ author_id: None,+ actor: ai_memory_core::ActorContext::anonymous(),+ })+ .await+ .unwrap();++ let resp = get(+ state,+ "/admin/read-page?workspace=default&project=scratch&path=notes%2Fon-disk.md",+ )+ .await;+ assert_eq!(resp.status(), StatusCode::OK);+ let body = body_json(resp).await;+ assert_eq!(+ body["body"].as_str().unwrap_or(""),+ "written to disk via the wiki",+ "{body}"+ );+}++/// A genuinely-absent page (no DB row, no file) still 404s — the fallback+/// must not mask a real miss.+#[tokio::test]+async fn read_page_404_when_truly_absent() {+ let tmp = TempDir::new().unwrap();+ let (state, store) = make_state(&tmp).await;+ // Create the workspace/project so resolution succeeds but the page does not.+ let ws = store+ .writer+ .get_or_create_workspace("default".to_string())+ .await+ .unwrap();+ store+ .writer+ .get_or_create_project(ws, "scratch".to_string(), None)+ .await+ .unwrap();++ let resp = get(+ state,+ "/admin/read-page?workspace=default&project=scratch&path=notes%2Fnope.md",+ )+ .await;+ assert_eq!(resp.status(), StatusCode::NOT_FOUND);+}diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex a2905ae4..d3d139ec 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -30,7 +30,7 @@ pub use reader::{ActivityWindow, BriefingPage, BriefingSnapshot, DecayCandidate, DerivedIndexStatus,EmbeddingTripleCount, HealthDetail, HealthPage, ObservationHit, PageAuthor, PageHit,PageHitWithMeta, PageLinks, PageMeta, PageSummary, ProjectSummary, ReaderPool, RelatedPage,- StatusCounts, StoredEmbedding, WorkspaceSummary, f32_vec_to_bytes,+ StatusCounts, StoredEmbedding, StoredPageBody, WorkspaceSummary, f32_vec_to_bytes,};pub use users::{TOKEN_HASH_LEN, TOKEN_RAW_LEN, TokenPepper, generate_token, hash_token};pub use writer::WriterHandle;diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 3025d756..2ef666e9 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -41,6 +41,20 @@ pub struct PageHit {pub rank: f64,}+/// The latest version of a page's stored content, used as a DB-backed+/// fallback when the on-disk markdown read fails (index/disk skew). The+/// markdown file is the source of truth, but the store keeps a faithful copy+/// written in the same transaction, so serving it is safe.+#[derive(Debug, Clone)]+pub struct StoredPageBody {+ /// Page title as stored in the DB.+ pub title: String,+ /// Page body (markdown without frontmatter).+ pub body: String,+ /// Raw `frontmatter_json` TEXT column (parse at the call site).+ pub frontmatter_json: String,+}+/// Search hit with workspace/project names, used by the web UI to avoid/// per-hit metadata lookups after a global search.#[derive(Debug, Clone, Serialize)]@@ -2572,6 +2586,42 @@ impl ReaderPool {.await}+ /// Fetch the latest version's stored body/title/frontmatter for a page by+ /// `(workspace_id, project_id, path)`. Used as a DB-backed fallback for+ /// `memory_read_page` when the on-disk markdown read fails (index/disk+ /// skew — see `gotchas/read-page-by-query-misses`). Returns `None` when no+ /// `is_latest` row exists.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn page_body_by_ids(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ path: &str,+ ) -> StoreResult<Option<StoredPageBody>> {+ let path = path.to_owned();+ self.with_conn(move |conn| {+ let row = conn+ .query_row(+ "SELECT title, body, frontmatter_json FROM pages \+ WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 \+ AND is_latest = 1",+ params![workspace_id.as_bytes(), project_id.as_bytes(), path],+ |row| {+ Ok(StoredPageBody {+ title: row.get(0)?,+ body: row.get(1)?,+ frontmatter_json: row.get(2)?,+ })+ },+ )+ .optional()?;+ Ok(row)+ })+ .await+ }+/// Look up a workspace id by name without creating it.////// Returns `None` when no workspace with the given name exists.