Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(wrapper): auto-detect podman container engine (#636)
Joao Paulo Ramosdf03a6b4ee75
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a80f1671..18154440 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`dest_free_bytes`, so the same number is visible right before a migration.### Fixed+- The `bin/ai-memory` container wrapper now automatically uses Podman when+ Docker is unavailable, uses a fully qualified Docker Hub image name to avoid+ Podman's non-interactive short-name resolution failure, and preserves the+ selected engine in standalone-container recovery scripts emitted by+ `ai-memory upgrade` instead of hard-coding `docker` (#636).- Corrected `docs/MIGRATION-2.0.md`, which wrongly promised the automaticpre-migration archive could roll a store back to 1.x (#633). The archive iswritten *after* `Store::open` migrates the SQLite schema forward, so itsdiff --git a/README.md b/README.mdindex 331e441b..f30d0f7c 100644--- a/README.md+++ b/README.md@@ -146,8 +146,8 @@ packaged unit. Full user-service, system-service, auth, and provider setup is in### Docker-You need: Docker + an agent CLI from the [Support Matrix](#support-matrix), or-anything else that speaks MCP.+You need: Docker or Podman + an agent CLI from the [Support Matrix](#support-matrix),+or anything else that speaks MCP.The published Docker image includes `linux/amd64` and `linux/arm64` variants,so Apple Silicon Macs and ARM64 Linux hosts can pull `akitaonrails/ai-memory`@@ -160,7 +160,7 @@ expose the server on the LAN; see [Security](#security) below.```bash# 1. Install the ai-memory CLI wrapper (a small shell script that-# runs the binary inside docker with your $HOME mounted). This is+# runs the binary inside a container with your $HOME mounted). This is# the only thing that needs to live on the host filesystem.mkdir -p ~/.local/binwrapper_tmp="$(mktemp -d)"@@ -197,7 +197,7 @@ docker run -d --name ai-memory \-e ANTHROPIC_API_KEY=sk-ant-... \-e AI_MEMORY_EMBEDDING_PROVIDER=openai \-e OPENAI_API_KEY=sk-... \- akitaonrails/ai-memory:latest+ docker.io/akitaonrails/ai-memory:latest# 3. Wire your agent CLI in two commands. The wrapper takes care of# mounts and each client's config-path detection. Re-run with@@ -210,6 +210,10 @@ ai-memory install-mcp --client claude-code --applyai-memory install-hooks --agent claude-code --apply```+The examples use `docker`; replace it with `podman` on a Podman host. The+wrapper automatically uses Podman when Docker is not installed. Set+`AI_MEMORY_DOCKER=podman` to force Podman when both engines are available.+On Linux/macOS, that's it. Start a Claude Code session as usual - everyprompt and tool call now lands in ai-memory, and the next session youopen in this project will see a handoff with where you left off.diff --git a/bin/ai-memory b/bin/ai-memoryindex 49897fce..94b43957 100755--- a/bin/ai-memory+++ b/bin/ai-memory@@ -1,5 +1,5 @@#!/usr/bin/env bash-# ai-memory — thin wrapper that invokes the dockerised ai-memory+# ai-memory — thin wrapper that invokes the containerized ai-memory# binary with the right mounts so install-* commands can edit your# real config files, bootstrap can read your real project, and# data-dir commands hit the same volume your server uses.@@ -17,8 +17,8 @@# Same: the rename is keyed on host repo identity.## Env overrides:-# AI_MEMORY_IMAGE docker image (default: akitaonrails/ai-memory:latest)-# AI_MEMORY_DOCKER docker command (default: docker; e.g. "podman")+# AI_MEMORY_IMAGE container image (default: docker.io/akitaonrails/ai-memory:latest)+# AI_MEMORY_DOCKER container engine command (default: docker, then podman)# AI_MEMORY_DATA_VOLUME named volume mounted at /data (default: ai-memory-data)# AI_MEMORY_DATA_DIR host path to bind-mount at /data instead (rare)# AI_MEMORY_SERVER_URL server URL for thin-client commands; if unset,@@ -39,8 +39,18 @@# paths under $HOME are covered by the home bind mount)set -euo pipefail-IMAGE="${AI_MEMORY_IMAGE:-akitaonrails/ai-memory:latest}"-DOCKER="${AI_MEMORY_DOCKER:-docker}"+IMAGE="${AI_MEMORY_IMAGE:-docker.io/akitaonrails/ai-memory:latest}"+if [ -n "${AI_MEMORY_DOCKER:-}" ]; then+ DOCKER="${AI_MEMORY_DOCKER}"+elif command -v docker >/dev/null 2>&1; then+ DOCKER="docker"+elif command -v podman >/dev/null 2>&1; then+ DOCKER="podman"+else+ # Preserve the existing command-not-found error for containerized commands;+ # native wrapper-only commands do not need either engine.+ DOCKER="docker"+fiDATA_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"@@ -143,7 +153,7 @@ self_upgrade_script() {}-# Reconstruct the `docker run` that created a running container, so a+# Reconstruct the container-engine command that created a running container, so a# non-compose install can be recreated on the freshly pulled image without# the operator having to remember their original flags (issue #407).#@@ -154,11 +164,12 @@ self_upgrade_script() {## Reconstructs the flags that matter for an ai-memory container: name,# restart policy, published ports, mounts, operator-supplied environment,-# and an overridden command. It does NOT reproduce every possible `docker+# and an overridden command. It does NOT reproduce every possible container# run` flag (networks, capabilities, resource limits, devices); the script# says so in its own header so a reader can add anything exotic back.emit_docker_run_script() {- local container="$1" out="$2" image+ local container="$1" out="$2" image engine+ printf -v engine '%q' "${DOCKER}"image="$("${DOCKER}" inspect "${container}" --format '{{.Config.Image}}' 2>/dev/null)" || return 1[ -n "${image}" ] || return 1@@ -212,9 +223,9 @@ ENVEOFecho "# else (custom network, capabilities, resource limits), re-add it."echo "set -euo pipefail"echo- echo "docker stop ${container}"- echo "docker rm ${container}"- printf 'docker run -d --name %s' "${container}"+ printf '%s stop %q\n' "${engine}" "${container}"+ printf '%s rm %q\n' "${engine}" "${container}"+ printf '%s run -d --name %q' "${engine}" "${container}"[ -n "${restart}" ] && printf ' %s' "${restart}"[ -n "${ports}" ] && printf ' %s' "${ports% }"[ -n "${volumes}" ] && printf ' %s' "${volumes% }"@@ -294,10 +305,10 @@ cmd_upgrade() {if "${DOCKER}" ps --filter "name=^ai-memory$" --format '{{.Names}}' 2>/dev/null \| grep -q '^ai-memory$'; then# A LOCAL ai-memory container is running. We've just pulled a new- # image; `docker restart` won't recreate from the new image, so we- # need to stop+remove+recreate. Use `docker compose up -d` only when+ # image; a restart won't recreate from the new image, so we+ # need to stop+remove+recreate. Use `compose up -d` only when# the discovered project owns this container; otherwise reconstruct- # the standalone `docker run` from its inspected runtime settings.+ # the standalone container from its inspected runtime settings.local compose_dir=""if [ -f "$(pwd)/docker/docker-compose.yml" ]; thencompose_dir="$(pwd)/docker"@@ -307,13 +318,13 @@ cmd_upgrade() {compose_dir="${HOME}/deploy/ai-memory"fiif [ -n "${compose_dir}" ] && compose_manages_container "ai-memory" "${compose_dir}"; then- echo "→ restarting local ai-memory container via docker compose (${compose_dir})"+ echo "→ restarting local ai-memory container via ${DOCKER} compose (${compose_dir})"( cd "${compose_dir}" && "${DOCKER}" compose up -d ) \- || echo " (compose restart failed; re-run manually: cd ${compose_dir} && docker compose up -d)"+ || echo " (compose restart failed; re-run manually: cd ${compose_dir} && ${DOCKER} compose up -d)"elseif [ -n "${compose_dir}" ]; thenecho "→ the compose file at ${compose_dir} does not manage the running ai-memory container"- echo " Treating it as a standalone docker run install to avoid a container-name conflict."+ echo " Treating it as a standalone ${DOCKER} run install to avoid a container-name conflict."elseecho "→ a local ai-memory container is running but no compose file"echo " was found in \$PWD/docker-compose.yml, ./docker/docker-compose.yml,"@@ -331,8 +342,8 @@ cmd_upgrade() {elseecho " Could not inspect the running container to reconstruct its"echo " command. Restart it manually so the new image takes effect:"- echo " docker stop ai-memory && docker rm ai-memory"- echo " # then re-run your docker-run command from the README Quick start"+ echo " ${DOCKER} stop ai-memory && ${DOCKER} rm ai-memory"+ echo " # then re-run your container command from the README Quick start"fififi@@ -371,7 +382,7 @@ native_host_binary() {Linux) os="linux" ;;Darwin) os="macos" ;;*)- echo "ai-memory: the Docker wrapper cannot provide managed host launches on this OS" >&2+ echo "ai-memory: the container wrapper cannot provide managed host launches on this OS" >&2echo "install the native release binary to use ai-memory run/show/continue/resume/workstreams/rename-workstream" >&2return 1;;@@ -455,7 +466,7 @@ case "${1:-}" in;;esac-# ---- normal pass-through to the binary inside docker ---------------------+# ---- normal pass-through to the binary inside a container ----------------maybe_warn_outdated || truediff --git a/crates/ai-memory-cli/tests/packaging.rs b/crates/ai-memory-cli/tests/packaging.rsindex b1dd4ac3..1b54be65 100644--- a/crates/ai-memory-cli/tests/packaging.rs+++ b/crates/ai-memory-cli/tests/packaging.rs@@ -449,6 +449,76 @@ fn docker_wrappers_keep_stdin_attached_independently_of_tty_allocation() {assert!(powershell.contains("${ScopeRoot}:/scope:ro"));}+#[cfg(unix)]+#[test]+fn posix_wrapper_auto_selects_podman_when_docker_is_unavailable() {+ let tmp = tempfile::tempdir().unwrap();+ let podman_args = tmp.path().join("podman-args.txt");+ let scripts = [+ (+ "podman",+ format!(+ "#!/bin/bash\n\+ if [ \"${{1:-}}\" = info ]; then\n\+ \x20 printf '[name=seccomp]\\n'\n\+ \x20 exit 0\n\+ fi\n\+ printf '%s\\n' \"$@\" > {}\n",+ shell_path(&podman_args)+ ),+ ),+ (+ "id",+ "#!/bin/bash\ncase \"$1\" in -u) printf '1000\\n' ;; -g) printf '1000\\n' ;; esac\n"+ .to_owned(),+ ),+ ("uname", "#!/bin/bash\nprintf 'Linux\\n'\n".to_owned()),+ ("getenforce", "#!/bin/bash\nprintf 'Disabled\\n'\n".to_owned()),+ (+ "grep",+ "#!/bin/bash\n\+ pattern=\"${@: -1}\"\n\+ input=\"\"\n\+ while IFS= read -r line; do input=\"${input}${line}\"; done\n\+ case \"${input}\" in *\"${pattern}\"*) exit 0 ;; *) exit 1 ;; esac\n"+ .to_owned(),+ ),+ ];+ for (name, body) in scripts {+ let path = tmp.path().join(name);+ std::fs::write(&path, body).unwrap();+ use std::os::unix::fs::PermissionsExt as _;+ std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap();+ }++ let output = Command::new("/bin/bash")+ .arg(repo_root().join("bin/ai-memory"))+ .arg("status")+ .env("PATH", tmp.path())+ .env("HOME", tmp.path())+ .env("AI_MEMORY_NO_TTY", "1")+ .env("AI_MEMORY_NO_VERSION_CHECK", "1")+ .env("AI_MEMORY_DATA_VOLUME", "test-ai-memory-data")+ .env_remove("AI_MEMORY_DOCKER")+ .env_remove("AI_MEMORY_IMAGE")+ .env_remove("AI_MEMORY_SERVER_URL")+ .output()+ .unwrap();+ assert!(+ output.status.success(),+ "wrapper failed: stdout={} stderr={}",+ String::from_utf8_lossy(&output.stdout),+ String::from_utf8_lossy(&output.stderr)+ );+ let args = std::fs::read_to_string(podman_args).unwrap();+ let flags: Vec<_> = args.lines().collect();+ assert_eq!(flags.first(), Some(&"run"), "Podman was not invoked: {args}");+ assert!(+ flags.contains(&"docker.io/akitaonrails/ai-memory:latest"),+ "default image must not require Podman short-name resolution: {args}"+ );+}+#[test]fn wrapper_updates_and_install_docs_use_verified_release_assets() {let wrapper = read_repo("bin/ai-memory");diff --git a/docs/install.md b/docs/install.mdindex 4bfb2032..de576a60 100644--- a/docs/install.md+++ b/docs/install.md@@ -34,9 +34,11 @@ path (docker + Claude Code). This page covers everything else:The Docker image is published for `linux/amd64` and `linux/arm64`; AppleSilicon Macs and ARM64 Linux hosts should not need `--platform linux/amd64`.-> **Podman.** The `bin/ai-memory` wrapper works with rootless podman, either-> through the `podman-docker` `docker` shim or by pointing it at podman-> directly with `AI_MEMORY_DOCKER=podman`. See+> **Podman.** The `bin/ai-memory` wrapper automatically uses rootless Podman+> when Docker is not installed. It also works through the `podman-docker`+> `docker` shim; set `AI_MEMORY_DOCKER=podman` to force Podman when both engines+> are installed. The default image name is fully qualified for non-interactive+> Podman short-name resolution. See> [SELinux-enforcing hosts](#selinux-enforcing-hosts) for how it detects the> engine's rootless and SELinux state.diff --git a/tests/wrapper_upgrade.sh b/tests/wrapper_upgrade.shindex 3c155c3f..3eb18168 100755--- a/tests/wrapper_upgrade.sh+++ b/tests/wrapper_upgrade.sh@@ -23,7 +23,7 @@ assert_not_contains() {fi}-FAKE_DOCKER="${TMP_ROOT}/docker"+FAKE_DOCKER="${TMP_ROOT}/podman"cat >"${FAKE_DOCKER}" <<'DOCKER'#!/usr/bin/env bashset -euo pipefail@@ -85,9 +85,11 @@ run_upgrade_case standalone 0assert_contains "${TMP_ROOT}/standalone/output.log" "does not manage the running ai-memory container"assert_not_contains "${TMP_ROOT}/standalone/docker.log" "compose up -d"assert_contains "${TMP_ROOT}/standalone/cache/ai-memory/recreate-ai-memory.sh" "-v ai-memory-data:/data"+assert_contains "${TMP_ROOT}/standalone/cache/ai-memory/recreate-ai-memory.sh" "${FAKE_DOCKER} stop ai-memory"+assert_not_contains "${TMP_ROOT}/standalone/cache/ai-memory/recreate-ai-memory.sh" "docker stop ai-memory"run_upgrade_case compose 1-assert_contains "${TMP_ROOT}/compose/output.log" "restarting local ai-memory container via docker compose"+assert_contains "${TMP_ROOT}/compose/output.log" "restarting local ai-memory container via ${FAKE_DOCKER} compose"assert_contains "${TMP_ROOT}/compose/docker.log" "compose up -d"if [ -e "${TMP_ROOT}/compose/cache/ai-memory/recreate-ai-memory.sh" ]; thenfail "Compose-owned container unexpectedly produced a standalone recreation script"