Skip to content

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

Rust

fix(wrapper): clarify remote upgrade state

AkitaOnRailsb479d31f711f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 68340da1..8e81ba54 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+- Corrected Docker-wrapper upgrade guidance: `ai-memory upgrade` no longer
+ claims a configured remote server is stale when it cannot inspect that
+ deployment, and the install guide now makes clear that refreshing Docker
+ script hooks does not convert them to native capture-policy commands.
+
## [1.17.2] - 2026-07-22
### Added
@@ -29,8 +35,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
the spool/wire. Optional assistant/Stop capture proposed in #196 remains
disabled. Upgrading the binary is sufficient for native Claude Code installs;
script-fallback installs (Docker wrapper, `AI_MEMORY_HOOK_PLATFORM=posix`)
- should run `ai-memory install-hooks --agent claude-code --apply` to migrate to
- native commands and close the residual local-wire vector ([#196]).
+ still send the raw field to the server, which strips it immediately on
+ receipt. Closing the local-wire vector requires a native client on the agent
+ host and using it to reinstall hooks; running the installer through the
+ Docker wrapper only refreshes its scripts ([#196]).
### Fixed
- Removed the unused `syntect` dependency and its `plist`, `quick-xml`,
diff --git a/bin/ai-memory b/bin/ai-memory
index d22fc875..c960824d 100755
--- a/bin/ai-memory
+++ b/bin/ai-memory
@@ -181,18 +181,16 @@ cmd_upgrade() {
fi
fi
- # If the server runs on a different host (homelab scenario), only
- # the local wrapper + image + hook scripts got refreshed here.
- # Surface that, because the user still needs to deploy on the
- # remote box for the server-side binary to update.
+ # If the server runs on a different host (homelab scenario), this command
+ # cannot know or change that host's deployment state.
if [ -n "${AI_MEMORY_SERVER_URL:-}" ] \
&& ! echo "${AI_MEMORY_SERVER_URL}" | grep -qE '^https?://(127\.|localhost|\[?::1\]?)'; then
echo
echo "→ Note: AI_MEMORY_SERVER_URL points at ${AI_MEMORY_SERVER_URL}"
- echo " Your local image is now up to date, but the remote server still"
- echo " runs the previous version. Redeploy on that host (e.g. \`bin/deploy\`"
- echo " or \`docker compose pull && docker compose up -d\` in its deploy dir)"
- echo " for the server-side binary to update."
+ echo " ai-memory upgrade updates this wrapper and local image only; it does not"
+ echo " inspect or redeploy the remote server. If that host is not already current,"
+ echo " run \`bin/deploy\` or \`docker compose pull && docker compose up -d\`"
+ echo " in its deploy directory."
fi
mkdir -p "${CACHE_DIR}"
diff --git a/crates/ai-memory-cli/tests/packaging.rs b/crates/ai-memory-cli/tests/packaging.rs
index 38d8152d..f977ab60 100644
--- a/crates/ai-memory-cli/tests/packaging.rs
+++ b/crates/ai-memory-cli/tests/packaging.rs
@@ -276,6 +276,44 @@ fn managed_run_wrapper_uses_host_binary_path_and_remote_server_without_docker()
assert!(!docker_record.exists(), "managed run entered Docker");
}
+#[cfg(unix)]
+#[test]
+fn wrapper_upgrade_does_not_claim_an_updated_remote_server_is_stale() {
+ let tmp = tempfile::tempdir().unwrap();
+ let docker = tmp.path().join("docker");
+ std::fs::write(
+ &docker,
+ "#!/usr/bin/env bash\n\
+ case \"$1\" in\n\
+ pull | ps) exit 0 ;;\n\
+ *) exit 1 ;;\n\
+ esac\n",
+ )
+ .unwrap();
+ {
+ use std::os::unix::fs::PermissionsExt as _;
+ std::fs::set_permissions(&docker, std::fs::Permissions::from_mode(0o755)).unwrap();
+ }
+
+ let output = shell_script_command(&repo_root().join("bin/ai-memory"))
+ .arg("upgrade")
+ .env("AI_MEMORY_DOCKER", &docker)
+ .env("AI_MEMORY_SKIP_SELF_UPGRADE", "1")
+ .env("AI_MEMORY_SERVER_URL", "http://192.168.0.90:49374")
+ .env("HOME", tmp.path())
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "wrapper failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ let stdout = String::from_utf8_lossy(&output.stdout);
+ assert!(stdout.contains("does not\n inspect or redeploy the remote server"));
+ assert!(stdout.contains("If that host is not already current"));
+ assert!(!stdout.contains("remote server still\n runs the previous version"));
+}
+
#[cfg(unix)]
#[test]
fn docker_wrapper_completions_tolerate_an_early_reader_close() {
diff --git a/docs/install.md b/docs/install.md
index f1d0db63..27bea4ef 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -401,8 +401,13 @@ Upgrading the binary is sufficient for native Claude Code installs, and pending
spooled events drain with the field stripped as well. Installs that run the
`.sh`/`.ps1` script fallback (the Docker script bundle or an explicit
`AI_MEMORY_HOOK_PLATFORM=posix`) still POST the raw field on the local wire
-until they move to native commands: run `install-hooks --agent claude-code
---apply`, which installs native `ai-memory hook` commands where supported.
+until they move to native commands. The Docker wrapper deliberately keeps
+script commands because a binary path inside its helper container is not valid
+on the host; running `install-hooks` through that wrapper refreshes the scripts
+but does not convert them. To close the local-wire exposure, install a native
+ai-memory client on the agent host, then use that native executable to run
+`install-hooks --agent claude-code --apply`. If the script fallback is retained,
+the server still strips the field immediately on receipt before persistence.
Native `ai-memory hook --event ...` commands spool events locally. Session start
does a short bounded cleanup drain before fetching a handoff; cancellation-prone