Skip to content

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

Rust

bootstrap: serialise parallel runs + better connect-refused error

AkitaOnRails6fae4fe92045
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 5e795aa9..b7aef6e9 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -185,6 +185,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
data_dir: config.data_dir.clone(),
db_path: store.db_path().to_path_buf(),
bind: bind.clone(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
});
// Build the auth state. Precedence (highest first):
// 1. AI_MEMORY_AUTH_TOKEN env var
diff --git a/crates/ai-memory-cli/src/http_client.rs b/crates/ai-memory-cli/src/http_client.rs
index 442c5d9a..9addbd3c 100644
--- a/crates/ai-memory-cli/src/http_client.rs
+++ b/crates/ai-memory-cli/src/http_client.rs
@@ -86,7 +86,7 @@ pub async fn get_json<T: DeserializeOwned>(
let resp = req
.send()
.await
- .with_context(|| format!("GET {url} (is the server running at {}?)", endpoint.url))?;
+ .map_err(|e| augment_connect_error(e, endpoint, &url))?;
let status = resp.status();
if !status.is_success() {
let body = resp.text().await.unwrap_or_default();
@@ -112,7 +112,7 @@ pub async fn post_json<B: Serialize, T: DeserializeOwned>(
let resp = req
.send()
.await
- .with_context(|| format!("POST {url} (is the server running at {}?)", endpoint.url))?;
+ .map_err(|e| augment_connect_error(e, endpoint, &url))?;
let status = resp.status();
if !status.is_success() {
let body = resp.text().await.unwrap_or_default();
@@ -123,6 +123,60 @@ pub async fn post_json<B: Serialize, T: DeserializeOwned>(
.with_context(|| format!("parsing JSON body from POST {url}"))
}
+/// Turn a low-level reqwest connect/timeout error into a friendlier
+/// message that surfaces the env-var configuration. The common case
+/// is "Connection refused" — typically because `AI_MEMORY_SERVER_URL`
+/// is unset and the CLI defaulted to loopback on a host that has no
+/// local server running.
+fn augment_connect_error(
+ err: reqwest::Error,
+ endpoint: &ServerEndpoint,
+ url: &str,
+) -> anyhow::Error {
+ // Walk the source chain to see if there's a Connection-refused
+ // io::Error buried somewhere. reqwest wraps its errors deeply.
+ let chain_contains_refused = {
+ let mut src: Option<&dyn std::error::Error> = Some(&err);
+ let mut found = false;
+ while let Some(e) = src {
+ if e.to_string().contains("Connection refused")
+ || e.to_string().contains("connection refused")
+ {
+ found = true;
+ break;
+ }
+ src = e.source();
+ }
+ found
+ };
+
+ let url_from_env = std::env::var("AI_MEMORY_SERVER_URL").is_ok_and(|v| !v.is_empty());
+
+ if chain_contains_refused {
+ let hint = if url_from_env {
+ format!(
+ "\nAI_MEMORY_SERVER_URL is set to {} but nothing answered. \
+ Check the server is running, the port is reachable from \
+ this host, and (if remote) any firewall + bearer-token \
+ config matches.",
+ endpoint.url
+ )
+ } else {
+ format!(
+ "\nAI_MEMORY_SERVER_URL is NOT set; the CLI defaulted to \
+ {} and nothing answered. If your server lives on another \
+ machine (e.g. a homelab), `export AI_MEMORY_SERVER_URL=\
+ http://<server>:49374` and (if auth is on) \
+ `export AI_MEMORY_AUTH_TOKEN=<token>` before re-running.",
+ endpoint.url
+ )
+ };
+ anyhow::Error::new(err).context(format!("could not reach {url}.{hint}"))
+ } else {
+ anyhow::Error::new(err).context(format!("HTTP request to {url} failed"))
+ }
+}
+
/// POST an empty body to `<endpoint>{path}`, return the raw response bytes.
///
/// Intended for routes whose response is binary (e.g. `POST /admin/backup`
@@ -139,7 +193,7 @@ pub async fn post_bytes(endpoint: &ServerEndpoint, path: &str) -> Result<Vec<u8>
let resp = req
.send()
.await
- .with_context(|| format!("POST {url} (is the server running at {}?)", endpoint.url))?;
+ .map_err(|e| augment_connect_error(e, endpoint, &url))?;
let status = resp.status();
if !status.is_success() {
let body = resp.text().await.unwrap_or_default();
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 62ea602d..b5258464 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -66,6 +66,13 @@ pub struct AdminState {
pub db_path: PathBuf,
/// Server's bind address — informational, surfaced in /admin/status.
pub bind: String,
+ /// Serialises concurrent bootstrap requests. Bootstrap fans out
+ /// into an LLM call + a multi-page wiki write + a git commit;
+ /// running two in parallel would race the `commit_all` git ops and
+ /// stack LLM cost unnecessarily. The mutex is held for the entire
+ /// handler so a second caller waits its turn (request stays open
+ /// until the lock is acquired, then proceeds normally).
+ pub bootstrap_lock: Arc<tokio::sync::Mutex<()>>,
}
/// JSON request body for `POST /admin/bootstrap`.
@@ -368,15 +375,40 @@ async fn handle_bootstrap(
));
}
- // Resolve workspace + project — create if absent.
+ // Resolve workspace + project — create if absent. This is cheap;
+ // do it BEFORE acquiring the mutex so the get-or-create race is
+ // serialised by the writer actor (not gated on bootstrap-running).
let (ws, proj) = resolve_ws_proj(&state, &req.workspace, &req.project).await?;
- // Dry-run with no LLM: compute the budget-pruned source counts and
- // return early without constructing Bootstrap (which requires an LLM).
+ // Dry-run is read-only (no LLM call, no git commit), so it can
+ // proceed in parallel with anything else.
if req.dry_run && state.llm.is_none() {
return dry_run_outcome(req.sources, req.max_input_tokens);
}
+ // Serialise live bootstrap runs. Two parallel `process_sources`
+ // calls would race the wiki's `commit_all` (libgit2 ops on the
+ // same repo) and stack LLM cost unnecessarily. The wait is
+ // operator-visible only in log lines; the request stays open
+ // until the lock is acquired, then proceeds normally.
+ if !req.dry_run {
+ if let Ok(guard) = state.bootstrap_lock.try_lock() {
+ // Fast path: nobody else was bootstrapping, lock acquired
+ // immediately. Drop straight through.
+ drop(guard);
+ } else {
+ info!(
+ "another bootstrap is in progress; queueing — \
+ this request waits for the active one to finish"
+ );
+ }
+ }
+ let _bootstrap_guard = if req.dry_run {
+ None
+ } else {
+ Some(state.bootstrap_lock.lock().await)
+ };
+
let llm = Arc::clone(
state
.llm
diff --git a/crates/ai-memory-mcp/tests/admin_backup.rs b/crates/ai-memory-mcp/tests/admin_backup.rs
index fa72d48d..39a4d35f 100644
--- a/crates/ai-memory-mcp/tests/admin_backup.rs
+++ b/crates/ai-memory-mcp/tests/admin_backup.rs
@@ -33,6 +33,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
};
(state, store)
}
diff --git a/crates/ai-memory-mcp/tests/admin_bootstrap.rs b/crates/ai-memory-mcp/tests/admin_bootstrap.rs
index 1562cf62..5911385f 100644
--- a/crates/ai-memory-mcp/tests/admin_bootstrap.rs
+++ b/crates/ai-memory-mcp/tests/admin_bootstrap.rs
@@ -30,6 +30,7 @@ async fn make_admin_state(tmp: &TempDir) -> AdminState {
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
}
}
diff --git a/crates/ai-memory-mcp/tests/admin_phase3.rs b/crates/ai-memory-mcp/tests/admin_phase3.rs
index b4a34999..790f3f03 100644
--- a/crates/ai-memory-mcp/tests/admin_phase3.rs
+++ b/crates/ai-memory-mcp/tests/admin_phase3.rs
@@ -39,6 +39,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
};
(state, store)
}
diff --git a/crates/ai-memory-mcp/tests/admin_purge.rs b/crates/ai-memory-mcp/tests/admin_purge.rs
index 80e49872..1cdbeb86 100644
--- a/crates/ai-memory-mcp/tests/admin_purge.rs
+++ b/crates/ai-memory-mcp/tests/admin_purge.rs
@@ -34,6 +34,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
decay_params: DecayParams::default(),
data_dir: tmp.path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
db_path,
};
(state, store)
@@ -342,6 +343,7 @@ async fn purge_project_idempotent_second_call_is_404() {
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
};
seed_two_projects(&store, &state_a.wiki).await;
diff --git a/crates/ai-memory-mcp/tests/admin_rename.rs b/crates/ai-memory-mcp/tests/admin_rename.rs
index eac88766..809cf334 100644
--- a/crates/ai-memory-mcp/tests/admin_rename.rs
+++ b/crates/ai-memory-mcp/tests/admin_rename.rs
@@ -32,6 +32,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
};
(state, store)
}
@@ -309,6 +310,7 @@ async fn rename_project_pages_still_searchable() {
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
};
let rename_resp = post(
diff --git a/crates/ai-memory-mcp/tests/admin_status_search.rs b/crates/ai-memory-mcp/tests/admin_status_search.rs
index 5405ce87..c5108b03 100644
--- a/crates/ai-memory-mcp/tests/admin_status_search.rs
+++ b/crates/ai-memory-mcp/tests/admin_status_search.rs
@@ -27,6 +27,7 @@ async fn make_admin_state(tmp: &TempDir) -> (AdminState, Store) {
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:49374".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
};
(state, store)
}
diff --git a/crates/ai-memory-mcp/tests/admin_write_page.rs b/crates/ai-memory-mcp/tests/admin_write_page.rs
index f25e96f5..027a7be8 100644
--- a/crates/ai-memory-mcp/tests/admin_write_page.rs
+++ b/crates/ai-memory-mcp/tests/admin_write_page.rs
@@ -27,6 +27,7 @@ async fn make_state(tmp: &TempDir) -> AdminState {
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),
}
}