Skip to content

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.yml
index 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.md
echo "" >> body.md
echo "# 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.md
echo "" >> body.md
echo "# Windows x86_64 (no toolchain): download ai-memory-windows-x86_64.zip below," >> body.md
echo "# extract it, and follow the bundled docs/windows.md." >> body.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 (prebuilt
release 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 docs
table, and `docs/install.md`, and bundled it into the macOS release tarballs
alongside `docs/install.md` (mirroring how the Windows zip ships
`docs/windows.md`).
diff --git a/README.md b/README.md
index 204e3f7b..0cd0e622 100644
--- a/README.md
+++ b/README.md
@@ -258,6 +258,8 @@ ai-memory install-hooks --agent claude-code --apply
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.
+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; otherwise
diff --git a/crates/ai-memory-cli/tests/packaging.rs b/crates/ai-memory-cli/tests/packaging.rs
index 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.md
index 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 for
native macOS/Linux Claude Code installs (cargo / release binary); it uses
the 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:
```bash
cd ~/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 the
two 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 at
session boundaries; the whole-minute spool-timing overrides are shared with
Windows 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 Checklist
1. `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 and
version, and whether hooks executed or failed with a connect/resolve error.