Skip to content

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.md
index 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 automatic
pre-migration archive could roll a store back to 1.x (#633). The archive is
written *after* `Store::open` migrates the SQLite schema forward, so its
diff --git a/README.md b/README.md
index 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/bin
wrapper_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 --apply
ai-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 - every
prompt and tool call now lands in ai-memory, and the next session you
open in this project will see a handoff with where you left off.
diff --git a/bin/ai-memory b/bin/ai-memory
index 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"
+fi
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"
@@ -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 @@ ENVEOF
echo "# 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" ]; then
compose_dir="$(pwd)/docker"
@@ -307,13 +318,13 @@ cmd_upgrade() {
compose_dir="${HOME}/deploy/ai-memory"
fi
if [ -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)"
else
if [ -n "${compose_dir}" ]; then
echo "→ 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."
else
echo "→ 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() {
else
echo " 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"
fi
fi
fi
@@ -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" >&2
echo "install the native release binary to use ai-memory run/show/continue/resume/workstreams/rename-workstream" >&2
return 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 || true
diff --git a/crates/ai-memory-cli/tests/packaging.rs b/crates/ai-memory-cli/tests/packaging.rs
index 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.md
index 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`; Apple
Silicon 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.sh
index 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 bash
set -euo pipefail
@@ -85,9 +85,11 @@ run_upgrade_case standalone 0
assert_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" ]; then
fail "Compose-owned container unexpectedly produced a standalone recreation script"