Skip to content

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

Rust

fix(setup): distinguish foreign listeners from healthy servers

Samir Hanna Verzaf6c4e7fc67d6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c6a02aca..a1331e0e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,11 @@ version in [`docs/changelog/`](docs/changelog/):
### Fixed
+- Fixed `ai-memory setup` treating another service's HTTP 200 response as a
+ healthy ai-memory server. Setup now checks the bounded `/healthz` JSON,
+ reports an occupied address with port/configuration remedies, and skips
+ MCP/admin probes when the health response is unrecognized (#1647).
+
- `ai-memory user list` and `ai-memory api-key list` now size their columns
by terminal display width rather than bytes, as `list-projects` and the
grants tables already do. An accented username, display name or key label
diff --git a/crates/ai-memory-cli/src/commands/setup.rs b/crates/ai-memory-cli/src/commands/setup.rs
index 7abe8167..4f3a4c27 100644
--- a/crates/ai-memory-cli/src/commands/setup.rs
+++ b/crates/ai-memory-cli/src/commands/setup.rs
@@ -92,6 +92,13 @@ enum ServicePlan {
Skip(String),
}
+#[derive(Debug)]
+enum SetupProbe {
+ Healthy,
+ Unreachable(String),
+ Unexpected(String),
+}
+
#[derive(Debug, Clone, PartialEq, Eq)]
struct AgentPlan {
agent: AgentChoice,
@@ -262,15 +269,13 @@ pub async fn run(config: &Config, args: SetupArgs, config_path: Option<&Path>) -
home: home.clone(),
xdg_config_home: env("XDG_CONFIG_HOME").map(PathBuf::from),
};
- let reachable = matches!(
- probe_server(&ServerEndpoint::from_config_resolving_auth(config).await).await,
- ServerProbe::Reachable
- );
+ let probe =
+ probe_setup_server(&ServerEndpoint::from_config_resolving_auth(config).await).await;
plan_service(
ServiceManager::current(),
&spec,
&config.server_url,
- reachable,
+ &probe,
&user_service::SystemRunner,
)
};
@@ -498,14 +503,15 @@ fn homebrew_links(resolved: &Path) -> Vec<PathBuf> {
]
}
-/// Decide the service step. A server already answering with no unit of ours
+/// Decide the service step. An ai-memory server answering with no unit of ours
/// in place is left in charge (Docker, a packaged unit, a foreground
-/// `serve`): a second server could not bind the port anyway.
+/// `serve`). An unrecognized listener also prevents a bind, but needs an
+/// actionable diagnostic rather than being treated as our server.
fn plan_service(
manager: Option<ServiceManager>,
spec: &user_service::ServiceSpec,
server_url: &str,
- reachable: bool,
+ probe: &SetupProbe,
runner: &dyn CommandRunner,
) -> ServicePlan {
let Some(manager) = manager else {
@@ -520,11 +526,24 @@ fn plan_service(
"the configured server {server_url} is not on this machine; no local service"
));
}
+ if let SetupProbe::Unexpected(reason) = probe {
+ return ServicePlan::Skip(format!(
+ "{server_url} did not return ai-memory's /healthz JSON ({reason}); leaving the \
+ listener and any existing service unchanged. Check which process owns this address, \
+ then free it or set `bind = \"127.0.0.1:<free-port>\"` in {} and re-run \
+ `ai-memory setup` (update an explicit server_url too). OpenCode's background \
+ service also uses port 49374 by default; move it with \
+ `opencode service set port <free-port>` if it is the occupant.",
+ spec.config_path.display()
+ ));
+ }
match user_service::render(manager, spec) {
- Ok(unit) if reachable && !unit.exists(runner) => ServicePlan::Skip(format!(
- "a server already answers at {server_url}; leaving it in charge (pass --no-service \
+ Ok(unit) if matches!(probe, SetupProbe::Healthy) && !unit.exists(runner) => {
+ ServicePlan::Skip(format!(
+ "an ai-memory server already answers at {server_url}; leaving it in charge (pass --no-service \
to skip this check)"
- )),
+ ))
+ }
Ok(unit) => ServicePlan::Install(unit),
Err(error) => ServicePlan::Skip(format!("cannot render the service: {error:#}")),
}
@@ -1056,19 +1075,20 @@ fn wire_mcp_and_hooks(
async fn self_check(config: &Config, endpoint: &ServerEndpoint) -> Vec<String> {
let mut problems = Vec::new();
let healthz = endpoint.build_url("/healthz");
- match reqwest::Client::new()
- .get(&healthz)
- .timeout(Duration::from_secs(5))
- .send()
- .await
- {
- Ok(response) if response.status().is_success() => println!("healthz: ok ({healthz})"),
- Ok(response) => problems.push(format!("{healthz} answered {}", response.status())),
- Err(error) => {
+ match probe_setup_server(endpoint).await {
+ SetupProbe::Healthy => println!("healthz: ok ({healthz})"),
+ SetupProbe::Unreachable(error) => {
problems.push(format!("{healthz} did not answer: {error}"));
// Nothing else can pass without a server.
return problems;
}
+ SetupProbe::Unexpected(reason) => {
+ problems.push(format!(
+ "{healthz} did not return ai-memory's /healthz JSON ({reason}); check the \
+ configured server URL and the process listening there"
+ ));
+ return problems;
+ }
}
match memory_status(config).await {
Ok(()) => println!("memory_status: ok"),
@@ -1086,6 +1106,55 @@ async fn self_check(config: &Config, endpoint: &ServerEndpoint) -> Vec<String> {
problems
}
+/// Setup needs the health response before it can leave an existing server
+/// in charge or report success. The shared launch probe remains presence-only
+/// for compatibility with servers that predate `/healthz`.
+async fn probe_setup_server(endpoint: &ServerEndpoint) -> SetupProbe {
+ let response = reqwest::Client::new()
+ .get(endpoint.build_url("/healthz"))
+ .timeout(Duration::from_secs(5))
+ .send()
+ .await;
+ let response = match response {
+ Ok(response) => response,
+ Err(error) => return SetupProbe::Unreachable(error.to_string()),
+ };
+ match validate_healthz(response).await {
+ Ok(()) => SetupProbe::Healthy,
+ Err(reason) => SetupProbe::Unexpected(reason),
+ }
+}
+
+async fn validate_healthz(mut response: reqwest::Response) -> Result<(), String> {
+ if !response.status().is_success() {
+ return Err(format!("HTTP {}", response.status()));
+ }
+ if !response
+ .headers()
+ .get(reqwest::header::CONTENT_TYPE)
+ .and_then(|value| value.to_str().ok())
+ .and_then(|value| value.split(';').next())
+ .is_some_and(|mime| mime.trim().eq_ignore_ascii_case("application/json"))
+ {
+ return Err("expected Content-Type application/json".to_owned());
+ }
+ // A foreign listener can return a whole page (or a stream). Bound its
+ // body and never echo it into the terminal.
+ let mut body = Vec::new();
+ while let Some(chunk) = response.chunk().await.map_err(|error| error.to_string())? {
+ if body.len() + chunk.len() > 1024 {
+ return Err("health response exceeds 1024 bytes".to_owned());
+ }
+ body.extend_from_slice(&chunk);
+ }
+ if serde_json::from_slice::<serde_json::Value>(&body).is_ok_and(|value| value["status"] == "ok")
+ {
+ Ok(())
+ } else {
+ Err("expected JSON with status \"ok\"".to_owned())
+ }
+}
+
/// One `memory_status` call over the server's MCP endpoint, authenticated the
/// way `mcp-bridge` authenticates, so a refused credential shows here rather
/// than in the agent's first session.
@@ -1666,7 +1735,7 @@ mod tests {
None,
&spec(tmp.path()),
"http://127.0.0.1:49374",
- false,
+ &SetupProbe::Unreachable(String::new()),
&user_service::SystemRunner,
) else {
panic!("expected a skip");
@@ -1702,11 +1771,11 @@ mod tests {
..spec(tmp.path())
};
assert!(matches!(
- plan_service(manager, &spec, url, false, &Reg(None)),
+ plan_service(manager, &spec, url, &SetupProbe::Unreachable(String::new()), &Reg(None)),
ServicePlan::Install(unit) if unit.manager == ServiceManager::WindowsRun
));
assert!(matches!(
- plan_service(manager, &spec, url, true, &Reg(None)),
+ plan_service(manager, &spec, url, &SetupProbe::Healthy, &Reg(None)),
ServicePlan::Skip(reason) if reason.contains("already answers")
));
assert!(matches!(
@@ -1714,7 +1783,7 @@ mod tests {
manager,
&spec,
url,
- true,
+ &SetupProbe::Healthy,
&Reg(Some("\"C:\\ai\\ai-memory.exe\" service-host"))
),
ServicePlan::Install(_)
@@ -1728,7 +1797,7 @@ mod tests {
Some(ServiceManager::SystemdUser),
&spec(tmp.path()),
"https://memory.example.com",
- true,
+ &SetupProbe::Healthy,
&user_service::SystemRunner,
);
assert!(
@@ -1750,7 +1819,7 @@ mod tests {
Some(ServiceManager::SystemdUser),
&spec,
url,
- true,
+ &SetupProbe::Healthy,
&user_service::SystemRunner,
);
assert!(matches!(plan, ServicePlan::Skip(reason) if reason.contains("already answers")));
@@ -1759,7 +1828,7 @@ mod tests {
Some(ServiceManager::SystemdUser),
&spec,
url,
- false,
+ &SetupProbe::Unreachable(String::new()),
&user_service::SystemRunner,
) else {
panic!("expected an install when nothing answers");
@@ -1771,10 +1840,114 @@ mod tests {
Some(ServiceManager::SystemdUser),
&spec,
url,
- true,
+ &SetupProbe::Healthy,
&user_service::SystemRunner
),
ServicePlan::Install(_)
));
}
+
+ #[tokio::test]
+ async fn setup_health_probe_requires_successful_bounded_json() {
+ use axum::http::StatusCode;
+
+ for (status, content_type, body, healthy) in [
+ (
+ StatusCode::OK,
+ "application/json",
+ r#"{"status":"ok"}"#.to_owned(),
+ true,
+ ),
+ (
+ StatusCode::OK,
+ "application/json; charset=utf-8",
+ r#"{"status":"ok","extra":1}"#.to_owned(),
+ true,
+ ),
+ (
+ StatusCode::OK,
+ "text/html",
+ r#"{"status":"ok"}"#.to_owned(),
+ false,
+ ),
+ (
+ StatusCode::OK,
+ "application/json",
+ "<!doctype html>".to_owned(),
+ false,
+ ),
+ (
+ StatusCode::OK,
+ "application/json",
+ r#"{"status":"down"}"#.to_owned(),
+ false,
+ ),
+ (
+ StatusCode::OK,
+ "application/json",
+ r#"{"other":"ok"}"#.to_owned(),
+ false,
+ ),
+ (StatusCode::OK, "application/json", " ".repeat(1025), false),
+ (
+ StatusCode::SERVICE_UNAVAILABLE,
+ "application/json",
+ r#"{"status":"ok"}"#.to_owned(),
+ false,
+ ),
+ ] {
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let app = axum::Router::new().route(
+ "/memory/healthz",
+ axum::routing::get(move || async move {
+ (
+ status,
+ [(axum::http::header::CONTENT_TYPE, content_type)],
+ body,
+ )
+ }),
+ );
+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+ let endpoint =
+ ServerEndpoint::from_pair(Some(format!("http://{address}/memory")), None);
+ let probe = probe_setup_server(&endpoint).await;
+ server.abort();
+ assert_eq!(
+ matches!(probe, SetupProbe::Healthy),
+ healthy,
+ "{status} {content_type}: {probe:?}"
+ );
+ if !healthy {
+ assert!(matches!(probe, SetupProbe::Unexpected(_)), "{probe:?}");
+ }
+ }
+ }
+
+ /// An unhealthy response still means the port is occupied. Do not
+ /// install a second service or restart an existing one over that listener.
+ #[cfg(unix)]
+ #[test]
+ fn an_unrecognized_listener_prevents_service_changes_even_with_an_existing_unit() {
+ let tmp = tempfile::tempdir().unwrap();
+ let spec = spec(tmp.path());
+ let unit = user_service::render(ServiceManager::SystemdUser, &spec).unwrap();
+ for existing in [false, true] {
+ if existing {
+ std::fs::create_dir_all(unit.path.parent().unwrap()).unwrap();
+ std::fs::write(&unit.path, &unit.contents).unwrap();
+ }
+ let plan = plan_service(
+ Some(ServiceManager::SystemdUser),
+ &spec,
+ "http://127.0.0.1:49374",
+ &SetupProbe::Unexpected("HTTP 503 Service Unavailable".to_owned()),
+ &user_service::SystemRunner,
+ );
+ assert!(
+ matches!(plan, ServicePlan::Skip(reason) if reason.contains("did not return ai-memory's /healthz"))
+ );
+ assert_eq!(unit.path.exists(), existing);
+ }
+ }
}
diff --git a/crates/ai-memory-cli/tests/suite/setup_e2e.rs b/crates/ai-memory-cli/tests/suite/setup_e2e.rs
index 81a243a0..b4989038 100644
--- a/crates/ai-memory-cli/tests/suite/setup_e2e.rs
+++ b/crates/ai-memory-cli/tests/suite/setup_e2e.rs
@@ -171,6 +171,74 @@ fn setup_plan_json_prints_the_plan_and_changes_nothing() {
assert_eq!(sandbox.snapshot(), before, "a refused setup wrote");
}
+/// An SPA can answer every unknown route with HTML and HTTP 200. It is not
+/// an existing ai-memory install, and its MCP/admin errors are not useful
+/// setup diagnostics.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn setup_identifies_a_foreign_listener_in_the_plan_and_self_check() {
+ let sandbox = Sandbox::new();
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let port = listener.local_addr().unwrap().port();
+ let paths = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+ let seen = paths.clone();
+ let app = axum::Router::new().fallback(move |uri: axum::http::Uri| {
+ seen.lock().unwrap().push(uri.path().to_owned());
+ async { axum::response::Html("<!doctype html><title>Another service</title>") }
+ });
+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+ let planned = sandbox
+ .cmd(Some(port))
+ .args(["setup", "--plan", "--json"])
+ .output()
+ .unwrap();
+ assert!(planned.status.success(), "{}", text(&planned));
+ let plan: serde_json::Value = serde_json::from_slice(&planned.stdout).unwrap();
+ assert_eq!(plan["service"]["action"], "skip", "{plan}");
+ let reason = plan["service"]["reason"].as_str().unwrap();
+ assert!(
+ reason.contains("did not return ai-memory's /healthz"),
+ "{reason}"
+ );
+ assert!(reason.contains(&format!("127.0.0.1:{port}")), "{reason}");
+ assert!(
+ reason.contains("config.toml") && reason.contains("bind"),
+ "{reason}"
+ );
+
+ let applied = sandbox
+ .cmd(Some(port))
+ .args(["setup", "--yes"])
+ .output()
+ .unwrap();
+ server.abort();
+ assert!(!applied.status.success(), "{}", text(&applied));
+ let stdout = String::from_utf8_lossy(&applied.stdout);
+ assert!(!stdout.contains("healthz: ok"), "{}", text(&applied));
+ assert!(
+ stdout.contains("did not return ai-memory's /healthz"),
+ "{}",
+ text(&applied)
+ );
+ assert!(
+ paths.lock().unwrap().iter().all(|path| path == "/healthz"),
+ "setup sent unrelated probes to the foreign listener: {:?}",
+ paths.lock().unwrap()
+ );
+ assert!(
+ !sandbox
+ .home
+ .join("Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist")
+ .exists()
+ );
+ assert!(
+ !sandbox
+ .home
+ .join(".config/systemd/user/ai-memory.service")
+ .exists()
+ );
+}
+
/// The generic `opencode` agent, named or found by the session store both
/// majors share, is wired in the major `opencode --version` reports: OpenCode
/// 2 gets the `{ id, setup }` plugin and the nested `mcp.servers` entry, not
diff --git a/docs/install.md b/docs/install.md
index 98c2b673..3118fda2 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -146,10 +146,17 @@ runs, in order, the commands a native install otherwise needs one by one:
and restarts it after a failure, giving up after five failures within ten
seconds of starting; see
[`docs/windows.md`](windows.md#scenario-e-keep-the-server-running-native-windows-service).
- The step is skipped when a server already answers at the configured
+ The step is skipped when an ai-memory server already answers at the configured
URL and no unit or logon entry of ours exists yet (Docker, a packaged system
unit, a foreground `serve`), when the configured server is not on this
- machine, and with `--no-service`.
+ machine, and with `--no-service`. Setup requires a successful
+ `application/json` response with `{"status":"ok"}` from `/healthz` before
+ treating a listener as healthy. An unrecognized response leaves any local
+ service unchanged and fails the self-check with a diagnostic. Check which
+ process owns the address, then free it or change `bind` in the named
+ `config.toml` and re-run setup; update an explicit `server_url` too.
+ OpenCode's background service also defaults to port 49374 and can be moved
+ with `opencode service set port <free-port>`.
3. For each agent: `install-mcp --apply`, `install-hooks --apply` and
`install-skills --scope global`. With no `--agent`, `setup` wires every
harness whose session store or MCP config exists under your home, using the