# macOS Support macOS is a supported platform: the workspace test suite runs on macOS CI and 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** is the recommended way to run ai-memory. Three native installs exist: - **[Scenario D: menu bar app](#scenario-d-menu-bar-app)**: a self-contained `.app` that bundles the binary, starts the LaunchAgent, and opens `/web`, status, and config. This is the GUI path if you are building from source. - **[Scenario A: prebuilt tarball](#scenario-a-prebuilt-release-binary-recommended-no-toolchain)**: no Rust toolchain; run `serve` in a terminal or install the LaunchAgent by hand. - **[Scenario B: source build](#scenario-b-source-build)**: for developing ai-memory itself. 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 ([Scenario C](#scenario-c-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, with no WSL-vs-native split. ## Rule Of Thumb Run `install-mcp` / `install-hooks` from the same shell that launches Claude Code, Codex, Cursor, Gemini CLI, or another agent. On macOS that is your normal Terminal. - The agent runs as a native macOS process, so its config must point at a **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) and the Docker wrapper's checksum-verified host client; it uses the local event spool + OIDC-token fallback and enforces capture policy v1. - `posix`: `sh` runs the bundled `.sh` script. This is an explicit compatibility fallback for the Docker wrapper. Set `AI_MEMORY_HOOK_PLATFORM` before wiring hooks to override the default. - The [menu bar app](#scenario-d-menu-bar-app) still needs `install-mcp` / `install-hooks` from a shell; use the bundled binary inside the `.app` so hook discovery sees the sibling `hooks/` tree. ## Scenario A: Prebuilt Release Binary (Recommended, No Toolchain) The shortest route is two commands: `install.sh` downloads and verifies the tarball for your chip, and `ai-memory setup` initialises the data dir, installs and starts the LaunchAgent below for you, and wires your agents: ```bash curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh ai-memory setup ``` See [`docs/install.md`](install.md#one-step-native-install-installsh--ai-memory-setup) for what each step does. The manual steps follow. Use this when you want a local server plus native hooks without a Rust toolchain or Docker. Each tagged release publishes a macOS tarball per architecture. ```bash # 1. Download the archive for your chip and extract it to a stable location. # aarch64 = Apple Silicon (M-series); x86_64 = Intel. mkdir -p ~/Applications/ai-memory && cd ~/Applications/ai-memory curl -fsSL -O https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-macos-aarch64.tar.gz tar -xzf ai-memory-macos-aarch64.tar.gz # `curl` downloads are not Gatekeeper-quarantined, so the binary runs as-is. # If you downloaded via a browser instead, clear the quarantine flag once: # xattr -d com.apple.quarantine ./ai-memory # 2. Initialise the data dir (defaults to # ~/Library/Application Support/ai-memory; override with AI_MEMORY_DATA_DIR). ./ai-memory init # 3. Start the server (loopback only). ./ai-memory serve --transport http --bind 127.0.0.1:49374 ``` > **The server from step 3 must stay running for every other command.** > `ai-memory init` only creates the data dir; it does **not** start a > server. `bootstrap`, `install-hooks`, `install-mcp`, and `status` are all > clients that talk to the running server over HTTP, so running them while > nothing is serving fails with `Connection refused (os error 61)` / > `could not reach http://localhost:49374`. Leave `serve` running in its own > terminal (or set it up as a login service, below), then run the rest in a > second terminal. In a second terminal, wire the agent: ```bash cd ~/Applications/ai-memory # `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 ``` Optionally, once hooks are wired, put the binary on `PATH` so later commands (`ai-memory status`, a fresh terminal tab, the checklist below) don't need `cd`/`./`: ```bash sudo ln -sf ~/Applications/ai-memory/ai-memory /usr/local/bin/ai-memory ``` As of v1.39.0, running `install-hooks` through the symlink works: hook discovery canonicalises the running binary's path before walking up to the sibling `hooks/` directory ([#546](https://github.com/akitaonrails/ai-memory/issues/546), fixed in v1.39.0). **On v1.38.x or older**, the walk did not resolve through a symlink: running `install-hooks` via `/usr/local/bin/ai-memory` sent discovery to the wrong parent directories, failing outright on a clean machine: ``` Error: could not locate hooks directory. Tried: ["/…/hooks/claude-code", "/usr/local/share/ai-memory/hooks/claude-code", "/usr/share/ai-memory/hooks/claude-code", "…/Library/Application Support/ai-memory/hooks/claude-code"] ``` On a machine with an earlier install it could instead silently wire a stale hooks cache from `~/Library/Application Support/ai-memory`, which is worse. If you are on an older release, run `install-hooks` via the extracted `./ai-memory` path (or upgrade). Notes: - `init` on a fresh data dir writes a root bearer token to `/auth-tokens/default`. The hooks, the CLI and `install-mcp` read it from there, so you never pass `--auth-token` locally. An install from before 3.0 keeps running without a token until `ai-memory auth enable`. - Keep the extracted `ai-memory` at a stable path; the hook commands (and the symlink, if you made one) reference it. Re-run `install-hooks` and re-point the symlink if you move it. - Later updates: with the release binary on `PATH` (or invoked as `./ai-memory`), run `ai-memory upgrade` to download the latest matching macOS tarball, verify its `.sha256`, replace the binary (and sibling `hooks/` when present), and refresh staged agent hooks. See [`docs/install.md#keeping-ai-memory-up-to-date`](install.md#keeping-ai-memory-up-to-date). ## Scenario B: Source Build Use this when developing ai-memory itself. Requires Rust 1.95 (`rust-toolchain.toml`) plus the Xcode Command Line Tools (`xcode-select --install`); SQLite is bundled and libgit2 is vendored, so no extra system libraries are needed. ```bash git clone https://github.com/akitaonrails/ai-memory cd ai-memory cargo build --release --workspace ./target/release/ai-memory init ./target/release/ai-memory serve --transport http --bind 127.0.0.1:49374 ``` From another shell in the repo, `install-hooks` finds the bundled `hooks/` automatically (no `--source` needed from the repo root): ```bash ./target/release/ai-memory install-hooks --agent claude-code --apply ./target/release/ai-memory install-mcp --client claude-code --apply ``` If you symlink the built binary onto `PATH` for convenience (e.g. `ln -sf "$(pwd)/target/release/ai-memory" ~/.local/bin/ai-memory`), do it *after* the `install-hooks` call above, not before. See the `install-hooks` symlink caution in Scenario A ([#546](https://github.com/akitaonrails/ai-memory/issues/546)); it applies here too and is the exact layout that bug was filed against. `install.sh` leaves such a link alone and stops, so remove it first if you later switch to the release install. ## Scenario C: Docker Wrapper 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. This assumes the `ai-memory` thin-client wrapper is already on `PATH`; if `ai-memory --version` doesn't resolve yet, install it first via the [README Docker quick-start](../README.md#docker) (downloads a small shell script to `~/.local/bin/ai-memory`). On a stock macOS Terminal `~/.local/bin` is **not** on `PATH` by default; add `export PATH="$HOME/.local/bin:$PATH"` to `~/.zshrc` if `which ai-memory` comes up empty after installing the wrapper. ```bash # 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 \ akitaonrails/ai-memory:latest # 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 ``` The wrapper is a shell script, not the native binary, so the `install-hooks` symlink caution above (#546) does not apply here. The published Docker image includes both `linux/amd64` and `linux/arm64`, so Apple Silicon pulls the native arm64 image without `--platform linux/amd64`. ## Scenario D: Menu bar app Use this when you want a self-contained macOS install: one `.app` that contains the `ai-memory` binary and `hooks/`, starts the existing LaunchAgent, and opens the surfaces the tool already has (`/web`, `ai-memory status`, `config.toml`, logs). It does not replace those tools with a second dashboard. From a source checkout (Rust 1.95 + Xcode / Swift 6): ```bash ./companions/ai-memory-macos/build.sh open "companions/ai-memory-macos/dist/AI Memory.app" ``` Drag `AI Memory.app` to `/Applications` so the LaunchAgent path stays stable across rebuilds. The menu extra has no Dock icon. 1. **Install & Start Server** runs bundled `ai-memory init` if `~/Library/Application Support/ai-memory/config.toml` is missing, renders `packaging/launchd/com.github.akitaonrails.ai-memory.plist`, and bootstraps the same `com.github.akitaonrails.ai-memory` label as the hand-installed LaunchAgent below. Do not skip this click; the app does not start the server on first launch by itself. 2. The status item is green when `GET /admin/status` succeeds, yellow when the server is up but the LLM/embedding role is in error or the write queue is non-empty, red when the server is unreachable. The app sends the token saved in Settings only to the server it was saved for, so changing the URL does not carry it to a different host; when no token is saved it sends the one `init` wrote to `auth-tokens/default` in its data dir, but only to a loopback server, so an install the app initialized needs no pasting. A token saved for another server is not sent, and Settings says so with a **Clear saved token** button. 3. **Open Web UI**, **Show Status…**, **Open Config**, **Open Data Directory**, and **Open Logs** call the existing browser UI, the bundled CLI, and Finder. After adding, changing, or clearing the data-directory override in Settings, choose **Restart Server** to reload the LaunchAgent with that selection. Existing files stay in their original directory. Wire an agent with the **bundled** binary so `install-hooks` finds the sibling `hooks/` tree (#546): ```bash BIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory" "$BIN" install-mcp --client claude-code --apply "$BIN" install-hooks --agent claude-code --apply ``` Memory, config, models, and logs stay outside the bundle (`~/Library/Application Support/ai-memory` and `~/Library/Logs/ai-memory`). Replacing the `.app` is an update; it does not rewrite that tree. Details: [`companions/ai-memory-macos/README.md`](../companions/ai-memory-macos/README.md). Notarization and a Homebrew cask are not part of this companion yet. ## Run as a Login Service (launchd) Scenarios A–C leave the server in the foreground: close that terminal and capture stops. Scenario D already installs this LaunchAgent from **Install & Start Server**. The macOS counterpart of a systemd user unit is a **LaunchAgent**: a plist in `~/Library/LaunchAgents/` that the per-user launchd domain starts at login and restarts on failure. The repo ships one at `packaging/launchd/com.github.akitaonrails.ai-memory.plist`, and the macOS release tarballs include it. launchd expands nothing. A plist has no home specifier and no `EnvironmentFile`, so every path in it is a literal and the template carries two placeholders you substitute at install time. Run this from the extracted tarball (Scenario A) or the repo root (Scenario B): ```bash # launchd creates the log files but not their parent directory, and a missing # one is a silent redirect failure. mkdir -p ~/Library/Logs/ai-memory # Wherever you keep the binary: ~/Applications/ai-memory/ai-memory for a # release tarball, ./target/release/ai-memory for a source build. AI_MEMORY_BIN=~/Applications/ai-memory/ai-memory sed -e "s|__AI_MEMORY_BIN__|$AI_MEMORY_BIN|" \ -e "s|__HOME__|$HOME|" \ packaging/launchd/com.github.akitaonrails.ai-memory.plist \ > ~/Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist launchctl bootstrap gui/$(id -u) \ ~/Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist ``` The agent runs `ai-memory serve --transport http --enable-web` and passes neither `--data-dir` nor `--config`: on macOS the binary already defaults to `~/Library/Application Support/ai-memory` with the config file inside it, so naming them would only add two more paths to substitute. `bind` comes from that config, defaulting to `127.0.0.1:49374`. Re-render and reload the plist if you move the binary. Verify it came up: ```bash launchctl print gui/$(id -u)/com.github.akitaonrails.ai-memory | grep state curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:49374/mcp # 405 tail -f ~/Library/Logs/ai-memory/stderr.log ``` ### Privacy controls and Full Disk Access The server looks at each hook event's working directory (git discovery) to decide which project the event belongs to. A LaunchAgent is a background process under macOS privacy controls (TCC): reading inside `~/Documents`, `~/Desktop`, `~/Downloads`, iCloud Drive, or an external or network volume can need a permission that a background agent has no way to ask for, and the read can hang instead of failing. A server started from a terminal or an SSH session borrows that app's permissions, which is why the same binary can work there and not under launchd. The server keeps answering when this happens: it runs those reads off its request threads with a 2-second limit. Events from a directory it cannot read are dropped, and `stderr.log` shows `inspecting cwd "" did not finish within 2s` for each one. At most four of those reads wait at a time, so while a directory stays blocked, events from a project the server has not seen yet can be dropped too; projects it already knows keep working. If your agents work in one of those places, give the binary the plist runs Full Disk Access, then restart the agent: ```bash # The binary the LaunchAgent runs: plutil -extract ProgramArguments.0 raw \ ~/Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist # System Settings > Privacy & Security > Full Disk Access: click +, press # Cmd+Shift+G and paste that path. Then: launchctl kickstart -k gui/$(id -u)/com.github.akitaonrails.ai-memory ``` The grant belongs to that file path. If `setup` later points the plist at a different binary, grant that one too. ### Coming from systemd | systemd `--user` | launchd (per-user domain) | |---|---| | `systemctl --user enable --now ai-memory` | `launchctl bootstrap gui/$(id -u) ` | | `systemctl --user disable --now ai-memory` | `launchctl bootout gui/$(id -u)/