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.mdindex 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 andtool call now lands in ai-memory, and the next session you open inthis 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 dockerneeded), 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` fornon-Claude agents, or any other path for project-rules files(`.cursor/rules`, `.windsurfrules`, etc.). Append `--print` topreview without writing.diff --git a/bin/ai-memory b/bin/ai-memorynew file mode 100755index 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}" "$@"