Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(macos): align install guide with wrapper fixes
AkitaOnRails5dbebc12ea50
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 566bb0d4..7fbd97b9 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -509,7 +509,7 @@ jobs:echo "docker pull akitaonrails/ai-memory:${{ needs.validate-version.outputs.version }}" >> body.mdecho "" >> body.mdecho "# macOS aarch64/x86_64 (no toolchain): download the matching ai-memory-macos-<arch>.tar.gz below," >> body.md- echo "# extract it, and put ai-memory on PATH." >> body.md+ echo "# extract it, and follow the bundled docs/macos.md." >> body.mdecho "" >> body.mdecho "# Windows x86_64 (no toolchain): download ai-memory-windows-x86_64.zip below," >> body.mdecho "# extract it, and follow the bundled docs/windows.md." >> body.mddiff --git a/CHANGELOG.md b/CHANGELOG.mdindex be95719e..051f36ac 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -57,8 +57,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0(default 32 events).- Added [`docs/macos.md`](docs/macos.md) covering macOS install paths (prebuiltrelease binary, source build, and the Docker wrapper) and the `posix` vs- `posix-native` hook platform split, with a "Known limitations" section for the- current macOS rough edges. Linked it from the README support matrix, the docs+ `posix-native` hook platform split, with troubleshooting notes for macOS+ wrapper and hook-discovery issues. Linked it from the README support matrix, the docstable, and `docs/install.md`, and bundled it into the macOS release tarballsalongside `docs/install.md` (mirroring how the Windows zip ships`docs/windows.md`).diff --git a/README.md b/README.mdindex 204e3f7b..0cd0e622 100644--- a/README.md+++ b/README.md@@ -258,6 +258,8 @@ ai-memory install-hooks --agent claude-code --applyOn 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.+On macOS, the native release binary is also supported and recommended when you+do not need Docker; see [`docs/macos.md`](docs/macos.md).The `install-mcp` / `install-hooks` commands use`AI_MEMORY_SERVER_URL` / `AI_MEMORY_AUTH_TOKEN` when set; otherwisediff --git a/crates/ai-memory-cli/tests/packaging.rs b/crates/ai-memory-cli/tests/packaging.rsindex 73619a43..c67eadda 100644--- a/crates/ai-memory-cli/tests/packaging.rs+++ b/crates/ai-memory-cli/tests/packaging.rs@@ -181,3 +181,23 @@ fn macos_wrapper_routes_urls_by_real_subcommand() {"global options before install-hooks must not hide the real subcommand; got {args}");}++#[test]+fn macos_docs_use_valid_install_commands_and_release_body_points_to_them() {+ let docs = read_repo("docs/macos.md");+ assert!(docs.contains("install-hooks --agent claude-code --apply"));+ assert!(docs.contains("install-mcp --client claude-code --apply"));+ assert!(+ !docs.contains("setup-agent --agent claude-code --source ./hooks"),+ "setup-agent has no --apply path; use install-hooks for native macOS docs"+ );+ assert!(+ !docs.contains("init` configures the bearer token"),+ "init writes token_pepper, not a bearer token"+ );+ assert!(docs.contains("Host-side agent config should use"));+ assert!(docs.contains("Tagged releases publish a multi-arch manifest"));++ let release = read_repo(".github/workflows/release.yml");+ assert!(release.contains("follow the bundled docs/macos.md"));+}diff --git a/docs/macos.md b/docs/macos.mdindex a08eb5f0..0ec422db 100644--- a/docs/macos.md+++ b/docs/macos.md@@ -5,34 +5,30 @@ tagged releases publish native `ai-memory-macos-aarch64.tar.gz` (Apple Silicon)and `ai-memory-macos-x86_64.tar.gz` (Intel) binaries.On macOS the **native binary** (a prebuilt release or a source build) is the-recommended way to run ai-memory today. It binds the server on-`127.0.0.1:49374`, and both the MCP endpoint and the lifecycle hooks talk to-that loopback address — which the native agent can reach and which is already in-the default Host-header allowlist. The Docker wrapper is the recommended path on-Linux, but on macOS it currently has the rough edges listed under-[Known limitations](#known-limitations-on-macos); prefer the native binary until-those are resolved.+recommended way to run ai-memory. It binds the server on `127.0.0.1:49374`, and+both the MCP endpoint and the lifecycle hooks talk to that loopback address —+which the native agent can reach and which is already in the default Host-header+allowlist. The Docker wrapper is also supported when you prefer a containerised+server.Unlike Windows there is only one "path world" on macOS: POSIX paths and POSIX`.sh` hooks throughout. There is no WSL-vs-native split to get wrong.## Rule Of Thumb-Run `setup-agent` / `install-mcp` / `install-hooks` from the same shell that-launches Claude Code, Codex, Cursor, Gemini CLI, or another agent — on macOS-that is just your normal Terminal.+Run `install-mcp` / `install-hooks` from the same shell that launches Claude+Code, Codex, Cursor, Gemini CLI, or another agent — on macOS that is just your+normal Terminal.- The agent runs as a native macOS process, so its config must point at a- **host-reachable** server URL. The native binary renders- `http://127.0.0.1:49374`, which works. (The Docker wrapper renders- `http://host.docker.internal:49374`, which does **not** resolve on the macOS- host — see [Known limitations](#known-limitations-on-macos).)+ **host-reachable** server URL. Native installs and Docker-wrapper+ `install-mcp` / `install-hooks` commands render `http://127.0.0.1:49374`,+ which works from the host agent.- Hooks are rendered for one of two platforms:- `posix-native` — a direct `ai-memory hook --event …` call. The default fornative macOS/Linux Claude Code installs (cargo / release binary); it usesthe local event spool + OIDC-token fallback.- - `posix` — `sh` runs the bundled `.sh` script. The Docker wrapper's default- (the host has no local binary).+ - `posix` — `sh` runs the bundled `.sh` script. The Docker wrapper's default.Set `AI_MEMORY_HOOK_PLATFORM` before wiring hooks to override the default.@@ -59,26 +55,23 @@ tar -xzf ai-memory-macos-aarch64.tar.gz./ai-memory serve --transport http --bind 127.0.0.1:49374```-In a second terminal, stage the hook bundle and wire the agent:+In a second terminal, wire the agent:```bashcd ~/Applications/ai-memory-# `setup-agent` extracts the bundled hook scripts and writes the hook config.-# Pass --source ./hooks because the scripts ship beside the binary in the-# release tarball (see Known limitations #4).-./ai-memory setup-agent --agent claude-code --source ./hooks \- --to ~/.local/share/ai-memory/hooks --apply+# `install-hooks` auto-discovers the bundled hooks/ directory beside the binary.+./ai-memory install-hooks --agent claude-code --apply./ai-memory install-mcp --client claude-code --apply```Notes:-- The MCP endpoint and the capture hooks work without a token in this- single-user loopback setup. Admin/diagnostic routes are gated, so- `ai-memory status` needs the bearer token `init` configures for new installs —- pass `--auth-token <token>` or export `AI_MEMORY_AUTH_TOKEN`.+- The MCP endpoint, capture hooks, and `ai-memory status` work without a token+ in this single-user loopback setup. If you explicitly configure+ `AI_MEMORY_AUTH_TOKEN` for the server, pass the same token with `--auth-token`+ or export it for CLI commands.- Keep the extracted `ai-memory` at a stable path; the hook commands reference- it. Re-run `setup-agent` / `install-hooks` if you move it.+ it. Re-run `install-hooks` if you move it.## Scenario B: Source Build@@ -105,76 +98,63 @@ automatically (no `--source` needed from the repo root):## Scenario C: Docker Wrapper-The server itself runs fine in Docker on macOS; the rough edges are in how the-macOS wrapper wires the **native** agent and how its thin-client CLI reaches the-server (see [Known limitations](#known-limitations-on-macos)). If you still want-the Docker server on macOS, apply both workarounds:+Use this when you want the server data in a Docker volume while the agent still+runs as a native macOS process. The wrapper renders host-side agent config with+`http://127.0.0.1:49374`, but its own thin-client commands reach the server from+inside a helper container via Docker Desktop's `host.docker.internal` alias.```bash-# Start the server, allowlisting the Docker-Desktop host alias so the wrapper's-# own thin-client commands (status, search, …) are not rejected with 403.+# Start the server. The image default allowlist includes host.docker.internal so+# wrapper thin-client commands (status, search, …) are not rejected with 403.docker run -d --name ai-memory --restart unless-stopped \-p 127.0.0.1:49374:49374 -v ai-memory-data:/data \- -e AI_MEMORY_ALLOWED_HOSTS="localhost,127.0.0.1,::1,host.docker.internal" \akitaonrails/ai-memory:latest-# Wire the agent with an explicit loopback URL so install-mcp/install-hooks emit-# a host-reachable address instead of the unresolvable host.docker.internal.-AI_MEMORY_SERVER_URL=http://127.0.0.1:49374 \- ai-memory install-mcp --client claude-code --apply-AI_MEMORY_SERVER_URL=http://127.0.0.1:49374 \- ai-memory install-hooks --agent claude-code --apply+# Wire the native host agent. The wrapper keeps these rendered URLs on loopback.+ai-memory install-mcp --client claude-code --apply+ai-memory install-hooks --agent claude-code --apply```-On Apple Silicon the published `:latest` image currently runs as `linux/amd64`-under emulation (Docker prints a platform-mismatch warning); it works but is not-native.+The published Docker image includes both `linux/amd64` and `linux/arm64`, so+Apple Silicon pulls the native arm64 image without `--platform linux/amd64`.## Hook Platform on macOS`AI_MEMORY_HOOK_PLATFORM` selects how hook commands are rendered. On macOS thetwo relevant values are `posix-native` (direct binary call; the native default)and `posix` (the bundled `.sh` scripts; the Docker-wrapper default). Set it-before running `setup-agent` / `install-hooks` so the choice is baked into the-rendered commands. The native hook spools events locally and drains them at+before running `install-hooks` so the choice is baked into the rendered+commands. The native hook spools events locally and drains them atsession boundaries; the whole-minute spool-timing overrides are shared withWindows and documented in[`docs/windows.md`](windows.md#tuning-the-spool-timings-high-latency-instances).-## Known limitations on macOS--These were observed on Apple Silicon (macOS 26, Docker Desktop 28). Until they-are fixed, prefer the native binary (Scenario A/B).--1. **`:latest` runs under emulation on Apple Silicon.** The published `:latest`- tag currently resolves to a single `linux/amd64` image, so Docker Desktop- runs it through emulation with a platform-mismatch warning rather than- natively on `arm64`.-2. **Docker wrapper thin-client → `403 forbidden host`.** The macOS wrapper- reaches the server via `host.docker.internal`, which is not in the default- Host-header allowlist (`localhost`, `127.0.0.1`, `::1`). Add- `host.docker.internal` to `AI_MEMORY_ALLOWED_HOSTS` on the server (Scenario C).-3. **Docker wrapper renders an unreachable agent URL.** Run through the wrapper,- `install-mcp` / `install-hooks` emit `http://host.docker.internal:49374`,- which does not resolve on the macOS host — so the native agent's MCP client- and capture hooks cannot reach the server. Wire with- `AI_MEMORY_SERVER_URL=http://127.0.0.1:49374` (Scenario C).-4. **Release-binary hook discovery needs `--source`.** `setup-agent` /- `install-hooks` do not auto-locate the `hooks/` bundle that ships beside the- binary in the release tarball, so pass `--source ./hooks` (Scenario A).+## Troubleshooting on macOS++- **`403 forbidden host` from Docker-wrapper CLI commands:** update the Docker+ image and wrapper script. Current images allowlist `host.docker.internal` for+ loopback-published Docker Desktop servers.+- **Agent config points at `host.docker.internal`:** re-run `ai-memory+ install-mcp --client <client> --apply` and `ai-memory install-hooks --agent+ <agent> --apply` with the current wrapper. Host-side agent config should use+ `http://127.0.0.1:49374`.+- **Hooks bundle not found from a release archive:** ensure you extracted the+ whole tarball, not just the binary. Current `install-hooks` probes the sibling+ `hooks/` directory automatically.+- **Platform-mismatch warning on Apple Silicon:** update to a current Docker+ tag. Tagged releases publish a multi-arch manifest with `linux/arm64`.## Suggested Test Checklist1. `ai-memory serve --bind 127.0.0.1:49374` starts and logs `bind=127.0.0.1:49374`.2. `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:49374/mcp` returns`405` (reachable; GET not allowed), confirming the loopback server is up.-3. `setup-agent --agent claude-code --source ./hooks --to … --apply` extracts the- hook scripts and writes a config whose commands reference- `http://127.0.0.1:49374` and host-side `.sh` paths.+3. `install-hooks --agent claude-code --apply` writes hook commands that+ reference `http://127.0.0.1:49374` and host-side paths.4. `install-mcp --client claude-code` renders `http://127.0.0.1:49374/mcp`.5. Launch the agent, call `memory_status`, send a prompt, then confirm capture- (`ai-memory status --auth-token <token>` shows non-zero observations, or query- the SQLite `observations` table).+ (`ai-memory status` shows non-zero observations, or query the SQLite+ `observations` table).Report which scenario you used, your chip (Apple Silicon / Intel), the agent andversion, and whether hooks executed or failed with a connect/resolve error.