Skip to content

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

Rust

fix(wiki): serialize session purge with page mutations

Samir Hanna Verzaaed9b8bed689
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa333692..baccb86d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
now uses the import instead of a prose pointer (#680).
### Fixed
+- `purge-session` held the wiki mutation guard across database deletion and file
+ cleanup, preventing an in-flight watcher reindex from restoring deleted rows
+ or a concurrent page write from losing its file during cleanup (#653).
- The from-source AUR `PKGBUILD` now builds and tests on constrained AUR
builders. Release LTO was disabled (`options=('!debug' '!lto')`) so the
final link no longer gets OOM-killed on low-memory build hosts, and the
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index bdd5bb76..b95575b0 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -3598,38 +3598,6 @@ pub struct PurgeSessionReport {
pub checkpoint: Option<String>,
}
-async fn remove_purged_session_storage(
- state: &AdminState,
- workspace_id: WorkspaceId,
- project_id: ProjectId,
- removed_paths: &[PagePath],
-) -> (Vec<PagePath>, Vec<PagePath>) {
- let mut files_deleted = Vec::with_capacity(removed_paths.len());
- let mut files_failed = Vec::new();
-
- for path in removed_paths {
- match state
- .wiki
- .remove_page_file(workspace_id, project_id, path)
- .await
- {
- Ok(true) => files_deleted.push(path.clone()),
- Ok(false) => {}
- Err(error) => {
- warn!(
- operation = "purge-session",
- path = path.as_str(),
- error = %error,
- "session purge failed to remove wiki page file"
- );
- files_failed.push(path.clone());
- }
- }
- }
-
- (files_deleted, files_failed)
-}
-
/// `POST /admin/purge-session` — delete one session and everything derived
/// from it, inside a single workspace/project scope.
async fn handle_purge_session(
@@ -3698,8 +3666,8 @@ async fn handle_purge_session(
ai_memory_store::Compaction::Skip
};
- let summary = match state
- .writer
+ let outcome = match state
+ .wiki
.purge_session(ws_id, proj_id, session_id, author_id, compaction)
.await
{
@@ -3714,8 +3682,11 @@ async fn handle_purge_session(
Err(e) => return internal_err(e.to_string()),
};
- let (files_deleted, files_failed) =
- remove_purged_session_storage(&state, ws_id, proj_id, &summary.removed_paths).await;
+ let ai_memory_wiki::PurgeSessionOutcome {
+ summary,
+ files_deleted,
+ files_failed,
+ } = outcome;
if !files_failed.is_empty()
&& let Some(ref mut ctx) = dispatch_ctx
{
diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rs
index 7321a21d..3a3978c0 100644
--- a/crates/ai-memory-wiki/src/lib.rs
+++ b/crates/ai-memory-wiki/src/lib.rs
@@ -26,7 +26,7 @@ pub use git::{COMMIT_AUTHOR_EMAIL, COMMIT_AUTHOR_NAME, GitAdapter};
pub use markdown::{Markdown, derive_title, emit, parse};
pub use migrations::run_pending as run_wiki_migrations;
pub use watcher::{DEBOUNCE_WINDOW, RECONCILE_INTERVAL, WatcherHandle};
-pub use wiki::{MoveSessionOutcome, SessionPageFile, Wiki, WritePageRequest};
+pub use wiki::{MoveSessionOutcome, PurgeSessionOutcome, SessionPageFile, Wiki, WritePageRequest};
// Integration tests compile into this crate's test harness instead of a
// separate binary: every test binary is another link and, on macOS and
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index 85ab938b..f0519503 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -22,6 +22,16 @@ use crate::git::{Checkpoint, GitAdapter};
use crate::markdown::{Markdown, derive_title, emit, parse};
use crate::watcher::is_pending_path;
+/// Store deletion and best-effort file cleanup from [`Wiki::purge_session`].
+pub struct PurgeSessionOutcome {
+ /// Committed database deletion counts and paths.
+ pub summary: ai_memory_store::PurgeSessionSummary,
+ /// Paths successfully removed from disk.
+ pub files_deleted: Vec<PagePath>,
+ /// Paths whose file cleanup failed after the database committed.
+ pub files_failed: Vec<PagePath>,
+}
+
/// Summary of a [`Wiki::reindex_all`] run.
#[derive(Debug, Default, Clone)]
pub struct ReindexSummary {
@@ -1206,30 +1216,49 @@ impl Wiki {
}
}
- /// Remove one on-disk page file without touching the store.
- ///
- /// Used after a scoped store purge has already deleted the authoritative
- /// rows and returned the affected paths. A missing file is treated as
- /// already removed; any other filesystem error is reported to the caller.
+ /// Purge a session and its page files under one exclusive mutation guard.
+ /// Admission must run before this call. File failures do not roll back the
+ /// committed database purge and are returned for partial-failure reporting.
+ /// Holding the guard before submitting SQL prevents a watcher reindex,
+ /// page write or project move from landing between SQL and file cleanup.
///
/// # Errors
- /// Returns [`WikiError::Io`] on filesystem errors other than NotFound.
- pub async fn remove_page_file(
+ /// Returns the store error without removing files if the database purge fails.
+ pub async fn purge_session(
&self,
workspace_id: WorkspaceId,
project_id: ProjectId,
- path: &PagePath,
- ) -> WikiResult<bool> {
+ session_id: SessionId,
+ author_id: Option<UserId>,
+ compaction: ai_memory_store::Compaction,
+ ) -> ai_memory_store::StoreResult<PurgeSessionOutcome> {
let _guard = self.mutation_lock.write().await;
- let abs = self.abs_path(workspace_id, project_id, path);
- match self.git.remove_file(&abs) {
- Ok(()) => {
- sync_parent_best_effort(&abs);
- Ok(true)
+ let summary = self
+ .writer
+ .purge_session(workspace_id, project_id, session_id, author_id, compaction)
+ .await?;
+ let mut files_deleted = Vec::new();
+ let mut files_failed = Vec::new();
+ for path in &summary.removed_paths {
+ let abs = self.abs_path(workspace_id, project_id, path);
+ match self.git.remove_file(&abs) {
+ Ok(()) => {
+ sync_parent_best_effort(&abs);
+ files_deleted.push(path.clone());
+ }
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+ Err(error) => {
+ tracing::warn!(operation = "purge-session", path = path.as_str(),
+ error = %error, "session purge failed to remove wiki page file");
+ files_failed.push(path.clone());
+ }
}
- Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(false),
- Err(e) => Err(crate::WikiError::Io(e)),
}
+ Ok(PurgeSessionOutcome {
+ summary,
+ files_deleted,
+ files_failed,
+ })
}
/// Dispatch non-blocking purge webhooks after the caller's purge has
@@ -5133,6 +5162,90 @@ mod tests {
(store, wiki, ws, src, dst, sid, path)
}
+ #[tokio::test]
+ async fn purge_session_waits_for_in_flight_reindex_before_deleting_rows() {
+ let tmp = TempDir::new().unwrap();
+ let (store, wiki, ws, proj, _, sid, path) = session_with_page(&tmp).await;
+ let page_id = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
+ store.writer.end_session(sid, Some(page_id)).await.unwrap();
+
+ // Model a watcher that has acquired the shared guard but has not
+ // indexed its file yet. Poll the purge once, then fence the writer
+ // queue: any SQL it submitted must finish before this command replies.
+ let reader_guard = wiki.mutation_lock.read().await;
+ let purge = wiki.purge_session(ws, proj, sid, None, ai_memory_store::Compaction::Skip);
+ tokio::pin!(purge);
+ tokio::select! {
+ biased;
+ result = &mut purge => panic!("purge bypassed an active reader: {}", result.is_ok()),
+ () = std::future::ready(()) => {}
+ }
+ store
+ .writer
+ .get_or_create_workspace("queue-fence")
+ .await
+ .unwrap();
+ assert!(
+ store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_some(),
+ "purge must wait for the wiki guard before deleting SQL rows"
+ );
+ // Finish the already-admitted reindex without recursively locking.
+ wiki.reindex_page_locked(ws, proj, path.clone())
+ .await
+ .unwrap();
+ drop(reader_guard);
+ let outcome = purge.await.unwrap();
+ assert_eq!(outcome.files_deleted, vec![path.clone()]);
+ assert!(outcome.files_failed.is_empty());
+ assert!(
+ store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert!(!wiki.abs_path(ws, proj, &path).exists());
+ assert!(wiki.reindex_page(ws, proj, path).await.is_err());
+ assert!(
+ store
+ .reader
+ .search_pages("consolidated".into(), 10)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ }
+
+ #[tokio::test]
+ async fn purge_session_store_failure_preserves_page_file() {
+ let tmp = TempDir::new().unwrap();
+ let (store, wiki, ws, proj, other, sid, path) = session_with_page(&tmp).await;
+ let abs = wiki.abs_path(ws, proj, &path);
+ let before = std::fs::read(&abs).unwrap();
+ let result = wiki
+ .purge_session(ws, other, sid, None, ai_memory_store::Compaction::Skip)
+ .await;
+ assert!(matches!(
+ result,
+ Err(ai_memory_store::StoreError::NotFound(_))
+ ));
+ assert_eq!(std::fs::read(&abs).unwrap(), before);
+ assert!(
+ store
+ .reader
+ .find_session_scope(sid)
+ .await
+ .unwrap()
+ .is_some()
+ );
+ }
+
fn leftover_tempfiles(dir: &Path) -> Vec<String> {
std::fs::read_dir(dir)
.map(|rd| {
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index a800b7da..f6ac7d27 100644
--- a/docs/lifecycle-ops.md
+++ b/docs/lifecycle-ops.md
@@ -89,6 +89,13 @@ purge needs. Rebuilding only the indexes a given caller "should" have touched
is what leaves a managed agent's transcript text in the file after an operator
asked for it to be reclaimed.
+Session purges hold the wiki mutation guard across the database deletion and
+file cleanup. In-flight page writes and watcher reindexes finish before the
+purge starts; new ones wait until cleanup completes. This also serializes the
+purge with wiki project/session moves. Admission webhooks run before this guard.
+File cleanup failures still leave the database purge committed and are reported
+in `files_failed`; this coordination does not provide crash-atomic rollback.
+
### Scope containment
The session id is never authority on its own. Every statement is filtered on