Skip to content

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

Rust

fix(install-mcp): name the bridge binary by absolute path

Giovanni Campbell886decb0142d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 59954396..5c2f2125 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,15 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Fixed
+
+- `install-mcp` now writes the absolute path of the `ai-memory` binary as the
+ `command` of every stdio bridge entry (Claude Code's session-aware entry,
+ Muse Code and the session-less bridge of the other clients), as hook
+ commands already did. A client started without `~/.local/bin` on its `PATH`
+ no longer fails to spawn the bridge. The Docker wrapper keeps the bare
+ `ai-memory`, and existing entries with either form are still recognized.
+
## [3.1.0] - 2026-10-16
### Added
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index 132bd40f..9ca3a3b2 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -26,7 +26,9 @@ use serde_json::json;
use crate::cli::{InstallMcpArgs, McpClient, SchemaFlavor};
use crate::commands::apply_shared::{ApplyOutcome, apply_atomic, mutate_json, mutate_toml};
use crate::commands::path_util::{claude_config_dir, home_dir};
-use crate::commands::render_shared::{bearer_header_value, yaml_single_quote};
+use crate::commands::render_shared::{
+ bearer_header_value, hook_embedded_exe_path, shell_quote, yaml_single_quote,
+};
use crate::config::{Config, DEFAULT_MCP_URL};
const GEMINI_MCP_TIMEOUT_MS: u64 = 5000;
@@ -206,11 +208,42 @@ fn route_file_token(args: &mut InstallMcpArgs, token_file: &Path) -> Result<()>
Ok(())
}
-/// The command a stdio bridge entry runs. Resolved through `PATH` like the
-/// Claude Code entry, so the Docker wrapper (which intercepts `mcp-bridge`)
-/// and a native install both answer to it.
+/// The bare command name, resolved through `PATH`. Inside a container the
+/// Docker wrapper on the host intercepts `mcp-bridge`, so the entry must name
+/// the wrapper rather than the container's own binary.
const BRIDGE_COMMAND: &str = "ai-memory";
+/// The command a stdio bridge entry runs: this binary's absolute path, the
+/// same one hook commands embed, because clients often start MCP servers
+/// without the login shell's `PATH` and a bare `ai-memory` then fails to
+/// spawn. Inside a container, or when the path cannot be trusted to survive
+/// (see [`hook_embedded_exe_path`]), the bare [`BRIDGE_COMMAND`].
+fn bridge_command() -> String {
+ bridge_command_for(
+ ai_memory_wiki::backup::running_in_container(),
+ hook_embedded_exe_path(),
+ )
+}
+
+fn bridge_command_for(in_container: bool, exe: PathBuf) -> String {
+ if in_container {
+ BRIDGE_COMMAND.to_owned()
+ } else {
+ exe.to_string_lossy().into_owned()
+ }
+}
+
+/// Whether `command` runs ai-memory: the bare name, what [`bridge_command`]
+/// writes from this binary, or an absolute path to a binary named `ai-memory`
+/// that an earlier install wrote.
+fn is_bridge_command(command: &str) -> bool {
+ if command == BRIDGE_COMMAND || command == bridge_command() {
+ return true;
+ }
+ let path = Path::new(command);
+ path.is_absolute() && path.file_stem().and_then(|stem| stem.to_str()) == Some(BRIDGE_COMMAND)
+}
+
/// Arguments of the session-less bridge for `args`: the URL carries the
/// client's schema-flavor marker, because the bridge forwards `tools/list`
/// to it verbatim and the client is the one that needs the dialect.
@@ -224,12 +257,12 @@ fn session_less_bridge_args(args: &InstallMcpArgs) -> Vec<String> {
]
}
-/// The upstream URL of an ai-memory bridge entry: `command: "ai-memory"` with
+/// The upstream URL of an ai-memory bridge entry: an ai-memory `command` with
/// `args`, or OpenCode's single `command` array, running `mcp-bridge` with a
/// `--server-url`. `None` for any other entry.
pub(crate) fn bridge_entry_url(entry: &serde_json::Value) -> Option<&str> {
let argv: Vec<&str> = match entry.get("command")? {
- serde_json::Value::String(command) if command == BRIDGE_COMMAND => entry
+ serde_json::Value::String(command) if is_bridge_command(command) => entry
.get("args")?
.as_array()?
.iter()
@@ -237,7 +270,7 @@ pub(crate) fn bridge_entry_url(entry: &serde_json::Value) -> Option<&str> {
.collect(),
serde_json::Value::Array(command) => {
let mut words = command.iter().filter_map(serde_json::Value::as_str);
- if words.next() != Some(BRIDGE_COMMAND) {
+ if !words.next().is_some_and(is_bridge_command) {
return None;
}
words.collect()
@@ -340,10 +373,10 @@ pub(crate) fn existing_entry_endpoint(
/// take no stdio entry here.
fn stdio_bridge_entry(args: &InstallMcpArgs) -> Option<serde_json::Value> {
let bridge = session_less_bridge_args(args);
- let plain = || json!({"command": BRIDGE_COMMAND, "args": bridge.clone()});
- let typed =
- |kind: &str| json!({"type": kind, "command": BRIDGE_COMMAND, "args": bridge.clone()});
- let mut opencode_argv = vec![BRIDGE_COMMAND.to_owned()];
+ let command = bridge_command();
+ let plain = || json!({"command": command, "args": bridge.clone()});
+ let typed = |kind: &str| json!({"type": kind, "command": command, "args": bridge.clone()});
+ let mut opencode_argv = vec![command.clone()];
opencode_argv.extend(bridge.iter().cloned());
Some(match args.client {
McpClient::ClaudeDesktop
@@ -354,7 +387,7 @@ fn stdio_bridge_entry(args: &InstallMcpArgs) -> Option<serde_json::Value> {
| McpClient::Openclaw
| McpClient::IbmBob => plain(),
McpClient::GeminiCli | McpClient::AntigravityCli => json!({
- "command": BRIDGE_COMMAND,
+ "command": command,
"args": bridge,
"timeout": GEMINI_MCP_TIMEOUT_MS,
}),
@@ -363,20 +396,20 @@ fn stdio_bridge_entry(args: &InstallMcpArgs) -> Option<serde_json::Value> {
}
McpClient::Omp => json!({
"type": "stdio",
- "command": BRIDGE_COMMAND,
+ "command": command,
"args": bridge,
"enabled": true,
}),
McpClient::CopilotCli => json!({
"type": "local",
- "command": BRIDGE_COMMAND,
+ "command": command,
"args": bridge,
"tools": ["*"],
}),
McpClient::CommandCode => json!({
"transport": "stdio",
"enabled": true,
- "command": BRIDGE_COMMAND,
+ "command": command,
"args": bridge,
}),
McpClient::OpenCode => json!({"type": "local", "command": opencode_argv, "enabled": true}),
@@ -1541,7 +1574,7 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
McpClient::ClaudeCode => {
if args.session_aware {
entry.insert("type".into(), json!("stdio"));
- entry.insert("command".into(), json!("ai-memory"));
+ entry.insert("command".into(), json!(bridge_command()));
entry.insert(
"args".into(),
json!(["mcp-bridge", "--server-url", base_url]),
@@ -1804,7 +1837,7 @@ fn build_mcp_entry_muse(args: &InstallMcpArgs) -> Result<serde_json::Value> {
let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);
let mut entry = serde_json::Map::new();
entry.insert("type".into(), json!("stdio"));
- entry.insert("command".into(), json!(BRIDGE_COMMAND));
+ entry.insert("command".into(), json!(bridge_command()));
let mut argv = vec![
json!("mcp-bridge"),
json!("--agent"),
@@ -1952,7 +1985,7 @@ fn grok_upsert_mcp_server(
let mut server = Table::new();
if args.stdio_bridge {
// Grok picks stdio from `command` (and HTTP from `url`).
- server["command"] = value(BRIDGE_COMMAND);
+ server["command"] = value(bridge_command());
server["args"] = value(
session_less_bridge_args(args)
.iter()
@@ -2013,8 +2046,9 @@ fn render_claude_code(args: &InstallMcpArgs, config_path: &Path) -> Result<Strin
.map(|token| format!(" --env \"AI_MEMORY_AUTH_TOKEN={token}\""))
.unwrap_or_default();
format!(
- "claude mcp add --transport stdio{env} {name} -- \\\n ai-memory mcp-bridge --server-url {url}",
+ "claude mcp add --transport stdio{env} {name} -- \\\n {command} mcp-bridge --server-url {url}",
name = args.name,
+ command = shell_quote(&bridge_command()),
url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
)
} else if let Some(b) = &bearer {
@@ -2325,7 +2359,7 @@ fn render_dsh_snippet(args: &InstallMcpArgs) -> String {
out.push_str(" transport: stdio\n");
out.push_str(&format!(
" command: {}\n",
- yaml_single_quote(BRIDGE_COMMAND)
+ yaml_single_quote(&bridge_command())
));
out.push_str(" args:\n");
for arg in session_less_bridge_args(args) {
@@ -2768,7 +2802,7 @@ mod tests {
entry,
json!({
"type": "stdio",
- "command": "ai-memory",
+ "command": bridge_command(),
"args": ["mcp-bridge", "--agent", "muse", "--server-url", "http://127.0.0.1:49374/mcp"],
"mode": "optional",
})
@@ -3820,6 +3854,37 @@ mod tests {
);
}
+ #[test]
+ fn bridge_command_names_the_binary_by_absolute_path_outside_a_container() {
+ let exe = PathBuf::from("/opt/ai-memory/ai-memory");
+ assert_eq!(
+ bridge_command_for(false, exe.clone()),
+ "/opt/ai-memory/ai-memory"
+ );
+ assert_eq!(bridge_command_for(true, exe), BRIDGE_COMMAND);
+ }
+
+ #[test]
+ fn bridge_entries_are_recognized_by_bare_name_or_absolute_path() {
+ for command in ["ai-memory", "/opt/ai-memory/ai-memory"] {
+ let entry =
+ json!({"command": command, "args": ["mcp-bridge", "--server-url", "http://h/mcp"]});
+ assert_eq!(bridge_entry_url(&entry), Some("http://h/mcp"), "{command}");
+ let opencode =
+ json!({"command": [command, "mcp-bridge", "--server-url", "http://h/mcp"]});
+ assert_eq!(
+ bridge_entry_url(&opencode),
+ Some("http://h/mcp"),
+ "{command}"
+ );
+ }
+ for command in ["other", "/usr/bin/other", "bin/ai-memory"] {
+ let entry =
+ json!({"command": command, "args": ["mcp-bridge", "--server-url", "http://h/mcp"]});
+ assert_eq!(bridge_entry_url(&entry), None, "{command}");
+ }
+ }
+
#[test]
fn claude_code_session_aware_entry_uses_owned_stdio_bridge() {
let mut args = args_with_token(McpClient::ClaudeCode);
@@ -3829,7 +3894,7 @@ mod tests {
let entry = build_mcp_entry(&args).unwrap();
assert_eq!(entry["type"], "stdio");
- assert_eq!(entry["command"], "ai-memory");
+ assert_eq!(entry["command"], bridge_command());
assert_eq!(
entry["args"],
json!(["mcp-bridge", "--server-url", "https://memory.example/mcp"])
@@ -3840,7 +3905,10 @@ mod tests {
let rendered = render_claude_code(&args, Path::new("/home/alice/.claude.json")).unwrap();
assert!(rendered.contains("claude mcp add --transport stdio"));
- assert!(rendered.contains("ai-memory mcp-bridge --server-url"));
+ assert!(rendered.contains(&format!(
+ "{} mcp-bridge --server-url",
+ shell_quote(&bridge_command())
+ )));
}
#[test]
@@ -4145,7 +4213,7 @@ mod tests {
};
let opencode = entry(McpClient::OpenCode);
assert_eq!(opencode["type"], "local");
- assert_eq!(opencode["command"][0], "ai-memory");
+ assert_eq!(opencode["command"][0], bridge_command());
assert_eq!(opencode["command"][1], "mcp-bridge");
assert_eq!(opencode["enabled"], true);
assert!(entry(McpClient::OpenCode2).get("enabled").is_none());
@@ -4165,7 +4233,10 @@ mod tests {
let mut doc = toml_edit::DocumentMut::new();
grok_upsert_mcp_server(&mut doc, &grok).unwrap();
let text = doc.to_string();
- assert!(text.contains("command = \"ai-memory\""), "{text}");
+ assert!(
+ text.contains(&format!("command = {:?}", bridge_command())),
+ "{text}"
+ );
assert!(!text.contains("url ="), "{text}");
let mut dsh = args_for(McpClient::Dsh);
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index d18465c1..8737f4ff 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -23,8 +23,9 @@ Warp, Cline, Kilo Code, Goose, Qwen Code and OpenHuman have no
> other client gets a local stdio entry, in its own format, that runs
> `ai-memory mcp-bridge --no-session-id --server-url <url>`: the bridge reads
> the token file at launch and forwards no session id, so the client passes
-> `workspace` and `project` like any static client. The client must find
-> `ai-memory` on its `PATH` (GUI apps may need the full path). ZCode keeps
+> `workspace` and `project` like any static client. Stdio entries name the
+> `ai-memory` binary by its absolute path, so the client does not need it on
+> its `PATH`; the Docker wrapper keeps the bare `ai-memory`. ZCode keeps
> HTTP entries only and is refused. Passing `--auth-token` explicitly (or
> `AI_MEMORY_AUTH_TOKEN`) keeps the HTTP snippets below, header included.
@@ -201,7 +202,8 @@ sessions through that entry. Opt into ai-memory's local stdio bridge instead:
ai-memory install-mcp --client claude-code --session-aware --apply
```
-The generated entry runs `ai-memory mcp-bridge`, connects to the same configured
+The generated entry runs `ai-memory mcp-bridge`, naming the binary by its
+absolute path, connects to the same configured
local or remote `/mcp` endpoint, preserves bearer authentication, and adds
`X-Memory-Actor-Session-Id: <CLAUDE_CODE_SESSION_ID>` to every upstream request.
It supports ai-memory's default stateless HTTP mode and opt-in stateful mode.
@@ -532,7 +534,7 @@ id as the actor session:
"mcpServers": {
"ai-memory": {
"type": "stdio",
- "command": "ai-memory",
+ "command": "/home/you/.local/bin/ai-memory",
"args": ["mcp-bridge", "--agent", "muse",
"--server-url", "http://127.0.0.1:49374/mcp",
"--data-dir", "/home/you/.local/share/ai-memory"],