Skip to content

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.md
index 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.0
deliberate well-formed operator queries are preserved as before. Found by
the 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
### Added
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 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 no
diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rs
index 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.rs
index 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] {