Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(admission): cover deletes + project purges
Djalma Júniorfc36a2f6abd0
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex f8151394..ab74053e 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -1375,18 +1375,20 @@ async fn handle_purge_project(};// Remove the entire per-project directory: <wiki_root>/<ws_uuid>/<proj_uuid>/.- // DB cascade already deleted all rows; the dir removal is best-effort.- let proj_root = state.wiki.project_root(ws_id, proj_id);- let proj_root_str = proj_root.display().to_string();+ // DB cascade already deleted all rows. Routed through Wiki::purge_project so+ // the admission chain is notified (op=purge_project) before removal — a+ // mirror can drop its copy of the project. Best-effort dir removal.+ let proj_root_str = state+ .wiki+ .project_root(ws_id, proj_id)+ .display()+ .to_string();let mut files_deleted: Vec<String> = Vec::new();let mut files_failed: Vec<String> = Vec::new();- match std::fs::remove_dir_all(&proj_root) {+ match state.wiki.purge_project(ws_id, proj_id, None).await {Ok(()) => {files_deleted.push(proj_root_str);}- Err(e) if e.kind() == std::io::ErrorKind::NotFound => {- // Already absent; nothing to do.- }Err(e) => {warn!(path = %proj_root_str, error = %e, "purge-project: failed to remove project dir");files_failed.push(proj_root_str);diff --git a/crates/ai-memory-wiki/src/admission.rs b/crates/ai-memory-wiki/src/admission.rsindex 4517280a..f13f729b 100644--- a/crates/ai-memory-wiki/src/admission.rs+++ b/crates/ai-memory-wiki/src/admission.rs@@ -48,6 +48,13 @@ pub enum AdmissionOp {/// An LLM consolidation write (consolidator/lint compile observations/// into a durable page).Consolidate,+ /// A single page is being deleted (`Wiki::delete_page`). Carries the+ /// page path; no body. Lets a mirror `git rm` the file.+ Delete,+ /// A whole project is being purged (`Wiki::purge_project` →+ /// `remove_dir_all`). Carries the project (ctx), no page path. Lets a+ /// mirror remove the project's directory.+ PurgeProject,}impl AdmissionOp {@@ -57,6 +64,8 @@ impl AdmissionOp {match self {AdmissionOp::WritePage => "write_page",AdmissionOp::Consolidate => "consolidate",+ AdmissionOp::Delete => "delete",+ AdmissionOp::PurgeProject => "purge_project",}}}@@ -358,6 +367,69 @@ impl AdmissionChain {}Ok(())}++ /// Notify webhooks of a delete / purge (`ctx.op` = `Delete` /+ /// `PurgeProject`). Unlike [`Self::run`], there is no body to send or+ /// mutate — the webhook acts on `ctx.op` + the (optional) page path, e.g.+ /// a mirror `git rm`s the file or removes the project directory. Honours+ /// the same skip-list, op-subscription, timeout, and failure policy.+ ///+ /// # Errors+ /// Returns an error only when a `Reject`-policy webhook fails.+ pub async fn notify(&self, page_path: Option<&str>, ctx: &AdmissionContext) -> WikiResult<()> {+ let empty_frontmatter = serde_json::Value::Object(serde_json::Map::new());+ for hook in self.webhooks.iter() {+ if ctx.skip_webhooks.iter().any(|n| n == &hook.name) {+ tracing::debug!(webhook = %hook.name, "admission skip (caller opt-out)");+ continue;+ }+ if !hook.events.contains(&ctx.op) {+ continue;+ }+ let payload = WebhookRequestBody {+ page: WebhookPagePayload {+ path: page_path.unwrap_or(""),+ frontmatter: &empty_frontmatter,+ body: "",+ },+ ctx,+ };+ let result = self+ .client+ .post(&hook.url)+ .header("X-Memory-Op", ctx.op.as_header_value())+ .timeout(Duration::from_millis(hook.timeout_ms))+ .json(&payload)+ .send()+ .await;+ match result {+ Ok(resp) if resp.status().is_success() => {+ tracing::debug!(webhook = %hook.name, op = ctx.op.as_header_value(), "admission notify ok");+ }+ Ok(resp) => {+ let status = resp.status();+ let body_txt = resp.text().await.unwrap_or_default();+ tracing::warn!(webhook = %hook.name, status = %status, body = %body_txt, "admission notify error response");+ if matches!(hook.failure_policy, FailurePolicy::Reject) {+ return Err(WikiError::Io(std::io::Error::other(format!(+ "admission webhook {} status {}: {}",+ hook.name, status, body_txt+ ))));+ }+ }+ Err(e) => {+ tracing::warn!(webhook = %hook.name, error = %e, "admission notify request failed");+ if matches!(hook.failure_policy, FailurePolicy::Reject) {+ return Err(WikiError::Io(std::io::Error::other(format!(+ "admission webhook {} request failed: {}",+ hook.name, e+ ))));+ }+ }+ }+ }+ Ok(())+ }}#[cfg(test)]diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex f27b4f67..b2a5eedd 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -7,7 +7,7 @@ use ai_memory_core::{NewPage, PageId, PagePath, ProjectId, Sanitizer, Tier, Workuse ai_memory_llm::Embedder;use ai_memory_store::{ReaderPool, WriterHandle, f32_vec_to_bytes};-use crate::admission::{AdmissionChain, AdmissionContext};+use crate::admission::{AdmissionChain, AdmissionContext, AdmissionOp};use crate::atomic;use crate::error::WikiResult;use crate::git::GitAdapter;@@ -196,12 +196,49 @@ impl Wiki {////// # Errors/// Returns [`WikiError::Io`] for any OS error other than "not found".- pub fn delete_page(+ /// Best-effort fill of `ctx.workspace`/`ctx.project` from ids via the+ /// store reader, so webhooks address pages by the same human names the+ /// engine uses. Mirrors the inline resolution in [`Self::write_page`].+ async fn resolve_admission_names(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ctx: &mut AdmissionContext,+ ) {+ if let Some(reader) = &self.store_reader {+ if ctx.workspace.is_empty()+ && let Ok(Some(name)) = reader.workspace_name_by_id(workspace_id).await+ {+ ctx.workspace = name;+ }+ if ctx.project.is_empty()+ && let Ok(Some(name)) = reader.project_name_by_id(workspace_id, project_id).await+ {+ ctx.project = name;+ }+ }+ }++ /// Delete a single page file. When an admission chain is attached, it is+ /// notified (`op=delete`) BEFORE the file is removed, so a mirror can+ /// `git rm` the same path. A `Reject`-policy webhook aborts the delete.+ ///+ /// # Errors+ /// Returns [`WikiError`] on a filesystem error or a rejecting webhook.+ pub async fn delete_page(&self,workspace_id: WorkspaceId,project_id: ProjectId,path: &PagePath,+ admission_ctx: Option<AdmissionContext>,) -> WikiResult<()> {+ if let Some(chain) = &self.admission_chain {+ let mut ctx = admission_ctx.unwrap_or_default();+ ctx.op = AdmissionOp::Delete;+ self.resolve_admission_names(workspace_id, project_id, &mut ctx)+ .await;+ chain.notify(Some(path.as_str()), &ctx).await?;+ }let abs = self.abs_path(workspace_id, project_id, path);match std::fs::remove_file(&abs) {Ok(()) => Ok(()),@@ -210,6 +247,35 @@ impl Wiki {}}+ /// Purge a whole project's wiki directory. When an admission chain is+ /// attached, it is notified (`op=purge_project`, no page path) BEFORE the+ /// directory is removed, so a mirror can drop the project. A `Reject`+ /// webhook aborts the purge. Routes the on-disk removal through the+ /// namespaced [`Self::project_root`] (invariant: never hand-roll paths).+ ///+ /// # Errors+ /// Returns [`WikiError`] on a filesystem error or a rejecting webhook.+ pub async fn purge_project(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ admission_ctx: Option<AdmissionContext>,+ ) -> WikiResult<()> {+ if let Some(chain) = &self.admission_chain {+ let mut ctx = admission_ctx.unwrap_or_default();+ ctx.op = AdmissionOp::PurgeProject;+ self.resolve_admission_names(workspace_id, project_id, &mut ctx)+ .await;+ chain.notify(None, &ctx).await?;+ }+ let root = self.project_root(workspace_id, project_id);+ match std::fs::remove_dir_all(&root) {+ Ok(()) => Ok(()),+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),+ Err(e) => Err(crate::WikiError::Io(e)),+ }+ }+/// Cloneable handle to the underlying store writer.#[must_use]pub fn writer(&self) -> &WriterHandle {diff --git a/crates/ai-memory-wiki/tests/admission.rs b/crates/ai-memory-wiki/tests/admission.rsindex 102e4d5c..cef86151 100644--- a/crates/ai-memory-wiki/tests/admission.rs+++ b/crates/ai-memory-wiki/tests/admission.rs@@ -509,3 +509,100 @@ async fn workspace_and_project_names_propagate_in_payload() {assert_eq!(payload["ctx"]["workspace"], json!("default"));assert_eq!(payload["ctx"]["project"], json!("ai-memory-ops"));}++/// Records `(op-header, page.path)` for each request the webhook receives.+fn recording_app(seen: Arc<Mutex<Vec<(String, String)>>>) -> Router {+ Router::new().route(+ "/hook",+ post(move |headers: HeaderMap, Json(payload): Json<Value>| {+ let seen = seen.clone();+ async move {+ let op = headers+ .get("X-Memory-Op")+ .and_then(|v| v.to_str().ok())+ .unwrap_or("")+ .to_string();+ let path = payload["page"]["path"].as_str().unwrap_or("").to_string();+ seen.lock().unwrap().push((op, path));+ StatusCode::NO_CONTENT+ }+ }),+ )+}++#[tokio::test]+async fn notify_delete_sends_op_and_path() {+ let seen = Arc::new(Mutex::new(Vec::new()));+ let base = spawn_server(recording_app(seen.clone())).await;+ let chain = AdmissionChain::new(vec![WebhookConfig {+ name: "mirror".into(),+ url: format!("{base}/hook"),+ timeout_ms: 2_000,+ failure_policy: FailurePolicy::Ignore,+ events: vec![AdmissionOp::Delete],+ }])+ .unwrap();++ let ctx = AdmissionContext {+ op: AdmissionOp::Delete,+ ..AdmissionContext::default()+ };+ chain.notify(Some("runbooks/02.md"), &ctx).await.unwrap();++ let rec = seen.lock().unwrap();+ assert_eq!(rec.len(), 1, "delete must fire one notify");+ assert_eq!(rec[0].0, "delete");+ assert_eq!(rec[0].1, "runbooks/02.md");+}++#[tokio::test]+async fn notify_purge_has_op_and_no_path() {+ let seen = Arc::new(Mutex::new(Vec::new()));+ let base = spawn_server(recording_app(seen.clone())).await;+ let chain = AdmissionChain::new(vec![WebhookConfig {+ name: "mirror".into(),+ url: format!("{base}/hook"),+ timeout_ms: 2_000,+ failure_policy: FailurePolicy::Ignore,+ events: vec![AdmissionOp::PurgeProject],+ }])+ .unwrap();++ let ctx = AdmissionContext {+ op: AdmissionOp::PurgeProject,+ project: "atlas".into(),+ ..AdmissionContext::default()+ };+ chain.notify(None, &ctx).await.unwrap();++ let rec = seen.lock().unwrap();+ assert_eq!(rec.len(), 1);+ assert_eq!(rec[0].0, "purge_project");+ assert_eq!(rec[0].1, "", "purge carries no page path");+}++#[tokio::test]+async fn notify_respects_op_subscription() {+ // A webhook subscribed only to WritePage must not receive a Delete notify.+ let seen = Arc::new(Mutex::new(Vec::new()));+ let base = spawn_server(recording_app(seen.clone())).await;+ let chain = AdmissionChain::new(vec![WebhookConfig {+ name: "writes-only".into(),+ url: format!("{base}/hook"),+ timeout_ms: 2_000,+ failure_policy: FailurePolicy::Ignore,+ events: vec![AdmissionOp::WritePage],+ }])+ .unwrap();++ let ctx = AdmissionContext {+ op: AdmissionOp::Delete,+ ..AdmissionContext::default()+ };+ chain.notify(Some("x.md"), &ctx).await.unwrap();++ assert!(+ seen.lock().unwrap().is_empty(),+ "delete must not reach a write-only webhook"+ );+}diff --git a/docs/admission-webhooks.md b/docs/admission-webhooks.mdindex 20630d0f..12e84db9 100644--- a/docs/admission-webhooks.md+++ b/docs/admission-webhooks.md@@ -1,6 +1,7 @@# Admission webhooks: pre-persistence HTTP hooks-> Operator-configured HTTP hooks invoked inside `Wiki::write_page`+> Operator-configured HTTP hooks invoked on the engine's write path+> (`Wiki::write_page`, `delete_page`, `purge_project`)> just before the page hits disk. Each hook can mutate the> page (return a new frontmatter / body) or just observe and side-effect> (return `204 No Content`). Sourced from@@ -39,9 +40,34 @@ 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`).--Each webhook opts into the ops it cares about via `events`. The chain-checks the op against `WebhookConfig::events` before dispatching.+- `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.+- `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+ removed so a mirror can drop the project.++`delete` / `purge_project` are notifications — there is no body to mutate;+a `Reject`-policy webhook still aborts the operation. Each webhook opts+into the ops it cares about via `events`; the chain checks the op against+`WebhookConfig::events` before dispatching.++### What does NOT fire the chain (by design)++- **`log.md` / `log-YYYY-MM.md` appends** — written on every hook event+ (per prompt/tool-call). Routing each through the chain would mean an+ HTTP POST per observation, violating the fire-and-forget hook budget. The+ per-event log is a local audit artifact; back it up out-of-band (batched+ rsync), not per-line.+- **Handoffs** — SQLite rows, transient cross-agent state, not wiki pages.+- **Forget-sweep soft/hard-delete** — DB-only (`is_latest=0` / row delete);+ the markdown file stays on disk, so there is nothing for a file mirror to+ do. (Only `purge_project` removes files in bulk.)+- **`rename-project`** — a `projects.name` column update; the on-disk path+ is the stable UUID, so no file moves and nothing to propagate.+- **External / manual edits on disk** — reconciled by the watcher, not the+ admission chain (the chain is for the engine's own write path).## 3. Wire contract@@ -50,7 +76,7 @@ checks the op against `WebhookConfig::events` before dispatching.```httpPOST <webhook.url>Content-Type: application/json-X-Memory-Op: write_page | consolidate+X-Memory-Op: write_page | consolidate | delete | purge_project``````jsonc@@ -70,7 +96,7 @@ X-Memory-Op: write_page | consolidate"client": "72836f52-...", // DCR client UUID"session_id": "019e6d-..."},- "op": "write_page" // write_page | consolidate+ "op": "write_page" // write_page | consolidate | delete | purge_project}}```