Skip to content

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

Rust

feat(packaging): add a launchd user agent for macOS

Davi Koscianski Vidal7619c427dbb4
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 41721ff1..7e6606de 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -144,9 +144,10 @@ jobs:
TAILWIND_SKIP: "1"
run: cargo build --release -p ai-memory-cli
- # Mirrors the Linux tarball, minus Linux-only service assets
- # (packaging/systemd|sysusers|tmpfiles|env). macOS users get the binary,
- # hooks bundle, default config template, and the docs a macOS user needs
+ # Mirrors the Linux tarball, swapping the Linux-only service assets
+ # (packaging/systemd|sysusers|tmpfiles|env) for the macOS-only
+ # packaging/launchd agent. macOS users get the binary, hooks bundle,
+ # default config template, and the docs a macOS user needs
# (install.md + macos.md).
- name: Create release tarball
env:
@@ -157,6 +158,8 @@ jobs:
mkdir -p "dist/$artifact"
cp target/release/ai-memory "dist/$artifact/ai-memory"
cp -a hooks "dist/$artifact/hooks"
+ mkdir -p "dist/$artifact/packaging"
+ cp -a packaging/launchd "dist/$artifact/packaging/launchd"
mkdir -p "dist/$artifact/crates/ai-memory-cli/templates"
cp crates/ai-memory-cli/templates/config.default.toml \
"dist/$artifact/crates/ai-memory-cli/templates/config.default.toml"
@@ -179,6 +182,7 @@ jobs:
"$smoke/ai-memory" --version
for path in \
hooks \
+ packaging/launchd/com.github.akitaonrails.ai-memory.plist \
crates/ai-memory-cli/templates/config.default.toml \
docs/install.md \
docs/macos.md \
diff --git a/crates/ai-memory-cli/tests/packaging.rs b/crates/ai-memory-cli/tests/packaging.rs
index 5b1c6ff9..379cceab 100644
--- a/crates/ai-memory-cli/tests/packaging.rs
+++ b/crates/ai-memory-cli/tests/packaging.rs
@@ -122,6 +122,75 @@ fn systemd_units_use_explicit_native_paths() {
assert!(!user.contains("/var/lib/ai-memory"));
}
+const LAUNCHD_AGENT_PLIST: &str = "packaging/launchd/com.github.akitaonrails.ai-memory.plist";
+
+#[test]
+fn launchd_agent_plist_is_home_independent_and_unthrottled() {
+ let agent = read_repo(LAUNCHD_AGENT_PLIST);
+
+ // launchd expands nothing: no %h, no $HOME, no ~. Every path in a plist is
+ // a literal, so the two the template cannot know stay placeholders.
+ assert!(agent.contains("__AI_MEMORY_BIN__"));
+ assert!(agent.contains("__HOME__/Library/Logs/ai-memory/"));
+ for unexpandable in ["%h", "$HOME", "${HOME}", "~/"] {
+ assert!(
+ !agent.contains(unexpandable),
+ "launchd would take {unexpandable} literally instead of expanding it"
+ );
+ }
+
+ // The macOS data dir and the config file inside it are already the binary's
+ // defaults, so passing them would only reintroduce a home-dependent path.
+ assert!(!agent.contains("--data-dir"));
+ assert!(!agent.contains("--config"));
+
+ // An unset ProcessType makes launchd throttle CPU and I/O bandwidth, which
+ // the hook ingress budget cannot absorb. Adaptive keys off XPC
+ // transactions, which ai-memory never opens, so it decays to Background.
+ assert!(agent.contains("<key>ProcessType</key>\n <string>Interactive</string>"));
+
+ assert!(agent.contains("<key>RunAtLoad</key>\n <true/>"));
+ assert!(agent.contains("<key>KeepAlive</key>\n <true/>"));
+
+ // launchctl addresses the job by Label, so a Label that disagrees with the
+ // filename silently invalidates every bootout/kickstart command we publish.
+ let label = Path::new(LAUNCHD_AGENT_PLIST)
+ .file_stem()
+ .and_then(|stem| stem.to_str())
+ .expect("the plist path has a file stem");
+ assert!(agent.contains(&format!("<key>Label</key>\n <string>{label}</string>")));
+}
+
+// Substring assertions cannot see malformed XML, and a plist launchd refuses to
+// parse fails at bootstrap time with no useful diagnostic.
+#[cfg(target_os = "macos")]
+#[test]
+fn launchd_agent_plist_is_a_valid_property_list() {
+ let path = repo_root().join(LAUNCHD_AGENT_PLIST);
+ let output = Command::new("plutil")
+ .arg("-lint")
+ .arg(&path)
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "plutil -lint rejected {}: {}{}",
+ path.display(),
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+}
+
+#[test]
+fn macos_release_tarball_ships_the_launchd_agent_plist() {
+ let release = read_repo(".github/workflows/release.yml");
+ assert!(release.contains("cp -a packaging/launchd \"dist/$artifact/packaging/launchd\""));
+ assert!(
+ release.contains(LAUNCHD_AGENT_PLIST),
+ "the macOS tarball smoke test must prove the plist actually shipped"
+ );
+}
+
#[test]
fn aur_packages_install_all_native_assets() {
for path in ["packaging/aur/PKGBUILD", "packaging/aur/PKGBUILD-bin"] {
diff --git a/packaging/launchd/com.github.akitaonrails.ai-memory.plist b/packaging/launchd/com.github.akitaonrails.ai-memory.plist
new file mode 100644
index 00000000..2eed910e
--- /dev/null
+++ b/packaging/launchd/com.github.akitaonrails.ai-memory.plist
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+ Per-user LaunchAgent for ai-memory, the macOS counterpart of
+ packaging/systemd/ai-memory-user.service.
+
+ launchd expands nothing: it has no systemd-style home specifier and no
+ EnvironmentFile, so both placeholders below must be substituted before the
+ file is installed into the user's LaunchAgents directory. See docs/macos.md
+ for the render command.
+
+ __AI_MEMORY_BIN__ absolute path to the ai-memory binary
+ __HOME__ absolute path to the user's home directory
+
+ The data dir and its config file are deliberately not passed: on macOS the
+ binary already defaults to Library/Application Support/ai-memory under the
+ user's home, so spelling them out would only add two more paths to
+ substitute.
+-->
+<plist version="1.0">
+<dict>
+ <key>Label</key>
+ <string>com.github.akitaonrails.ai-memory</string>
+
+ <key>ProgramArguments</key>
+ <array>
+ <string>__AI_MEMORY_BIN__</string>
+ <string>serve</string>
+ <string>--transport</string>
+ <string>http</string>
+ <string>--enable-web</string>
+ </array>
+
+ <key>RunAtLoad</key>
+ <true/>
+ <key>KeepAlive</key>
+ <true/>
+
+ <!-- Left unset, launchd throttles the job's CPU and I/O bandwidth, which the
+ hook ingress budget cannot absorb. Adaptive keys off XPC transactions
+ ai-memory never opens, so it would decay to Background. -->
+ <key>ProcessType</key>
+ <string>Interactive</string>
+
+ <!-- launchd creates these files but not their parent directory. -->
+ <key>StandardOutPath</key>
+ <string>__HOME__/Library/Logs/ai-memory/stdout.log</string>
+ <key>StandardErrorPath</key>
+ <string>__HOME__/Library/Logs/ai-memory/stderr.log</string>
+</dict>
+</plist>