Skip to content

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

Rust

fix(wrapper): keep the native client and its hook bundle out of the cache

Felipe Neves Ricardo068a040fb77a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 00f83a7e..05489bfa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- The Linux/macOS Docker wrapper now keeps its native host client in
+ `${XDG_DATA_HOME:-~/.local/share}/ai-memory/native-runner` instead of
+ `~/.cache/ai-memory/native-runner`. `ai-memory run` auto-wires hooks whose
+ command is that client's path (Claude Code, Codex, Kimi Code, Command Code,
+ Kiro CLI v3, Grok, Antigravity CLI), so flushing `~/.cache` left every hook of
+ those harnesses pointing at a missing binary. The wrapper also keeps the
+ release's `hooks/` bundle beside the client, so auto-wire no longer fails
+ with "could not locate hooks directory" for script-based harnesses on a host
+ where `install-hooks` never ran. (#874)
- Auto-improve review no longer stages a proposal whose LLM-produced page
path contains a Windows-illegal character (e.g. a `:` copied from a
conventional-commit subject). That path passed the deliberately tolerant
diff --git a/bin/ai-memory b/bin/ai-memory
index 18b6dcc1..f96f0ca9 100755
--- a/bin/ai-memory
+++ b/bin/ai-memory
@@ -9,7 +9,7 @@
#
# Special wrapper-only subcommands (not forwarded to the binary):
# ai-memory upgrade Pull the latest image + remind to re-stage hooks.
-# ai-memory run ... Use a cached native client so it can exec host agents.
+# ai-memory run ... Use a local native client so it can exec host agents.
# ai-memory show ... Use that client for host project/harness discovery.
# ai-memory continue ... Use that client to resume the newest linked checkout.
# ai-memory workstreams Use that client to inspect the host checkout identity.
@@ -55,6 +55,10 @@ DATA_VOLUME="${AI_MEMORY_DATA_VOLUME:-ai-memory-data}"
CACHE_DIR="${XDG_CACHE_HOME:-${HOME}/.cache}/ai-memory"
VERSION_CHECK_FILE="${CACHE_DIR}/last-version-check"
HOOKS_STAGE_DIR="${HOME}/.local/share/ai-memory/hooks"
+# `run` auto-wires hooks whose command is this client's own path, so a cache
+# flush would break every hook until the next managed launch. Keep it with the
+# host's ai-memory data instead of under CACHE_DIR.
+NATIVE_RUNNER_DIR="${XDG_DATA_HOME:-${HOME}/.local/share}/ai-memory/native-runner"
WRAPPER_URL="${AI_MEMORY_WRAPPER_URL:-https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper}"
WRAPPER_SHA256_URL="${AI_MEMORY_WRAPPER_SHA256_URL:-${WRAPPER_URL}.sha256}"
@@ -354,7 +358,7 @@ cmd_upgrade() {
fi
echo "→ pulling ${IMAGE}"
"${DOCKER}" pull "${IMAGE}"
- rm -f "${CACHE_DIR}/native-runner/last-check"
+ rm -f "${NATIVE_RUNNER_DIR}/last-check"
local found_agents=()
if [ -d "${HOOKS_STAGE_DIR}" ]; then
@@ -455,7 +459,7 @@ cmd_upgrade() {
# Managed launch/discovery commands must execute on the host: checkouts, harnesses,
# and native transcript stores are host resources, not contents of the helper
-# container. Keep a checksum-verified release client beside the wrapper cache.
+# container. Keep a checksum-verified release client under NATIVE_RUNNER_DIR.
native_host_binary() {
if [ -n "${AI_MEMORY_NATIVE_BIN:-}" ]; then
[ -x "${AI_MEMORY_NATIVE_BIN}" ] || {
@@ -486,7 +490,7 @@ native_host_binary() {
esac
artifact="ai-memory-${os}-${arch}"
base="https://github.com/akitaonrails/ai-memory/releases/latest/download/${artifact}.tar.gz"
- native_dir="${CACHE_DIR}/native-runner"
+ native_dir="${NATIVE_RUNNER_DIR}"
binary="${native_dir}/ai-memory"
archive="${native_dir}/${artifact}.tar.gz"
check_file="${native_dir}/last-check"
@@ -533,6 +537,13 @@ native_host_binary() {
[ -x "${tmp}/ai-memory" ] || chmod +x "${tmp}/ai-memory"
mv "${tmp}/${artifact}.tar.gz" "${archive}"
mv "${tmp}/ai-memory" "${binary}"
+ # `run` auto-wires hooks through this client, and install-hooks looks for
+ # its script bundle beside the binary. Without it, auto-wiring fails for
+ # every script-based harness on a host where nothing was staged yet.
+ if [ -d "${tmp}/hooks" ]; then
+ rm -rf "${native_dir}/hooks"
+ mv "${tmp}/hooks" "${native_dir}/hooks"
+ fi
rm -rf "${tmp}"
touch "${check_file}"
fi
diff --git a/crates/ai-memory-cli/tests/suite/packaging.rs b/crates/ai-memory-cli/tests/suite/packaging.rs
index db61b258..614a5d1b 100644
--- a/crates/ai-memory-cli/tests/suite/packaging.rs
+++ b/crates/ai-memory-cli/tests/suite/packaging.rs
@@ -1524,6 +1524,152 @@ mod slow {
);
}
+ /// `run` auto-wires hooks whose command is the native client's own path,
+ /// so the client must not live where a cache flush deletes it, and its
+ /// release `hooks/` bundle must sit beside it for script-based harnesses.
+ #[cfg(unix)]
+ #[test]
+ fn wrapper_installs_native_client_and_hook_bundle_outside_the_cache() {
+ use std::os::unix::fs::PermissionsExt as _;
+
+ let tmp = tempfile::tempdir().unwrap();
+ let release = tmp.path().join("release");
+ std::fs::create_dir_all(release.join("hooks/claude-code")).unwrap();
+ let record = tmp.path().join("native-record.txt");
+ std::fs::write(
+ release.join("ai-memory"),
+ format!(
+ "#!/usr/bin/env bash\nprintf '%s\\n' \"$@\" > {}\n",
+ shell_path(&record)
+ ),
+ )
+ .unwrap();
+ std::fs::set_permissions(
+ release.join("ai-memory"),
+ std::fs::Permissions::from_mode(0o755),
+ )
+ .unwrap();
+ std::fs::write(
+ release.join("hooks/claude-code/session-start.sh"),
+ "#!/bin/sh\n",
+ )
+ .unwrap();
+ let tarball = tmp.path().join("release.tar.gz");
+ let tar = Command::new("tar")
+ .arg("-czf")
+ .arg(&tarball)
+ .arg("-C")
+ .arg(&release)
+ .arg(".")
+ .status()
+ .unwrap();
+ assert!(tar.success(), "building the fake release tarball failed");
+ let sum = sha256_file(&tarball);
+
+ // Serve the tarball and its checksum the way the GitHub release does;
+ // the checksum names the asset the wrapper asked for.
+ let bin = tmp.path().join("bin");
+ std::fs::create_dir_all(&bin).unwrap();
+ let curl = bin.join("curl");
+ std::fs::write(
+ &curl,
+ format!(
+ "#!/usr/bin/env bash\n\
+ url=''; out=''\n\
+ while [ \"$#\" -gt 0 ]; do\n\
+ case \"$1\" in\n\
+ -o) out=\"$2\"; shift 2 ;;\n\
+ -*) shift ;;\n\
+ *) url=\"$1\"; shift ;;\n\
+ esac\n\
+ done\n\
+ case \"$url\" in\n\
+ *.tar.gz.sha256) body=\"{sum} $(basename \"${{url%.sha256}}\")\" ;;\n\
+ *.tar.gz) cp {tarball} \"$out\"; exit 0 ;;\n\
+ *) exit 22 ;;\n\
+ esac\n\
+ if [ -n \"$out\" ]; then printf '%s\\n' \"$body\" > \"$out\"; else printf '%s\\n' \"$body\"; fi\n",
+ tarball = shell_path(&tarball),
+ ),
+ )
+ .unwrap();
+ let docker = bin.join("docker");
+ let docker_record = tmp.path().join("docker-record.txt");
+ std::fs::write(
+ &docker,
+ format!(
+ "#!/usr/bin/env bash\nprintf '%s\\n' \"$@\" > {}\nexit 99\n",
+ shell_path(&docker_record)
+ ),
+ )
+ .unwrap();
+ for script in [&curl, &docker] {
+ std::fs::set_permissions(script, std::fs::Permissions::from_mode(0o755)).unwrap();
+ }
+ let path = format!(
+ "{}:{}",
+ shell_path(&bin),
+ std::env::var("PATH").unwrap_or_default()
+ );
+
+ // Default data home, then an explicit XDG_DATA_HOME.
+ for (case, xdg_data_home) in [("default", false), ("xdg", true)] {
+ let home = tmp.path().join(format!("home-{case}"));
+ let cache = tmp.path().join(format!("cache-{case}"));
+ let data_home = if xdg_data_home {
+ tmp.path().join(format!("data-{case}"))
+ } else {
+ home.join(".local/share")
+ };
+ std::fs::create_dir_all(&home).unwrap();
+ let _ = std::fs::remove_file(&record);
+
+ let mut command = shell_script_command(&repo_root().join("bin/ai-memory"));
+ command
+ .args(["workstreams", "--limit", "5"])
+ .env("HOME", &home)
+ .env("XDG_CACHE_HOME", &cache)
+ .env("AI_MEMORY_DOCKER", &docker)
+ .env("PATH", &path)
+ .env_remove("AI_MEMORY_NATIVE_BIN");
+ if xdg_data_home {
+ command.env("XDG_DATA_HOME", &data_home);
+ } else {
+ command.env_remove("XDG_DATA_HOME");
+ }
+ let output = command.output().unwrap();
+ assert!(
+ output.status.success(),
+ "{case}: wrapper failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ let runner = data_home.join("ai-memory/native-runner");
+ assert!(
+ runner.join("ai-memory").is_file(),
+ "{case}: native client missing from {}",
+ runner.display()
+ );
+ assert!(
+ runner.join("hooks/claude-code/session-start.sh").is_file(),
+ "{case}: release hooks bundle not kept beside the client"
+ );
+ assert!(
+ !cache.join("ai-memory/native-runner").exists(),
+ "{case}: native client was installed under the cache"
+ );
+ assert_eq!(
+ std::fs::read_to_string(&record).unwrap(),
+ "workstreams\n--limit\n5\n",
+ "{case}: wrapper did not exec the installed client"
+ );
+ }
+ assert!(
+ !docker_record.exists(),
+ "managed host command entered Docker"
+ );
+ }
+
#[cfg(unix)]
#[test]
fn wrapper_upgrade_does_not_claim_an_updated_remote_server_is_stale() {
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 0e90668e..fbc7d771 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -561,8 +561,16 @@ the launched Crush process continues its normal native session writes.
The Linux/macOS Docker shell wrapper cannot inspect host projects or execute a
host agent from inside its helper container. For `run`, `show`, `continue`,
`resume`, and `workstreams`, it downloads the matching native release into
-`~/.cache/ai-memory/native-runner`, verifies the published SHA-256 checksum, and
-executes that host client. Set `AI_MEMORY_NATIVE_BIN=/path/to/ai-memory` to use a
+`${XDG_DATA_HOME:-~/.local/share}/ai-memory/native-runner`, verifies the
+published SHA-256 checksum, and executes that host client. The release's
+`hooks/` bundle is kept beside it so auto-wire can stage hook scripts on a host
+where `install-hooks` never ran. The client lives with the host's ai-memory data
+rather than under `~/.cache` because auto-wired hook configuration runs it
+directly: a cache flush must not break capture. A client downloaded by an older
+wrapper stays in `~/.cache/ai-memory/native-runner`, and hooks auto-wired from it
+keep that path until a newer client version auto-wires again. To move them now,
+re-run `ai-memory install-hooks --agent <agent> --apply`, then delete the old
+directory. Set `AI_MEMORY_NATIVE_BIN=/path/to/ai-memory` to use a
specific native build. Native package, release, and source installs need no
shim. On native Windows, use the published `ai-memory.exe` or a source build.