Skip to content

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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.