Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(serve): guard the data dir with a single-instance lock (#563)
Atirna13ab1285022c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 095d853f..f05ea731 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -48,6 +48,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0deliberate well-formed operator queries are preserved as before. Found bythe new LongMemEval retrieval harness on its first full run.+- `ai-memory serve` now takes an exclusive lock on `<data-dir>/.serve.lock`+ before opening the store, so a second server pointed at the same data+ directory refuses at startup and names the holding process instead of+ silently contending the single-writer actor, the wiki git handle, and the+ active-project pointer. The OS releases the lock when the process exits,+ so a crashed server never leaves the operator locked out; `--force` starts+ unguarded for an operator who knows the previous server is gone, and a+ filesystem that cannot lock at all downgrades the guard to a warning+ instead of refusing to start. (#563)+## [1.39.0] - 2026-09-01### Addeddiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 9eb746ea..ed613b04 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -2132,6 +2132,14 @@ pub struct ServeArgs {/// Skip the filesystem watcher; useful for transient debugging.#[arg(long)]pub no_watcher: bool,+ /// DANGEROUS: start even when another process holds the single-instance+ /// serve lock.+ ///+ /// Only for an operator who is certain the previous server is gone (a+ /// hung holder, or a mount with unreliable locking): two live servers on+ /// one data directory corrupt wiki and index state.+ #[arg(long)]+ pub force: bool,/// Workspace name (auto-created).////// Not marker-aware, unlike the client commands: the server has nodiff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rsindex c792f4bc..cd74e2d5 100644--- a/crates/ai-memory-cli/src/commands/hook_spool.rs+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs@@ -331,7 +331,7 @@ pub struct DrainLock {#[cfg(windows)]const ERROR_LOCK_VIOLATION: i32 = 33;-fn is_drain_lock_busy_error(err: &std::io::Error) -> bool {+pub(crate) fn is_drain_lock_busy_error(err: &std::io::Error) -> bool {if err.kind() == std::io::ErrorKind::WouldBlock {return true;}diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex bbcd9e52..7db80ddb 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -1,6 +1,7 @@//! `ai-memory serve` — MCP server with optional filesystem watcher.use std::future::Future;+use std::io::Write as _;use std::net::SocketAddr;use std::path::Path;use std::sync::Arc;@@ -67,6 +68,80 @@ const SESSION_CONSOLIDATION_POLL_INTERVAL: Duration = Duration::from_secs(15);/// requests are expected to finish well inside this lease.const SESSION_CONSOLIDATION_LEASE: Duration = Duration::from_secs(10 * 60);+/// Lock file guarding a data dir against a second `ai-memory serve` (#563).+const SERVE_LOCK_FILE: &str = ".serve.lock";++/// The single-instance guard for `ai-memory serve`: an exclusive `flock` on+/// `<data-dir>/.serve.lock` held for the process lifetime. The OS releases it+/// when the process exits, so a crashed server never locks the operator out of+/// their own data.+#[derive(Debug)]+struct ServeLock {+ _file: std::fs::File,+}++/// Take the single-instance serve lock for `data_dir`.+///+/// A contended lock refuses startup naming the holder, unless `force` is set:+/// the operator who knows the previous server is gone (a hung holder, or a+/// mount with unreliable locking) must not be stranded. A filesystem that+/// cannot lock at all only downgrades the guard to a warning — refusing to+/// start there would be worse than the unguarded risk.+fn acquire_serve_lock(data_dir: &Path, force: bool) -> Result<Option<ServeLock>> {+ std::fs::create_dir_all(data_dir)+ .with_context(|| format!("creating data directory {}", data_dir.display()))?;+ let path = data_dir.join(SERVE_LOCK_FILE);+ let mut file = std::fs::OpenOptions::new()+ .create(true)+ .truncate(false)+ .read(true)+ .write(true)+ .open(&path)+ .with_context(|| format!("opening serve lock {}", path.display()))?;+ use fs2::FileExt as _;+ match file.try_lock_exclusive() {+ Ok(()) => {+ // Informational only: the flock is the guard, and this line names+ // the holder in a later refusal message. Best-effort.+ let _ = file+ .set_len(0)+ .and_then(|()| file.write_all(format!("pid={}\n", std::process::id()).as_bytes()));+ tracing::info!(lock = %path.display(), "single-instance serve lock held");+ Ok(Some(ServeLock { _file: file }))+ }+ Err(err) if crate::commands::hook_spool::is_drain_lock_busy_error(&err) => {+ let holder = std::fs::read_to_string(&path)+ .map(|text| text.trim().to_string())+ .unwrap_or_default();+ if force {+ tracing::warn!(+ lock = %path.display(),+ holder = %holder,+ "another process holds the serve lock; continuing unguarded per --force"+ );+ return Ok(None);+ }+ anyhow::bail!(+ "another ai-memory serve process appears to be using {} ({}); two servers on one data directory corrupt wiki and index state — stop the other process, or pass --force if you are certain it is gone",+ data_dir.display(),+ if holder.is_empty() {+ "holder unknown".to_owned()+ } else {+ holder+ },+ )+ }+ Err(err) => {+ tracing::warn!(+ lock = %path.display(),+ error = %err,+ "cannot lock the data directory; running without the single-instance guard"+ );+ Ok(None)+ }+ }+}+fn validate_api_credential_pepper(api_credentials_exist: bool, auth: &AuthSettings) -> Result<()> {let pepper_present = auth.token_pepper@@ -629,6 +704,11 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {let cors_origins = merge_cors_origins(&config.cors_allow_origins, &args.cors_allow_origin);validate_cors_origins(&cors_origins)?;+ // Guard the data dir before anything opens it: a second serve process+ // means a second writer actor, a second git handle on the wiki, and a+ // second active-project pointer (#563). Held until `run` returns.+ let _serve_lock = acquire_serve_lock(&config.data_dir, args.force)?;+let store = Store::open(&config.data_dir).with_context(|| format!("opening store at {}", config.data_dir.display()))?;@@ -1988,6 +2068,44 @@ mod tests {}}+ #[test]+ fn second_server_on_the_same_data_dir_is_refused_and_names_the_holder() {+ let dir = TempDir::new().unwrap();+ let first = acquire_serve_lock(dir.path(), false).unwrap();+ assert!(first.is_some());+ let err = acquire_serve_lock(dir.path(), false)+ .unwrap_err()+ .to_string();+ assert!(+ err.contains("--force"),+ "refusal must name the override: {err}"+ );+ assert!(+ err.contains(&format!("pid={}", std::process::id())),+ "refusal must name the holding process: {err}"+ );+ }++ #[test]+ fn force_starts_unguarded_while_the_holder_keeps_the_lock() {+ let dir = TempDir::new().unwrap();+ let _first = acquire_serve_lock(dir.path(), false).unwrap();+ assert!(acquire_serve_lock(dir.path(), true).unwrap().is_none());+ // --force bypasses the refusal, not the holder: a plain attempt still sees it.+ assert!(acquire_serve_lock(dir.path(), false).is_err());+ }++ #[test]+ fn a_released_serve_lock_does_not_lock_out_the_next_server() {+ let dir = TempDir::new().unwrap();+ {+ let _first = acquire_serve_lock(dir.path(), false).unwrap();+ // Dropping the holder is what process exit does to the flock: the+ // leftover .serve.lock file must not outlive the lock it named.+ }+ assert!(acquire_serve_lock(dir.path(), false).unwrap().is_some());+ }+#[test]fn existing_users_require_nonempty_pepper_and_root_bearer() {for users_exist in [false, true] {