Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(core,wiki,mcp): refuse git-reserved page paths and enforce portability in batch writes
Vinícius Andradee689c7bae7e5
diff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rsindex b696e95b..1aa1404a 100644--- a/crates/ai-memory-core/src/ids.rs+++ b/crates/ai-memory-core/src/ids.rs@@ -108,33 +108,6 @@ impl PagePath {////// # Errors/// Returns [`MemoryError::InvalidPagePath`] when the input is empty or- /// Reject a path that cannot be materialised and checkpointed on every- /// supported platform.- ///- /// Deliberately **not** part of [`PagePath::new`]. Persisted rows are- /// reconstructed through that constructor on every read- /// (`reader.rs` does so in the recency, search, vector and graph- /// queries), so tightening it would make any already-stored- /// non-portable page unreadable — and because those are list queries,- /// one such page would break a whole listing rather than just itself.- /// The rule therefore applies where a *new* path enters the system.- ///- /// The rule is the same on every platform on purpose. A wiki authored- /// on Linux is expected to be usable on Windows by the same release;- /// making the check platform-conditional would let a Linux session- /// create pages a Windows session cannot read, which is the defect- /// being fixed rather than a fix for it (#462).- ///- /// # Errors- /// Returns [`MemoryError::InvalidPagePath`] naming the offending- /// component and the reason.- pub fn ensure_portable(&self) -> Result<(), MemoryError> {- for component in self.as_str().split('/') {- ensure_portable_component(component, self.as_str())?;- }- Ok(())- }-/// contains a path component that would escape or alias the wiki root.pub fn new(raw: impl Into<String>) -> Result<Self, MemoryError> {let raw = raw.into();@@ -184,6 +157,33 @@ impl PagePath {Ok(Self(raw))}+ /// Reject a path that cannot be materialised and checkpointed on every+ /// supported platform.+ ///+ /// Deliberately **not** part of [`PagePath::new`]. Persisted rows are+ /// reconstructed through that constructor on every read+ /// (`reader.rs` does so in the recency, search, vector and graph+ /// queries), so tightening it would make any already-stored+ /// non-portable page unreadable — and because those are list queries,+ /// one such page would break a whole listing rather than just itself.+ /// The rule therefore applies where a *new* path enters the system.+ ///+ /// The rule is the same on every platform on purpose. A wiki authored+ /// on Linux is expected to be usable on Windows by the same release;+ /// making the check platform-conditional would let a Linux session+ /// create pages a Windows session cannot read, which is the defect+ /// being fixed rather than a fix for it (#462).+ ///+ /// # Errors+ /// Returns [`MemoryError::InvalidPagePath`] naming the offending+ /// component and the reason.+ pub fn ensure_portable(&self) -> Result<(), MemoryError> {+ for component in self.as_str().split('/') {+ ensure_portable_component(component, self.as_str())?;+ }+ Ok(())+ }+/// Borrow the inner string.#[must_use]pub fn as_str(&self) -> &str {@@ -704,6 +704,16 @@ const DOS_DEVICE_NAMES: &[&str] = &[/// [`PagePath::new`].const WINDOWS_RESERVED_CHARS: &[char] = &['<', '>', ':', '"', '|', '?', '*'];+/// Returns true if a path component is reserved by Git (`.git` case-insensitively,+/// or an 8.3 short-name alias like `git~1`..`git~4`).+#[must_use]+pub fn is_git_reserved_component(component: &str) -> bool {+ component.eq_ignore_ascii_case(".git")+ || (component.len() == 5+ && component[..4].eq_ignore_ascii_case("git~")+ && (b'1'..=b'4').contains(&component.as_bytes()[4]))+}+fn ensure_portable_component(component: &str, full: &str) -> Result<(), MemoryError> {let invalid = |reason: &str| {Err(MemoryError::InvalidPagePath(format!(@@ -738,6 +748,12 @@ fn ensure_portable_component(component: &str, full: &str) -> Result<(), MemoryEr"uses the reserved DOS device name {stem:?}; Windows resolves it to a device, not a file"));}+ // Git reserves `.git` for repository metadata. Any tree entry named `.git`+ // or an 8.3 alias is refused by libgit2 with `GIT_EINVALIDPATH` and cannot+ // be checkpointed.+ if is_git_reserved_component(component) {+ return invalid("is reserved by Git for repository metadata and refused in tree entries");+ }Ok(())}@@ -778,6 +794,30 @@ mod portable_page_path_tests {}}+ #[test]+ fn git_reserved_paths_are_rejected() {+ for raw in [+ ".git",+ ".git/config",+ ".git/HEAD",+ "notes/.git",+ "notes/.git/sub.md",+ "notes/.GIT/sub.md",+ "notes/.Git/sub.md",+ "notes/git~1",+ "notes/git~1/foo.md",+ "notes/GIT~2/bar.md",+ "notes/git~4/config",+ "a/b/c/.git/deep.md",+ ] {+ let path = PagePath::new(raw).expect("still constructible: reads must keep working");+ assert!(+ path.ensure_portable().is_err(),+ "{raw:?} contains a git-reserved component and must be refused at write time"+ );+ }+ }+/// The rule must not reject ordinary pages. `con` is only reserved as a/// whole component, so `concepts/` and `icon.md` are fine.#[test]@@ -792,6 +832,11 @@ mod portable_page_path_tests {"a/b/c/deep.md","notes/dot.in.middle.md","notes/UPPER.MD",+ "notes/.git.md",+ "notes/.gitignore",+ "notes/.gitattributes",+ "notes/github.md",+ "git-notes/index.md",] {let path = PagePath::new(raw).expect("valid path");assert!(@@ -806,7 +851,14 @@ mod portable_page_path_tests {/// not break on one bad row.#[test]fn existing_non_portable_pages_remain_constructible() {- for raw in ["CON.md", "notes/a|b.md", "notes/trailing./x.md"] {+ for raw in [+ "CON.md",+ "notes/a|b.md",+ "notes/trailing./x.md",+ ".git/config",+ "notes/.git/sub.md",+ "notes/git~1/foo.md",+ ] {assert!(PagePath::new(raw).is_ok(),"{raw:?} must still construct so persisted rows stay readable"diff --git a/crates/ai-memory-core/src/lib.rs b/crates/ai-memory-core/src/lib.rsindex 2a5d61d7..058dc038 100644--- a/crates/ai-memory-core/src/lib.rs+++ b/crates/ai-memory-core/src/lib.rs@@ -58,7 +58,7 @@ pub use handoff::{pub use ids::{AgentKind, ApiCredentialId, AutoImproveProposalId, AutoImproveRunId, EntityId, HandoffId,ManagedRunId, MessageId, ObservationId, PageFeedbackId, PageId, PagePath, ProjectId, SessionId,- UserId, WorkspaceId, WorkstreamId,+ UserId, WorkspaceId, WorkstreamId, is_git_reserved_component,};pub use message::{AgentMessage, MessageBox, MessageClaim, MessageOrigin, MessageState, NewAgentMessage,diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 1f6e4fe0..77b513a0 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -6765,6 +6765,12 @@ async fn handle_write_page(Json(serde_json::json!({ "error": format!("invalid path: {e}") })),)})?;+ path.ensure_portable().map_err(|e| {+ (+ StatusCode::UNPROCESSABLE_ENTITY,+ Json(serde_json::json!({ "error": format!("invalid path: {e}") })),+ )+ })?;let (ws, proj) = create_ws_proj(&state, &req.workspace, &req.project).await?;@@ -8906,6 +8912,46 @@ mod tests {assert_eq!(resp.status(), StatusCode::OK, "write-page setup failed");}+ #[tokio::test]+ async fn admin_write_page_refuses_git_reserved_and_non_portable_paths() {+ let (_tmp, router) = read_page_test_router();+ for bad in [+ ".git",+ ".git/config",+ "notes/.git",+ "notes/.git/sub.md",+ "notes/git~1",+ "notes/git~1/foo.md",+ "CON.md",+ "notes/aux.md",+ "notes/a|b.md",+ ] {+ let req_body = serde_json::json!({+ "workspace": "default",+ "project": "audit",+ "path": bad,+ "body": "bad path body",+ });+ 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::UNPROCESSABLE_ENTITY,+ "expected 422 for {bad:?}"+ );+ }+ }+#[tokio::test]async fn read_page_path_mode_returns_full_body() {let (_tmp, router) = read_page_test_router();diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex e1b78c22..858c9f03 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -3081,6 +3081,8 @@ impl AiMemoryServer {.map_err(|_| McpError::internal_error(format!("unknown tier '{tier_name}'"), None))?;let path = PagePath::new(args.path.clone()).map_err(|e| McpError::internal_error(format!("invalid path: {e}"), None))?;+ path.ensure_portable()+ .map_err(|e| McpError::internal_error(format!("invalid path: {e}"), None))?;let path = self.place_slot_write(path, &parts).await?;let (ws, proj) = match args.scope.as_deref().map(str::trim) {None | Some("") => {@@ -9905,10 +9907,66 @@ mod tests {.unwrap();assert!(recent_text.contains("notes/santander-2025.md"),- "write-page result must be visible to read tools; got {recent_text}"+ "got {recent_text}");}+ #[tokio::test]+ async fn memory_write_page_refuses_git_reserved_and_non_portable_paths() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "scratch", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ let server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj)+ .with_wiki(wiki);++ for bad in [+ ".git",+ ".git/config",+ "notes/.git",+ "notes/.git/sub.md",+ "notes/.GIT/sub.md",+ "notes/git~1",+ "notes/git~1/foo.md",+ "notes/GIT~2/bar.md",+ "CON.md",+ "notes/aux.md",+ "notes/a|b.md",+ ] {+ let err = server+ .memory_write_page(+ Parameters(WritePageArgs {+ path: bad.into(),+ body: "# Bad\n\nShould be refused.".into(),+ title: None,+ tier: None,+ tags: vec![],+ pinned: false,+ project: None,+ workspace: None,+ scope: None,+ expires_at: None,+ }),+ OptionalParts(test_parts_default()),+ )+ .await+ .unwrap_err();+ assert!(+ err.to_string().contains("invalid path"),+ "expected invalid path error for {bad:?}, got: {err}"+ );+ }+ }+#[tokio::test]async fn memory_write_page_rejects_workspace_without_project() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-wiki/src/git.rs b/crates/ai-memory-wiki/src/git.rsindex 03326ef7..98329c54 100644--- a/crates/ai-memory-wiki/src/git.rs+++ b/crates/ai-memory-wiki/src/git.rs@@ -150,7 +150,12 @@ impl GitAdapter {Some(path)};// The watcher reports git's own writes too; never stage them.- if rel.is_some_and(|rel| rel.starts_with(".git")) {+ // Also ignore any path that contains a git-reserved component.+ if rel.is_some_and(|rel| {+ rel.components().any(|c| {+ ai_memory_core::is_git_reserved_component(&c.as_os_str().to_string_lossy())+ })+ }) {return;}let mut written = self.written();@@ -621,6 +626,13 @@ fn stage_paths(paths: &BTreeSet<PathBuf>,) -> Result<usize, git2::Error> {for rel in paths {+ if rel+ .components()+ .any(|c| ai_memory_core::is_git_reserved_component(&c.as_os_str().to_string_lossy()))+ {+ warn!(path = %rel.display(), "skipping invalid git path with git-reserved component");+ continue;+ }let abs = root.join(rel);if abs.is_dir() {let spec = slash_path(rel);@@ -1048,6 +1060,9 @@ mod tests {adapter.mark_written(Path::new(".git/logs/HEAD"));adapter.mark_written(&root.join(".git/index"));adapter.mark_written(Path::new(".git"));+ adapter.mark_written(Path::new("ws/proj/.git/config"));+ adapter.mark_written(&root.join("ws/proj/.git/hooks/pre-commit"));+ adapter.mark_written(Path::new("ws/proj/git~1/config"));assert!(adapter.written_paths().is_empty());}diff --git a/crates/ai-memory-wiki/src/watcher.rs b/crates/ai-memory-wiki/src/watcher.rsindex 93a5ecc4..d223e40f 100644--- a/crates/ai-memory-wiki/src/watcher.rs+++ b/crates/ai-memory-wiki/src/watcher.rs@@ -196,10 +196,12 @@ async fn run_loop(}}-/// Inside the wiki's own git directory: neither indexed nor reported.+/// Inside the wiki's own git directory or any nested git metadata: neither indexed nor reported.fn is_git_internal(root: &Path, path: &Path) -> bool {- path.strip_prefix(root)- .is_ok_and(|rel| rel.starts_with(".git"))+ path.strip_prefix(root).is_ok_and(|rel| {+ rel.components()+ .any(|c| ai_memory_core::is_git_reserved_component(&c.as_os_str().to_string_lossy()))+ })}async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent) {@@ -924,13 +926,24 @@ mod tests {let git_log = wiki.root().join(".git/logs/HEAD");std::fs::create_dir_all(git_log.parent().unwrap()).unwrap();std::fs::write(&git_log, "ref\n").unwrap();+ let nested_git = proj_dir.join(".git/config");+ std::fs::create_dir_all(nested_git.parent().unwrap()).unwrap();+ std::fs::write(&nested_git, "config\n").unwrap();let gone = proj_dir.join("gone.md");for (kind, path) in [(EventKind::Create(notify::event::CreateKind::File), &ledger),(EventKind::Modify(notify::event::ModifyKind::Any), &git_log),+ (+ EventKind::Create(notify::event::CreateKind::File),+ &nested_git,+ ),(EventKind::Remove(notify::event::RemoveKind::File), &gone),(EventKind::Remove(notify::event::RemoveKind::File), &git_log),+ (+ EventKind::Remove(notify::event::RemoveKind::File),+ &nested_git,+ ),] {let event = notify_debouncer_full::DebouncedEvent::new(notify::Event::new(kind).add_path(path.clone()),@@ -944,7 +957,9 @@ mod tests {assert!(reported.contains(&rel(&ledger)), "{reported:?}");assert!(reported.contains(&rel(&gone)), "{reported:?}");assert!(- !reported.iter().any(|p| p.starts_with(".git")),+ !reported+ .iter()+ .any(|p| p.components().any(|c| c.as_os_str() == ".git")),"{reported:?}");}diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 58d0aecb..871f0987 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -1394,6 +1394,7 @@ impl Wiki {.ok_or_else(|| ai_memory_wiki_error("auto-improve proposal not found in scope"))?;let path = detail.summary.target_path.clone();+ path.ensure_portable()?;let mut frontmatter = serde_json::json!({"kind": detail.summary.kind,"title": detail.summary.title,@@ -1810,6 +1811,11 @@ impl Wiki {if requests.is_empty() {return Ok(Vec::new());}+ // Reject any path that cannot be materialised and checkpointed on every+ // supported platform, before anything is written.+ for req in &requests {+ req.path.ensure_portable()?;+ }// Pre-compute markdown for each request. Filesystem work happens only// after the mutation guard + project/workspace validation below.let mut staged: Vec<(@@ -5686,4 +5692,65 @@ mod tests {Some((ws, dst)));}++ #[tokio::test]+ async fn write_page_and_apply_batch_refuse_git_reserved_and_non_portable_paths() {+ let tmp = TempDir::new().unwrap();+ let (_store, wiki, ws, proj) = scoped(&tmp).await;++ for bad in [+ "CON.md",+ "notes/aux.md",+ ".git",+ ".git/config",+ "notes/.git",+ "notes/.git/sub.md",+ "notes/.GIT/sub.md",+ "notes/git~1",+ "notes/git~1/foo.md",+ "notes/GIT~2/bar.md",+ ] {+ let bad_path = PagePath::new(bad).unwrap();+ let write_err = wiki+ .write_page(req(+ ws,+ proj,+ bad_path.as_str(),+ "content",+ serde_json::json!({}),+ ))+ .await+ .unwrap_err();+ assert!(+ matches!(+ write_err,+ WikiError::Memory(ai_memory_core::MemoryError::InvalidPagePath(_))+ ),+ "write_page should refuse {bad:?}, got: {write_err}"+ );++ let batch_err = wiki+ .apply_batch(vec![req(+ ws,+ proj,+ bad_path.as_str(),+ "content",+ serde_json::json!({}),+ )])+ .await+ .unwrap_err();+ assert!(+ matches!(+ batch_err,+ WikiError::Memory(ai_memory_core::MemoryError::InvalidPagePath(_))+ ),+ "apply_batch should refuse {bad:?}, got: {batch_err}"+ );++ assert!(+ !wiki.abs_path(ws, proj, &bad_path).exists(),+ "file for {bad:?} must not be written to disk"+ );+ }+ }}