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.mdindex 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 managedworkstreams from the current checkout and validated client-local links. Itlaunches the selected named workstream with the established automatic harnessdiff --git a/README.md b/README.mdindex 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.mdindex 47cb8b24..31fed6a8 100644--- a/docs/macos.md+++ b/docs/macos.md@@ -118,6 +118,98 @@ ai-memory install-hooks --agent claude-code --applyThe published Docker image includes both `linux/amd64` and `linux/arm64`, soApple 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