Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(mcp): memory_delete_page — trigger for op=delete

Djalma Júnior83a8dc53c3c8
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rs
index 0be0cc14..3ae18476 100644
--- a/crates/ai-memory-core/src/routing_snippet.rs
+++ b/crates/ai-memory-core/src/routing_snippet.rs
@@ -71,6 +71,7 @@ match the intent to the tool. They do not need to name the tool.
| "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |
| "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes) |
| "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup) |
+| "delete the page X" / "remove that note" | `memory_delete_page` (by exact `path`; idempotent) |
| "audit the wiki" / "find contradictions" / "what rules should we add?" | `memory_lint` |
| "prune old pages" / "memory cleanup" | `memory_forget_sweep` |
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index f3bcd2fd..36faebb3 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -81,6 +81,9 @@ the conversation calls for them:\n\
returns the top hit's full body) or a `path` (direct lookup). Use \
this instead of memory_query when the user wants the complete text, \
not just snippets.\n\
+- `memory_delete_page` — when the user explicitly asks to delete or \
+ remove a specific page (by exact path). Idempotent; fires the \
+ admission chain so mirrors/backups stay consistent.\n\
- `memory_lint` — when the user asks to audit the wiki for stale \
pages, contradictions, or rule suggestions.\n\
- `memory_forget_sweep` — when the user wants to prune old / cold \
@@ -336,6 +339,17 @@ struct ReadPageArgs {
project: Option<String>,
}
+#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]
+struct DeletePageArgs {
+ /// Exact wiki path to delete (e.g. `notes/foo.md`).
+ path: String,
+ /// Project to delete from. Omit to target the project you're currently
+ /// working in (resolved from recent hook activity). **Omit unless the
+ /// user explicitly names a *different* project.**
+ #[serde(default)]
+ project: Option<String>,
+}
+
#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]
struct WritePageArgs {
/// Relative wiki path to write, for example `notes/santander-2025.md`.
@@ -968,6 +982,50 @@ impl AiMemoryServer {
}))
}
+ /// Delete a single wiki page by exact path.
+ #[tool(description = "Delete a single wiki page by its exact relative \
+ path (e.g. `notes/foo.md`). Use when the user explicitly asks to \
+ delete or remove a page. Fires the admission chain (op=delete) \
+ before the file is removed so backups/mirrors stay consistent. \
+ Idempotent — deleting a page that is already gone is a no-op. \
+ Returns `{ path, deleted }`.")]
+ async fn memory_delete_page(
+ &self,
+ Parameters(args): Parameters<DeletePageArgs>,
+ Extension(parts): Extension<axum::http::request::Parts>,
+ ) -> Result<CallToolResult, McpError> {
+ let Some(wiki) = self.wiki.as_ref() else {
+ return Err(McpError::internal_error(
+ "memory_delete_page requires the server to be built with a wiki handle",
+ None,
+ ));
+ };
+ let path = PagePath::new(args.path.clone())
+ .map_err(|e| McpError::internal_error(format!("invalid path: {e}"), None))?;
+ let (ws, proj) = self.effective_ids(args.project.as_deref()).await;
+
+ // Carry actor identity + loop-prevention skip list (same as write_page).
+ // `Wiki::delete_page` stamps `op = Delete` regardless of what we pass.
+ let actor = crate::actor::actor_from_headers(&parts.headers);
+ let skip_webhooks = crate::actor::skip_webhooks_from_headers(&parts.headers);
+ let admission_ctx = if actor.has_any() || !skip_webhooks.is_empty() {
+ Some(ai_memory_wiki::AdmissionContext {
+ actor,
+ op: ai_memory_wiki::AdmissionOp::Delete,
+ skip_webhooks,
+ ..ai_memory_wiki::AdmissionContext::default()
+ })
+ } else {
+ None
+ };
+
+ wiki.delete_page(ws, proj, &path, admission_ctx)
+ .await
+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;
+
+ ok_json(&serde_json::json!({ "path": path.to_string(), "deleted": true }))
+ }
+
/// Create a handoff snapshot for the next agent CLI.
#[tool(description = "Record a cross-agent handoff snapshot for the \
NEXT agent that opens this project (e.g. Codex picking up after \
@@ -1414,6 +1472,7 @@ mod tests {
"memory_consolidate",
"memory_write_page",
"memory_read_page",
+ "memory_delete_page",
"memory_lint",
"memory_forget_sweep",
"memory_install_self_routing",
@@ -1930,6 +1989,72 @@ mod tests {
);
}
+ #[tokio::test]
+ async fn memory_delete_page_removes_the_page() {
+ 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);
+
+ let parts = || {
+ axum::http::Request::builder()
+ .uri("/mcp")
+ .method("POST")
+ .body(())
+ .unwrap()
+ .into_parts()
+ .0
+ };
+
+ server
+ .memory_write_page(
+ Parameters(WritePageArgs {
+ path: "notes/temp.md".into(),
+ body: "# Temp\n\nthrowaway".into(),
+ title: Some("Temp".into()),
+ tier: Some("semantic".into()),
+ tags: vec![],
+ pinned: false,
+ project: None,
+ }),
+ rmcp::handler::server::tool::Extension(parts()),
+ )
+ .await
+ .unwrap();
+
+ server
+ .memory_delete_page(
+ Parameters(DeletePageArgs {
+ path: "notes/temp.md".into(),
+ project: None,
+ }),
+ rmcp::handler::server::tool::Extension(parts()),
+ )
+ .await
+ .unwrap();
+
+ // The on-disk file is gone; reading it back errors (file not found).
+ let read = server
+ .memory_read_page(Parameters(ReadPageArgs {
+ query: None,
+ path: Some("notes/temp.md".into()),
+ project: None,
+ }))
+ .await;
+ assert!(read.is_err(), "deleted page must not be readable");
+ }
+
/// `memory_handoff_begin` must resolve the same project as
/// `memory_briefing` when hooks publish `ActiveProject` (issue #2).
#[tokio::test]
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 6964e359..440e2d13 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -217,6 +217,7 @@ invariants below.
| `memory_handoff_accept` | destructive | Fetch + ack the latest open handoff (auto-cwd-matched). |
| `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out. |
| `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate something permanent. |
+| `memory_delete_page` | destructive | Delete a single page by exact `path`. Fires the admission chain (op=delete); idempotent. |
| `memory_forget_sweep` | destructive | M8 retention pass. `dry_run=true` for preview. |
| `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. |
diff --git a/docs/admission-webhooks.md b/docs/admission-webhooks.md
index 12e84db9..c013c740 100644
--- a/docs/admission-webhooks.md
+++ b/docs/admission-webhooks.md
@@ -40,9 +40,10 @@ Webhooks fire on these `op` values today (extensible enum):
`write-page`, `/admin/write-page`, the lint rewriter, hook synthesis.
- `consolidate` — LLM consolidation writes from the consolidator
(SessionEnd opt-in + PreCompact + manual `memory_consolidate`).
-- `delete` — a single page is removed (`Wiki::delete_page`). Carries the
- page path, no body; fired **before** the file is removed so a mirror can
- `git rm` the same path.
+- `delete` — a single page is removed (`Wiki::delete_page`, triggered by the
+ `memory_delete_page` MCP tool). Carries the page path, no body; fired
+ **before** the file is removed so a mirror can `git rm` the same path. The
+ SQLite index is reconciled by the watcher on the file-removal event.
- `purge_project` — a whole project is purged (`Wiki::purge_project` →
`remove_dir_all`, routed from `/admin/purge-project`). Carries the
project in `ctx`, **no** page path; fired before the directory is