Skip to content

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

Rust

docs(macos): document the launchd login service

Davi Koscianski Vidalb6fc6242ccee
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 55e4769d..b845a133 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- Added a per-user launchd agent for macOS at
+ `packaging/launchd/com.github.akitaonrails.ai-memory.plist`, the counterpart
+ of the systemd user unit, shipped in both macOS release tarballs and
+ documented in [`docs/macos.md`](docs/macos.md). Until now macOS had no
+ documented way to keep the server running once the terminal that started it
+ closed, which silently stopped hook delivery.
+
+ launchd expands nothing, so the template carries explicit
+ `__AI_MEMORY_BIN__` / `__HOME__` placeholders rather than a home specifier,
+ and passes neither `--data-dir` nor `--config` — both already resolve to the
+ macOS platform defaults. `ProcessType` is pinned to `Interactive` because
+ leaving it unset makes launchd throttle the job's CPU and I/O bandwidth,
+ which the hook ingress budget cannot absorb. A bearer token, if one is
+ configured at all, goes in the rendered plist's `EnvironmentVariables`:
+ launchd has no `EnvironmentFile` equivalent.
+
- Added `ai-memory resume`, an interactive picker for recent managed
workstreams from the current checkout and validated client-local links. It
launches the selected named workstream with the established automatic harness
diff --git a/README.md b/README.md
index 87fbe385..a15ceb6f 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@
| Area | Status | Notes |
|---|---|---|
| Linux | Supported | Primary Docker/server target and CI platform. Published Docker images support `linux/amd64` and `linux/arm64`. Native Arch/AUR packages include system and user systemd units. |
-| macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](docs/macos.md). |
+| macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries, which include a per-user launchd agent. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](docs/macos.md). |
| Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. |
| Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](docs/windows.md). |
| Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). |
diff --git a/docs/macos.md b/docs/macos.md
index 47cb8b24..31fed6a8 100644
--- a/docs/macos.md
+++ b/docs/macos.md
@@ -118,6 +118,98 @@ ai-memory install-hooks --agent claude-code --apply
The published Docker image includes both `linux/amd64` and `linux/arm64`, so
Apple Silicon pulls the native arm64 image without `--platform linux/amd64`.
+## Run as a Login Service (launchd)
+
+Every scenario above leaves the server in the foreground: close that terminal
+and capture stops. 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
+```
+
+### Coming from systemd
+
+| systemd `--user` | launchd (per-user domain) |
+|---|---|
+| `systemctl --user enable --now ai-memory` | `launchctl bootstrap gui/$(id -u) <plist>` |
+| `systemctl --user disable --now ai-memory` | `launchctl bootout gui/$(id -u)/<label>` |
+| `systemctl --user status ai-memory` | `launchctl print gui/$(id -u)/<label>` |
+| `systemctl --user restart ai-memory` | `launchctl kickstart -k gui/$(id -u)/<label>` |
+| `journalctl --user -u ai-memory -f` | `tail -f ~/Library/Logs/ai-memory/stderr.log` |
+| `loginctl enable-linger $USER` | no equivalent — a LaunchAgent stops at logout |
+| `EnvironmentFile=` | no equivalent — see the token note below |
+
+`<label>` is `com.github.akitaonrails.ai-memory`. After editing the plist,
+`bootout` then `bootstrap` again; `kickstart -k` only restarts the process and
+does not re-read the definition.
+
+### If you configure a bearer token
+
+`AI_MEMORY_AUTH_TOKEN` is read from the process environment only — it is not a
+`config.toml` key, and launchd has no `EnvironmentFile`. A single-user loopback
+setup needs no token at all. If you do set one, add it to your rendered plist
+and tighten the file, because `~/Library/LaunchAgents` is not private:
+
+```xml
+ <key>EnvironmentVariables</key>
+ <dict>
+ <key>AI_MEMORY_AUTH_TOKEN</key>
+ <string>…</string>
+ </dict>
+```
+
+```bash
+chmod 600 ~/Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist
+```
+
+### Removing the agent
+
+```bash
+launchctl bootout gui/$(id -u)/com.github.akitaonrails.ai-memory
+rm ~/Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist
+```
+
+Nothing rotates the two log files; they grow without bound. Add a
+`newsyslog.d` entry or truncate them periodically if that matters to you.
+
## Hook Platform on macOS
`AI_MEMORY_HOOK_PLATFORM` selects how hook commands are rendered. On macOS the