Skip to content

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.rs
index 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.rs
index 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.rs
index 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, Work
use 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.rs
index 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.md
index 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.
```http
POST <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
}
}
```