Skip to content

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

Rust

bin/ai-memory: dockerised CLI wrapper + simplify install

AkitaOnRailsa227d72cf9ab
diff --git a/README.md b/README.md
index cfa59d48..6d5c3435 100644
--- a/README.md
+++ b/README.md
@@ -30,56 +30,96 @@ You need: Docker + an agent CLI (Claude Code, Codex, OpenCode, Cursor,
or anything else that speaks MCP).
```bash
-# 1. Generate a bearer token (one-time; save the output).
-export TOKEN=$(docker run --rm akitaonrails/ai-memory:latest generate-auth-token)
-
-# 2. Start the server. Replace the API keys (or omit the four
-# -e AI_MEMORY_LLM_* / EMBEDDING_* lines for zero-LLM mode — FTS5
-# search still works without any keys).
+# 1. Install the ai-memory CLI wrapper (a ~3 KB shell script that
+# runs the binary inside docker with your $HOME mounted). This is
+# the only thing that needs to live on the host filesystem.
+mkdir -p ~/.local/bin
+curl -fsSL https://raw.githubusercontent.com/akitaonrails/ai-memory/main/bin/ai-memory \
+ -o ~/.local/bin/ai-memory
+chmod +x ~/.local/bin/ai-memory
+# Most distros put ~/.local/bin on PATH automatically. If `which
+# ai-memory` comes up empty, add this to ~/.bashrc / ~/.zshrc:
+# export PATH="$HOME/.local/bin:$PATH"
+
+# 2. Generate a bearer token (one-time; save it).
+export AI_MEMORY_AUTH_TOKEN=$(ai-memory generate-auth-token)
+
+# 3. Start the server. `--restart unless-stopped` makes it come back
+# on docker daemon restart and on machine boot (provided your
+# docker service is enabled at boot — `sudo systemctl enable
+# docker` on most distros). Omit the LLM / EMBEDDING lines for
+# zero-LLM mode — FTS5 search still works without any keys.
docker run -d --name ai-memory \
+ --restart unless-stopped \
-p 49374:49374 \
-v ai-memory-data:/data \
- -e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
+ -e AI_MEMORY_AUTH_TOKEN="$AI_MEMORY_AUTH_TOKEN" \
-e AI_MEMORY_LLM_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY=sk-ant-... \
-e AI_MEMORY_EMBEDDING_PROVIDER=openai \
-e OPENAI_API_KEY=sk-... \
akitaonrails/ai-memory:latest
-# 3. Wire your agent CLI to it. Claude Code shown below; for Codex,
-# OpenCode, Cursor, Claude Desktop, Gemini CLI, OpenClaw, see
-# docs/install.md.
-
-# 3a. Register the MCP endpoint (auto-edits ~/.claude/settings.json)
-docker run --rm -v "$HOME:/host" akitaonrails/ai-memory:latest \
- install-mcp --client claude-code --apply \
- --config-file /host/.claude/settings.json \
- --server-url "http://localhost:49374/mcp" \
- --auth-token "$TOKEN"
-
-# 3b. Extract the bundled hook scripts to your home dir
-docker cp ai-memory:/usr/local/share/ai-memory/hooks ~/.ai-memory/
-
-# 3c. Wire the hooks into ~/.claude/settings.json (also auto-edits)
-docker run --rm -v "$HOME:/host" akitaonrails/ai-memory:latest \
- install-hooks --agent claude-code --apply \
- --hooks-dir /host/.ai-memory/hooks \
- --config-file /host/.claude/settings.json \
- --server-url "http://localhost:49374" \
- --auth-token "$TOKEN"
+# 4. Wire your agent CLI in two commands. The wrapper takes care of
+# mounts + auto-detecting ~/.claude/settings.json. Re-run with
+# `--agent codex`, `--agent opencode`, `--client cursor`, etc.
+# for additional agents; full list in docs/install.md.
+ai-memory install-mcp --client claude-code --apply \
+ --server-url "http://localhost:49374/mcp"
+ai-memory install-hooks --agent claude-code --apply \
+ --server-url "http://localhost:49374"
```
-Both `install-mcp` and `install-hooks` accept `--apply` to **mutate
-the agent's config file in place** (idempotent — re-runs replace
-ai-memory's entry, preserving every other server / hook the user has
-configured; a timestamped `.bak-<ts>` is written next to the file
-before each modifying write). Drop `--apply` to keep the legacy
-print-the-JSON behaviour.
+Both `install-mcp` and `install-hooks` are idempotent — re-runs
+replace ai-memory's entry, preserve every other server / hook the
+user has configured, and write a timestamped `.bak-<ts>` next to the
+file before each modifying write. The hook scripts are staged into
+`~/.local/share/ai-memory/hooks/<agent>/` automatically; re-running
+overwrites them so future image updates ship updated hooks. Drop
+`--apply` to print the snippet instead of mutating.
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.
+> **Prefer docker compose?** Clone the repo and run
+> `docker compose -f docker/docker-compose.yml up -d` instead of
+> step 3. The bundled compose file already has
+> `restart: unless-stopped`, a healthcheck, and the named volume
+> wired up; step 4 is identical.
+
+### Keeping ai-memory up to date
+
+The wrapper checks Docker Hub at most once every 24 hours and prints
+a one-line warning to stderr when a newer image is available. To
+upgrade:
+
+```bash
+ai-memory upgrade
+```
+
+In order: (1) self-upgrades the wrapper script itself by re-fetching
+`bin/ai-memory` from GitHub (validated against the shebang; falls
+back gracefully if curl is missing or perms block the in-place
+replacement), (2) `docker pull`s the latest image, (3) re-stages
+hook scripts under `~/.local/share/ai-memory/hooks/<agent>/` for
+every agent you've configured, and (4) tells you how to restart the
+server container so the new binary is picked up. The hook refresh
+is idempotent — re-running `install-hooks --apply` replaces the
+seven keys ai-memory owns and leaves every other hook the user has
+wired up alone. Set `AI_MEMORY_NO_VERSION_CHECK=1` to silence the
+daily check, or `AI_MEMORY_WRAPPER_URL=<url>` to pin the self-upgrade
+source (e.g. a fork or a tagged release).
+
+> **Inside ai-jail (or any bwrap sandbox)?** The wrapper at
+> `~/.local/bin/ai-memory` works fine — the sandbox bind-mounts
+> `~/.local` read-only, so the script is visible from inside, and
+> `/var/run/docker.sock` is already passed through. Run the
+> `install-*` commands *outside* ai-jail (they need to write to
+> `~/.local/share/ai-memory/hooks/`, which the sandbox keeps
+> read-only); daily use from inside the sandbox needs no binary at
+> all (agents reach ai-memory over MCP).
+
**For everything else** — Codex, OpenCode, Cursor, Claude Desktop,
Gemini CLI, OpenClaw, the curl-based hook installer (no docker
needed), running ai-memory without docker, the full subcommand
@@ -130,15 +170,9 @@ solves that by LLM-summarising your existing `git log`, README,
```bash
# Run from your project's repo root (requires an LLM provider on the
# server). Default settings ingest everything; budget caps at 50k
-# input tokens (~$0.04 with Kimi 2.6).
-docker run --rm \
- -v ai-memory-data:/data \
- -v "$PWD:/repo" \
- -e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
- -e AI_MEMORY_LLM_PROVIDER=anthropic \
- -e ANTHROPIC_API_KEY=sk-ant-... \
- akitaonrails/ai-memory:latest \
- bootstrap --repo-path /repo --workspace homelab --project myproj
+# input tokens (~$0.05 with Claude Haiku 4.5). The wrapper auto-mounts the
+# data volume and $PWD into the container.
+ai-memory bootstrap --workspace homelab --project myproj
```
Bootstrap produces a `wiki/bootstrap.md` manifest listing every page
@@ -192,13 +226,12 @@ thinking to call `memory_query`. For projects where memory matters,
one command installs the recommended snippet into your `CLAUDE.md`:
```bash
-docker run --rm -v "$PWD:/host" akitaonrails/ai-memory:latest \
- install-instructions --target /host/CLAUDE.md
+ai-memory install-instructions --target ./CLAUDE.md
```
The block is wrapped in `<!-- ai-memory:start -->` /
`<!-- ai-memory:end -->` markers so re-running picks up an updated
-snippet without duplicating. Use `--target /host/AGENTS.md` for
+snippet without duplicating. Use `--target ./AGENTS.md` for
non-Claude agents, or any other path for project-rules files
(`.cursor/rules`, `.windsurfrules`, etc.). Append `--print` to
preview without writing.
diff --git a/bin/ai-memory b/bin/ai-memory
new file mode 100755
index 00000000..2d55ca55
--- /dev/null
+++ b/bin/ai-memory
@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# ai-memory — thin wrapper that invokes the dockerised 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.
+#
+# Install this to ~/.local/bin/ai-memory (ensure ~/.local/bin is on
+# PATH). See README "Quick start" for the one-liner.
+#
+# Special wrapper-only subcommands (not forwarded to the binary):
+# ai-memory upgrade Pull the latest image + remind to re-stage hooks.
+#
+# Env overrides:
+# AI_MEMORY_IMAGE docker image (default: akitaonrails/ai-memory:latest)
+# AI_MEMORY_DOCKER docker command (default: docker; e.g. "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_NO_TTY=1 force non-interactive even on a real tty
+# AI_MEMORY_NO_VERSION_CHECK=1 skip the once-per-day update check
+set -euo pipefail
+
+IMAGE="${AI_MEMORY_IMAGE:-akitaonrails/ai-memory:latest}"
+DOCKER="${AI_MEMORY_DOCKER:-docker}"
+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"
+WRAPPER_RAW_URL="${AI_MEMORY_WRAPPER_URL:-https://raw.githubusercontent.com/akitaonrails/ai-memory/main/bin/ai-memory}"
+
+# ---- version-check helpers (best-effort; never block the wrapper) --------
+
+local_digest() {
+ "${DOCKER}" image inspect --format='{{index .RepoDigests 0}}' "${IMAGE}" 2>/dev/null \
+ | sed 's/.*@//' || true
+}
+
+remote_digest() {
+ # docker manifest inspect was experimental pre-20.10; on modern
+ # docker it's stable. Silent on failure (offline, podman, etc.).
+ "${DOCKER}" manifest inspect "${IMAGE}" 2>/dev/null \
+ | grep -oE 'sha256:[a-f0-9]{64}' | head -n 1 || true
+}
+
+maybe_warn_outdated() {
+ [ -z "${AI_MEMORY_NO_VERSION_CHECK:-}" ] || return 0
+ # Skip in non-interactive contexts so we don't pollute pipes / CI.
+ [ -t 2 ] || return 0
+ # Skip if we checked within the last 24h (works on both BSD + GNU find).
+ if [ -f "${VERSION_CHECK_FILE}" ] \
+ && [ -z "$(find "${VERSION_CHECK_FILE}" -mtime +0 2>/dev/null)" ]; then
+ return 0
+ fi
+ mkdir -p "${CACHE_DIR}"
+ touch "${VERSION_CHECK_FILE}"
+ local local_d remote_d
+ local_d=$(local_digest)
+ remote_d=$(remote_digest)
+ [ -n "${local_d}" ] && [ -n "${remote_d}" ] || return 0
+ if [ "${local_d}" != "${remote_d}" ]; then
+ printf '\033[33mai-memory: a newer image is available on Docker Hub.\033[0m\n' >&2
+ printf ' run `ai-memory upgrade` to pull it + refresh hooks.\n' >&2
+ fi
+}
+
+# ---- upgrade subcommand --------------------------------------------------
+
+self_upgrade_script() {
+ command -v curl >/dev/null 2>&1 || { echo " curl not found; skipping wrapper self-upgrade" >&2; return 0; }
+ # Portable script-path resolution (works without GNU readlink/realpath).
+ local script_dir script_path tmp
+ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ script_path="${script_dir}/$(basename "${BASH_SOURCE[0]}")"
+ echo "→ checking for wrapper script updates (${script_path})"
+ tmp="$(mktemp)" || return 0
+ if ! curl -fsSL "${WRAPPER_RAW_URL}" -o "${tmp}" 2>/dev/null; then
+ echo " could not fetch ${WRAPPER_RAW_URL}; skipping self-upgrade"
+ rm -f "${tmp}"
+ return 0
+ fi
+ # Sanity: must look like our bash script. Refuse to install
+ # anything that doesn't start with the expected shebang.
+ if ! head -n1 "${tmp}" | grep -q '^#!/usr/bin/env bash'; then
+ echo " downloaded file doesn't look like the ai-memory wrapper; skipping"
+ rm -f "${tmp}"
+ return 0
+ fi
+ if cmp -s "${tmp}" "${script_path}"; then
+ echo " wrapper already up to date"
+ rm -f "${tmp}"
+ return 0
+ fi
+ chmod +x "${tmp}"
+ if ! mv "${tmp}" "${script_path}" 2>/dev/null; then
+ echo " could not replace ${script_path} (permission denied?)"
+ echo " rerun with: sudo install -m 0755 ${tmp} ${script_path}"
+ return 0
+ fi
+ echo " ✓ wrapper updated — re-executing with the new version"
+ AI_MEMORY_SKIP_SELF_UPGRADE=1 exec "${script_path}" upgrade
+}
+
+cmd_upgrade() {
+ if [ -z "${AI_MEMORY_SKIP_SELF_UPGRADE:-}" ]; then
+ self_upgrade_script
+ fi
+ echo "→ pulling ${IMAGE}"
+ "${DOCKER}" pull "${IMAGE}"
+
+ local found_agents=()
+ if [ -d "${HOOKS_STAGE_DIR}" ]; then
+ for d in "${HOOKS_STAGE_DIR}"/*/; do
+ [ -d "${d}" ] || continue
+ found_agents+=("$(basename "${d}")")
+ done
+ fi
+
+ echo
+ if [ "${#found_agents[@]}" -gt 0 ]; then
+ echo "→ refreshing staged hook scripts for: ${found_agents[*]}"
+ for agent in "${found_agents[@]}"; do
+ # `install-hooks --apply` re-stages scripts AND idempotently
+ # rewrites the agent's settings.json entry. Safe to re-run:
+ # the seven hook keys we own get replaced; everything else
+ # (other hooks the user wired up) survives untouched.
+ echo " ai-memory install-hooks --agent ${agent} --apply"
+ AI_MEMORY_NO_VERSION_CHECK=1 \
+ "$0" install-hooks --agent "${agent}" --apply \
+ || echo " (skipped — re-run with the same --server-url / --auth-token used originally)"
+ done
+ else
+ echo "→ no staged hook scripts found at ${HOOKS_STAGE_DIR}"
+ echo " (nothing to refresh — install-hooks hasn't been run with --apply yet)"
+ fi
+
+ echo
+ if "${DOCKER}" ps --filter "name=^ai-memory$" --format '{{.Names}}' 2>/dev/null \
+ | grep -q '^ai-memory$'; then
+ echo "→ restart the running ai-memory container to pick up the new image:"
+ if [ -f "$(pwd)/docker/docker-compose.yml" ] \
+ || [ -f "$(pwd)/docker-compose.yml" ]; then
+ echo " docker compose up -d # if you run via compose"
+ fi
+ echo " docker stop ai-memory && docker rm ai-memory"
+ echo " # then re-run your docker-run command (see README Quick start)"
+ fi
+
+ mkdir -p "${CACHE_DIR}"
+ touch "${VERSION_CHECK_FILE}"
+}
+
+# ---- intercept wrapper-only subcommands ----------------------------------
+
+case "${1:-}" in
+ upgrade)
+ shift
+ cmd_upgrade
+ exit 0
+ ;;
+esac
+
+# ---- normal pass-through to the binary inside docker ---------------------
+
+maybe_warn_outdated || true
+
+TTY_ARGS=()
+if [ -z "${AI_MEMORY_NO_TTY:-}" ] && [ -t 0 ] && [ -t 1 ]; then
+ TTY_ARGS=(-it)
+fi
+
+ENV_ARGS=()
+for var in \
+ AI_MEMORY_AUTH_TOKEN \
+ AI_MEMORY_LLM_PROVIDER \
+ AI_MEMORY_LLM_MODEL \
+ AI_MEMORY_LLM_BASE_URL \
+ AI_MEMORY_EMBEDDING_PROVIDER \
+ AI_MEMORY_EMBEDDING_MODEL \
+ AI_MEMORY_EMBEDDING_BASE_URL \
+ AI_MEMORY_EMBEDDING_DIM \
+ AI_MEMORY_ALLOWED_HOSTS \
+ ANTHROPIC_API_KEY \
+ OPENAI_API_KEY \
+ VOYAGE_API_KEY \
+ LLM_API_KEY \
+ RUST_LOG
+do
+ if [ -n "${!var:-}" ]; then
+ ENV_ARGS+=(-e "${var}")
+ fi
+done
+
+# Mount the data dir at /data so commands that open the store
+# (status, bootstrap, search, write-page, lint, embed, …) see the
+# same content the server sees. Bind-mount a host path if the user
+# overrode AI_MEMORY_DATA_DIR; otherwise use the named volume.
+DATA_ARGS=(-e "AI_MEMORY_DATA_DIR=/data")
+if [ -n "${AI_MEMORY_DATA_DIR:-}" ] && [ -d "${AI_MEMORY_DATA_DIR}" ]; then
+ DATA_ARGS+=(-v "${AI_MEMORY_DATA_DIR}:/data")
+else
+ DATA_ARGS+=(-v "${DATA_VOLUME}:/data")
+fi
+
+# Mount $HOME at the same path inside the container so:
+# - dirs::home_dir() resolves identically (~/.claude/settings.json
+# auto-detect works without --config-file)
+# - install-hooks stages scripts into ~/.local/share/ai-memory/hooks/
+# Mount $PWD when it's outside $HOME (so install-instructions
+# --target ./CLAUDE.md and bootstrap with $PWD as repo-root work).
+PWD_ARGS=()
+case "${PWD}" in
+ "${HOME}"|"${HOME}"/*) : ;; # already covered by the $HOME mount
+ *) PWD_ARGS=(-v "${PWD}:${PWD}") ;;
+esac
+
+exec "${DOCKER}" run --rm "${TTY_ARGS[@]}" \
+ -v "${HOME}:${HOME}" \
+ "${PWD_ARGS[@]}" \
+ -w "${PWD}" \
+ -e HOME="${HOME}" \
+ -u "$(id -u):$(id -g)" \
+ "${DATA_ARGS[@]}" \
+ "${ENV_ARGS[@]}" \
+ "${IMAGE}" "$@"