Skip to content

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

Rust

Add a macOS menu bar companion that bundles and governs the server.

Thiago Macedoeadab8e4bd85
diff --git a/.github/workflows/macos-app.yml b/.github/workflows/macos-app.yml
new file mode 100644
index 00000000..1eb3e06d
--- /dev/null
+++ b/.github/workflows/macos-app.yml
@@ -0,0 +1,22 @@
+name: macos-app
+
+on:
+ pull_request:
+ types: [opened, synchronize, reopened, labeled]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ swift-test:
+ name: swift test (ai-memory-macos)
+ if: >-
+ github.event_name == 'workflow_dispatch' ||
+ contains(github.event.pull_request.labels.*.name, 'macos') ||
+ contains(github.event.pull_request.labels.*.name, 'full-ci')
+ runs-on: macos-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ - name: Swift tests
+ run: swift test --package-path companions/ai-memory-macos
diff --git a/.gitignore b/.gitignore
index 30308091..4ca1a335 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,9 @@
# Rust build artefacts.
/target/
/companions/*/target/
+/companions/*/.build/
+/companions/*/.swiftpm/
+/companions/*/dist/
/dist/
**/*.rs.bk
**/*.rs.orig
diff --git a/AGENTS.md b/AGENTS.md
index 0d9a55cd..d0fe8921 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -197,6 +197,9 @@ evals/ live A/B harness; workspace member, not shipped.
companions/ai-memory-importer/ standalone OMC + external-conversation importer; NOT a root
workspace member — build/test it with
`--manifest-path companions/ai-memory-importer/Cargo.toml`.
+companions/ai-memory-macos/ Swift menu bar wrapper; NOT a root workspace member —
+ `swift test --package-path companions/ai-memory-macos`
+ and `./companions/ai-memory-macos/build.sh`.
hooks/ per-agent lifecycle hook bundles (shell/native).
bin/ host wrapper scripts (`ai-memory`, `deploy`, `release`).
docker/ Dockerfile, compose files, TLS proxy templates.
@@ -272,6 +275,10 @@ no tiers.
`cargo test --manifest-path companions/ai-memory-importer/Cargo.toml`
(plus fmt/clippy on the same manifest). Root `--workspace` commands do
not cover it.
+- Run the macOS menu bar companion separately:
+ `swift test --package-path companions/ai-memory-macos`
+ (plus `./companions/ai-memory-macos/build.sh` to stage `AI Memory.app`).
+ Root `--workspace` commands do not cover it.
### Platform notes
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c59817a..8d8ae5de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+- macOS menu bar companion (`companions/ai-memory-macos`) that bundles the
+ `ai-memory` binary and `hooks/` tree, governs the existing LaunchAgent, and
+ opens the built-in web UI, `ai-memory status`, `config.toml`, the data
+ directory, and logs. Durable memory stays in
+ `~/Library/Application Support/ai-memory`; replacing the `.app` does not
+ rewrite it. Documented as a README quick-start, an
+ [`install.md`](docs/install.md#macos-menu-bar-app) path, a cookbook
+ recipe, and [`docs/macos.md`](docs/macos.md) Scenario D.
+
### Security
- Bumped `rmcp` to 2.x (2.2.0), resolving three MCP transport advisories:
GHSA-9pj6-vhgr-3mwh (unauthenticated Streamable-HTTP session-table leak /
diff --git a/README.md b/README.md
index 59e769ef..d9b27be4 100644
--- a/README.md
+++ b/README.md
@@ -186,6 +186,37 @@ System service installs use `/var/lib/ai-memory` and `/etc/ai-memory/` via the
packaged unit. Full user-service, system-service, auth, and provider setup is in
[`docs/install.md#arch-linux-native-packages-aur`](docs/install.md#arch-linux-native-packages-aur).
+### macOS (menu bar app)
+
+A self-contained `.app` that bundles the native `ai-memory` binary and
+`hooks/` tree, starts the existing LaunchAgent, and opens `/web`,
+`ai-memory status`, and `config.toml` from the menu bar. Wiki, SQLite,
+config, and models stay in `~/Library/Application Support/ai-memory`, so
+replacing the app is an update — it does not rewrite that tree.
+
+Needs a Rust toolchain and Xcode / Swift 6 (same as a source build):
+
+```bash
+git clone https://github.com/akitaonrails/ai-memory
+cd ai-memory
+./companions/ai-memory-macos/build.sh
+open "companions/ai-memory-macos/dist/AI Memory.app"
+```
+
+Drag **AI Memory.app** to `/Applications`, then **Install & Start Server**
+from the menu extra (no Dock icon). When the status item is green, wire an
+agent with the bundled binary:
+
+```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
+```
+
+Prebuilt tarball and launchd-without-the-app paths:
+[`docs/macos.md`](docs/macos.md). Companion details:
+[`companions/ai-memory-macos`](companions/ai-memory-macos).
+
### Docker
You need: Docker or Podman + an agent CLI from the [Support Matrix](#support-matrix),
@@ -259,8 +290,9 @@ wrapper automatically uses Podman when Docker is not installed. Set
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).
+On macOS the native binary is the recommended path when you do not need
+Docker — either the [menu bar app](#macos-menu-bar-app) above or a
+[release tarball / launchd agent](docs/macos.md).
Wiring another agent is the same two commands with a different name —
`--client codex`, `--agent codex`, and so on for every row of the support
@@ -386,7 +418,7 @@ diagram, crate breakdown, schema notes, and invariants.
| [`docs/agent-messaging.md`](docs/agent-messaging.md) | Cross-project agent-to-agent messaging: a directed, claim-once inbox/queue plus the on-start "you have mail" notice. |
| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation. |
| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: default single-slot routing, session-aware isolation, and multi-user `per_actor` behavior. |
-| [`docs/macos.md`](docs/macos.md) | macOS install paths: native release binary (recommended), source build, the Docker wrapper, and current limitations. |
+| [`docs/macos.md`](docs/macos.md) | macOS install paths: menu bar app, native release tarball, source build, Docker wrapper, launchd, and current limitations. |
| [`docs/windows.md`](docs/windows.md) | Windows install modes: full WSL2, native Windows with Docker Desktop, prebuilt native release zip, native source builds, and caveats. |
| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes, handoff-injection limits, and community bridge guidance. |
| [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, pointers to the TLS guide. |
diff --git a/companions/ai-memory-macos/.gitignore b/companions/ai-memory-macos/.gitignore
new file mode 100644
index 00000000..29dd70f4
--- /dev/null
+++ b/companions/ai-memory-macos/.gitignore
@@ -0,0 +1,5 @@
+.build/
+.swiftpm/
+dist/
+*.xcodeproj/xcuserdata/
+*.xcworkspace/xcuserdata/
diff --git a/companions/ai-memory-macos/Info.plist b/companions/ai-memory-macos/Info.plist
new file mode 100644
index 00000000..5a08874d
--- /dev/null
+++ b/companions/ai-memory-macos/Info.plist
@@ -0,0 +1,39 @@
+<?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">
+<plist version="1.0">
+<dict>
+ <key>CFBundleDevelopmentRegion</key>
+ <string>en</string>
+ <key>CFBundleExecutable</key>
+ <string>AIMemoryMenu</string>
+ <key>CFBundleIdentifier</key>
+ <string>com.github.akitaonrails.ai-memory-menu</string>
+ <key>CFBundleInfoDictionaryVersion</key>
+ <string>6.0</string>
+ <key>CFBundleName</key>
+ <string>AI Memory</string>
+ <key>CFBundleDisplayName</key>
+ <string>AI Memory</string>
+ <key>CFBundlePackageType</key>
+ <string>APPL</string>
+ <key>CFBundleShortVersionString</key>
+ <string>1.0.0</string>
+ <key>CFBundleVersion</key>
+ <string>1</string>
+ <key>LSMinimumSystemVersion</key>
+ <string>14.0</string>
+ <key>LSUIElement</key>
+ <true/>
+ <key>NSHighResolutionCapable</key>
+ <true/>
+ <key>NSPrincipalClass</key>
+ <string>NSApplication</string>
+ <key>NSAppTransportSecurity</key>
+ <dict>
+ <key>NSAllowsLocalNetworking</key>
+ <true/>
+ <key>NSAllowsArbitraryLoads</key>
+ <true/>
+ </dict>
+</dict>
+</plist>
diff --git a/companions/ai-memory-macos/Package.swift b/companions/ai-memory-macos/Package.swift
new file mode 100644
index 00000000..c3d63375
--- /dev/null
+++ b/companions/ai-memory-macos/Package.swift
@@ -0,0 +1,28 @@
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+ name: "AIMemoryMenu",
+ platforms: [.macOS(.v14)],
+ products: [
+ .executable(name: "AIMemoryMenu", targets: ["AIMemoryMenu"]),
+ ],
+ targets: [
+ .target(
+ name: "AIMemoryMenuCore",
+ path: "Sources/AIMemoryMenuCore"
+ ),
+ .executableTarget(
+ name: "AIMemoryMenu",
+ dependencies: ["AIMemoryMenuCore"],
+ path: "Sources/AIMemoryMenu"
+ ),
+ .testTarget(
+ name: "AIMemoryMenuTests",
+ dependencies: ["AIMemoryMenuCore"],
+ path: "Tests/AIMemoryMenuTests",
+ resources: [.copy("fixtures")]
+ ),
+ ]
+)
diff --git a/companions/ai-memory-macos/README.md b/companions/ai-memory-macos/README.md
new file mode 100644
index 00000000..4be08de9
--- /dev/null
+++ b/companions/ai-memory-macos/README.md
@@ -0,0 +1,59 @@
+# AI Memory (macOS menu bar)
+
+Self-contained macOS accessory app that **ships the `ai-memory` runtime**, **governs the LaunchAgent**, and **opens the surfaces the tool already has**. It is a wrapper, not a second operator console.
+
+This companion is not a root Cargo workspace member. Durable memory stays in the user data directory so replacing the `.app` does not rewrite wiki, SQLite, config, models, or logs.
+
+| In the `.app` (replaceable) | In the user data dir (survives updates) |
+|---|---|
+| Swift menu bar UI | wiki, SQLite, `config.toml` |
+| `ai-memory` binary | hook spool, `auth.json`, capture-mode |
+| bundled `hooks/` | downloaded embedding models |
+| LaunchAgent template | rendered plist in `~/Library/LaunchAgents/` |
+| | logs in `~/Library/Logs/ai-memory/` |
+
+Data directory: `~/Library/Application Support/ai-memory` (the binary’s existing macOS default). Optional override in Settings writes `AI_MEMORY_DATA_DIR` into the LaunchAgent plist only.
+
+This app does **not** replace `ai-memory status`, `/web`, or hand-editing `config.toml`. Those stay the real tools; the menu opens them.
+
+## Build
+
+From the repository root (needs a Rust toolchain and Xcode / Swift 6):
+
+```bash
+chmod +x companions/ai-memory-macos/build.sh
+./companions/ai-memory-macos/build.sh
+open "companions/ai-memory-macos/dist/AI Memory.app"
+```
+
+`build.sh` compiles `ai-memory` with Cargo, compiles the Swift menu extra, and stages:
+
+```text
+AI Memory.app/Contents/Resources/runtime/
+ ai-memory
+ hooks/
+ packaging/launchd/com.github.akitaonrails.ai-memory.plist
+```
+
+Drag the `.app` to `/Applications` for a stable LaunchAgent path. Notarization, Developer ID, and a Homebrew cask are out of this companion’s first version.
+
+## Use
+
+1. Open the app (menu bar extra; no Dock icon).
+2. **Install & Start Server** — runs bundled `ai-memory init` if `config.toml` is missing, renders the existing launchd template, and `launchctl bootstrap`s `com.github.akitaonrails.ai-memory`.
+3. The status item turns green when `GET /admin/status` succeeds.
+4. **Open Web UI**, **Show Status…** (bundled `ai-memory status`), **Open Config**, **Open Data Directory**, **Open Logs**.
+
+Updates: replace `/Applications/AI Memory.app`. The data dir is untouched. If the helper path inside the bundle changed, **Restart Server** re-renders the plist.
+
+## Tests
+
+```bash
+swift test --package-path companions/ai-memory-macos
+```
+
+Root `cargo t` / `cargo tf` do not cover this package.
+
+## Open in Xcode
+
+Open `companions/ai-memory-macos/Package.swift`. `swift run` from the package directory will not include the staged runtime; use `build.sh` (or set `AI_MEMORY_MENU_RUNTIME` at the tarball-equivalent `runtime/` directory) to govern the service.
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenu/App.swift b/companions/ai-memory-macos/Sources/AIMemoryMenu/App.swift
new file mode 100644
index 00000000..55c60216
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenu/App.swift
@@ -0,0 +1,32 @@
+import AppKit
+import SwiftUI
+import AIMemoryMenuCore
+
+@main
+struct AIMemoryMenuApp: App {
+ @State private var model = AppModel()
+
+ init() {
+ NSApplication.shared.setActivationPolicy(.accessory)
+ }
+
+ var body: some Scene {
+ MenuBarExtra {
+ MenuBarView()
+ .environment(model)
+ } label: {
+ MenuBarLabel(icon: model.icon)
+ }
+ .menuBarExtraStyle(.menu)
+
+ Window("Status", id: "status") {
+ StatusOutputView()
+ .environment(model)
+ }
+
+ Settings {
+ SettingsView()
+ .environment(model)
+ }
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenu/AppModel.swift b/companions/ai-memory-macos/Sources/AIMemoryMenu/AppModel.swift
new file mode 100644
index 00000000..2fb705fa
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenu/AppModel.swift
@@ -0,0 +1,329 @@
+import AppKit
+import Foundation
+import AIMemoryMenuCore
+import Observation
+
+@MainActor
+@Observable
+final class AppModel {
+ var settings: AppSettings
+ var report: StatusReport?
+ var launchd: LaunchdState = .notInstalled
+ var icon: IconState = .unknown
+ var lastError: String?
+ var statusOutput: String = ""
+ var isBusy = false
+ var runtimeMissing = false
+ var tokenConfigured = false
+ var lastHTTPStatus: Int?
+
+ @ObservationIgnored private var tokenStore: any TokenStore
+ @ObservationIgnored private var health = HealthClient()
+ @ObservationIgnored private var runner: any CommandRunning
+ @ObservationIgnored private var pollTask: Task<Void, Never>?
+ @ObservationIgnored private var fetchFailed = false
+ @ObservationIgnored private var startingDeadline: Date?
+
+ init(
+ settings: AppSettings = .load(),
+ tokenStore: any TokenStore = KeychainTokenStore(),
+ runner: any CommandRunning = ProcessRunner()
+ ) {
+ self.settings = settings
+ self.tokenStore = tokenStore
+ self.runner = runner
+ self.tokenConfigured = tokenStore.read()?.isEmpty == false
+ startPolling()
+ }
+
+ var headlineVersion: String {
+ switch icon {
+ case .ok:
+ if let report {
+ return "Server running · v\(report.version)"
+ }
+ return "Server running"
+ case .degraded:
+ return "Server running · warnings"
+ case .authRequired:
+ return "Server running · auth required"
+ case .starting:
+ return "Server is starting…"
+ case .unreachable:
+ return launchd == .running ? "LaunchAgent up · server unreachable" : "Server down"
+ case .notInstalled:
+ return "LaunchAgent not installed"
+ case .unknown:
+ return "Checking server…"
+ }
+ }
+
+ var statisticLines: [String] {
+ guard let report else {
+ return []
+ }
+ return report.statisticLines
+ }
+
+ var showsServerStatus: Bool {
+ report != nil
+ }
+
+ var dataDir: URL {
+ settings.resolvedDataDir
+ }
+
+ var configURL: URL {
+ dataDir.appending(path: "config.toml")
+ }
+
+ var logURL: URL {
+ FileManager.default.homeDirectoryForCurrentUser
+ .appending(path: "Library/Logs/ai-memory/stderr.log")
+ }
+
+ func startPolling() {
+ guard pollTask == nil else { return }
+ pollTask = Task { [weak self] in
+ while let self, !Task.isCancelled {
+ await self.poll()
+ let interval: Duration = self.icon == .starting ? .seconds(1) : .seconds(15)
+ try? await Task.sleep(for: interval)
+ }
+ }
+ }
+
+ func poll() async {
+ let controller = launchdController()
+ launchd = controller.state()
+ lastHTTPStatus = nil
+ do {
+ report = try await health.fetch(baseURL: settings.serverURL, token: tokenStore.read())
+ fetchFailed = false
+ lastError = nil
+ } catch {
+ report = nil
+ fetchFailed = true
+ if let health = error as? HealthError, case let .http(code) = health {
+ lastHTTPStatus = code
+ fetchFailed = code != 401 && code != 403
+ }
+ lastError = (error as? HealthError).map(Self.describe) ?? error.localizedDescription
+ }
+ let derived = IconState.derived(
+ launchd: launchd,
+ report: report,
+ fetchFailed: fetchFailed,
+ httpStatus: lastHTTPStatus
+ )
+ let starting = startingDeadline.map { Date() < $0 } ?? false
+ icon = IconState.applyingStartGrace(derived, isStarting: starting)
+ if icon != .starting {
+ startingDeadline = nil
+ }
+ runtimeMissing = RuntimeLayout.resolve() == nil
+ tokenConfigured = tokenStore.read()?.isEmpty == false
+ }
+
+ func installAndStart() async {
+ markStarting()
+ await runBusy {
+ let runtime = try self.requireRuntime()
+ let controller = self.launchdController()
+ if FirstRun.needsInit(dataDir: self.dataDir) {
+ _ = try BundledCLI(runtime: runtime, runner: self.runner).initDataDir(self.dataDir)
+ }
+ let template = try String(contentsOf: runtime.plistTemplate, encoding: .utf8)
+ if controller.state() == .running {
+ try? controller.bootout()
+ }
+ try controller.writePlist(
+ template: template,
+ binary: runtime.binary,
+ dataDir: self.settings.dataDirOverride
+ )
+ try controller.bootstrap()
+ }
+ clearStartingIfFailed()
+ await poll()
+ }
+
+ func start() async {
+ markStarting()
+ await runBusy {
+ let runtime = try self.requireRuntime()
+ let controller = self.launchdController()
+ let template = try String(contentsOf: runtime.plistTemplate, encoding: .utf8)
+ try controller.writePlist(
+ template: template,
+ binary: runtime.binary,
+ dataDir: self.settings.dataDirOverride
+ )
+ try controller.bootstrap()
+ }
+ clearStartingIfFailed()
+ await poll()
+ }
+
+ func stop() async {
+ startingDeadline = nil
+ await runBusy {
+ try self.launchdController().bootout()
+ }
+ await poll()
+ }
+
+ func restart() async {
+ markStarting()
+ await runBusy {
+ let controller = self.launchdController()
+ let runtime = try self.requireRuntime()
+ let installed = (try? String(contentsOf: controller.plistDestination, encoding: .utf8)) ?? ""
+ if LaunchdController.programArgumentsBinary(inPlist: installed) != runtime.binary.path {
+ try? controller.bootout()
+ let template = try String(contentsOf: runtime.plistTemplate, encoding: .utf8)
+ try controller.writePlist(
+ template: template,
+ binary: runtime.binary,
+ dataDir: self.settings.dataDirOverride
+ )
+ try controller.bootstrap()
+ } else {
+ try controller.kickstart()
+ }
+ }
+ clearStartingIfFailed()
+ await poll()
+ }
+
+ func refreshStatusOutput() async {
+ await runBusy {
+ let runtime = try self.requireRuntime()
+ let result = try BundledCLI(runtime: runtime, runner: self.runner).status(
+ serverURL: self.settings.serverURL,
+ token: self.tokenStore.read(),
+ dataDir: self.settings.dataDirOverride
+ )
+ self.statusOutput = result.combinedOutput
+ }
+ }
+
+ func openWebUI() {
+ NSWorkspace.shared.open(HealthURL.webUI(from: settings.serverURL))
+ }
+
+ func openConfig() {
+ revealOrOpen(configURL)
+ }
+
+ func openDataDirectory() {
+ NSWorkspace.shared.open(dataDir)
+ }
+
+ func openLogs() {
+ revealOrOpen(logURL)
+ }
+
+ func saveSettings(
+ serverURLString: String,
+ dataDirOverride: String,
+ token: String?,
+ clearToken: Bool
+ ) {
+ if let url = URL(string: serverURLString), url.scheme != nil {
+ settings.serverURL = url
+ }
+ let trimmed = dataDirOverride.trimmingCharacters(in: .whitespacesAndNewlines)
+ settings.dataDirOverride = trimmed.isEmpty ? nil : URL(fileURLWithPath: trimmed)
+ settings.save()
+ if clearToken {
+ try? tokenStore.clear()
+ } else if let token {
+ let value = token.trimmingCharacters(in: .whitespacesAndNewlines)
+ if !value.isEmpty {
+ try? tokenStore.save(value)
+ }
+ }
+ tokenConfigured = tokenStore.read()?.isEmpty == false
+ Task { await poll() }
+ }
+
+ private func markStarting() {
+ startingDeadline = Date().addingTimeInterval(45)
+ icon = .starting
+ report = nil
+ lastError = nil
+ pollTask?.cancel()
+ pollTask = nil
+ startPolling()
+ }
+
+ private func clearStartingIfFailed() {
+ if lastError != nil {
+ startingDeadline = nil
+ }
+ }
+
+ private func launchdController() -> LaunchdController {
+ LaunchdController(home: FileManager.default.homeDirectoryForCurrentUser, runner: runner)
+ }
+
+ private func requireRuntime() throws -> RuntimeLayout {
+ guard let runtime = RuntimeLayout.resolve() else {
+ runtimeMissing = true
+ throw CliError.missingRuntime
+ }
+ return runtime
+ }
+
+ private func runBusy(_ work: () throws -> Void) async {
+ isBusy = true
+ defer { isBusy = false }
+ do {
+ try work()
+ lastError = nil
+ } catch {
+ lastError = error.localizedDescription
+ if let cli = error as? CliError, case .failed(_, let output) = cli {
+ statusOutput = output
+ lastError = output
+ }
+ }
+ }
+
+ private func revealOrOpen(_ url: URL) {
+ if FileManager.default.fileExists(atPath: url.path) {
+ NSWorkspace.shared.activateFileViewerSelecting([url])
+ } else {
+ NSWorkspace.shared.open(url.deletingLastPathComponent())
+ }
+ }
+
+ private static func describe(_ error: HealthError) -> String {
+ switch error {
+ case .badURL:
+ "Invalid server URL"
+ case .http(let code) where code == 401 || code == 403:
+ "Server is up but this app is not authorized (HTTP \(code)). Add a bearer in Settings."
+ case .http(let code):
+ "Server returned HTTP \(code)"
+ case .decode:
+ "Could not read /admin/status"
+ case .transport(let message):
+ message
+ }
+ }
+}
+
+extension CliError: LocalizedError {
+ public var errorDescription: String? {
+ switch self {
+ case .timeout:
+ "Timed out running ai-memory"
+ case .missingRuntime:
+ "Bundled ai-memory runtime is missing. Build with companions/ai-memory-macos/build.sh"
+ case .failed(_, let output):
+ output.isEmpty ? "ai-memory command failed" : output
+ }
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenu/MenuBarView.swift b/companions/ai-memory-macos/Sources/AIMemoryMenu/MenuBarView.swift
new file mode 100644
index 00000000..10886ab7
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenu/MenuBarView.swift
@@ -0,0 +1,127 @@
+import AppKit
+import SwiftUI
+import AIMemoryMenuCore
+
+struct MenuBarView: View {
+ @Environment(AppModel.self) private var model
+ @Environment(\.openWindow) private var openWindow
+
+ var body: some View {
+ Text(model.headlineVersion)
+ .disabled(true)
+ .onAppear {
+ Task { await model.poll() }
+ }
+ ForEach(Array(model.statisticLines.enumerated()), id: \.offset) { _, line in
+ Text(line)
+ .font(.system(.body, design: .monospaced))
+ .disabled(true)
+ }
+ if model.runtimeMissing {
+ Text("Runtime not bundled — run build.sh")
+ .disabled(true)
+ }
+ Divider()
+ serviceButtons
+ Divider()
+ Button("Open Web UI") {
+ model.openWebUI()
+ }
+ if model.showsServerStatus {
+ Button("Show Status…") {
+ Task {
+ await model.refreshStatusOutput()
+ NSApp.activate(ignoringOtherApps: true)
+ openWindow(id: "status")
+ }
+ }
+ }
+ Button("Open Config") {
+ model.openConfig()
+ }
+ Button("Open Data Directory") {
+ model.openDataDirectory()
+ }
+ Button("Open Logs") {
+ model.openLogs()
+ }
+ Divider()
+ SettingsLink {
+ Text("Settings…")
+ }
+ Button("Quit") {
+ NSApp.terminate(nil)
+ }
+ }
+
+ @ViewBuilder
+ private var serviceButtons: some View {
+ switch model.launchd {
+ case .notInstalled:
+ Button("Install & Start Server") {
+ Task { await model.installAndStart() }
+ }
+ .disabled(model.isBusy || model.icon == .starting)
+ case .stopped:
+ Button("Start Server") {
+ Task { await model.start() }
+ }
+ .disabled(model.isBusy || model.icon == .starting)
+ case .running:
+ Button("Stop Server") {
+ Task { await model.stop() }
+ }
+ .disabled(model.isBusy)
+ Button("Restart Server") {
+ Task { await model.restart() }
+ }
+ .disabled(model.isBusy || model.icon == .starting)
+ }
+ }
+}
+
+struct MenuBarLabel: View {
+ var icon: IconState
+
+ var body: some View {
+ // Menu extras flatten SwiftUI tint to a template image, so a
+ // non-template NSImage is what actually changes with server state.
+ Image(nsImage: StatusDot.image(for: icon))
+ .accessibilityLabel(icon.accessibilityLabel)
+ }
+}
+
+enum StatusDot {
+ static func image(for icon: IconState) -> NSImage {
+ let size = NSSize(width: 18, height: 18)
+ let image = NSImage(size: size, flipped: false) { rect in
+ let inset = rect.insetBy(dx: 3, dy: 3)
+ color(for: icon).setFill()
+ NSBezierPath(ovalIn: inset).fill()
+ if icon == .unknown || icon == .notInstalled {
+ NSColor.windowBackgroundColor.setStroke()
+ let stroke = NSBezierPath(ovalIn: inset.insetBy(dx: 0.5, dy: 0.5))
+ stroke.lineWidth = 1
+ stroke.stroke()
+ }
+ return true
+ }
+ image.isTemplate = false
+ return image
+ }
+
+ private static func color(for icon: IconState) -> NSColor {
+ switch icon {
+ case .ok:
+ NSColor.systemGreen
+ case .starting:
+ NSColor.systemOrange
+ case .degraded, .authRequired:
+ NSColor.systemYellow
+ case .unreachable:
+ NSColor.systemRed
+ case .notInstalled, .unknown:
+ NSColor.systemGray
+ }
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenu/SettingsView.swift b/companions/ai-memory-macos/Sources/AIMemoryMenu/SettingsView.swift
new file mode 100644
index 00000000..690fa0d3
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenu/SettingsView.swift
@@ -0,0 +1,104 @@
+import ServiceManagement
+import SwiftUI
+import AIMemoryMenuCore
+
+struct SettingsView: View {
+ @Environment(AppModel.self) private var model
+ @State private var serverURL: String = ""
+ @State private var dataDir: String = ""
+ @State private var token: String = ""
+ @State private var launchAtLogin = SMAppService.mainApp.status == .enabled
+ @State private var loginError: String?
+ @State private var saveTask: Task<Void, Never>?
+
+ var body: some View {
+ Form {
+ Section("Server") {
+ TextField("URL", text: $serverURL)
+ .onChange(of: serverURL) { _, _ in scheduleSave() }
+ .onSubmit { persist() }
+ SecureField(
+ model.tokenConfigured ? "Bearer token (saved in Keychain)" : "Bearer token (optional)",
+ text: $token
+ )
+ .onChange(of: token) { _, _ in scheduleSave() }
+ .onSubmit { persist() }
+ if model.tokenConfigured {
+ Button("Clear saved token") {
+ token = ""
+ model.saveSettings(
+ serverURLString: serverURL,
+ dataDirOverride: dataDir,
+ token: nil,
+ clearToken: true
+ )
+ }
+ }
+ }
+ Section("Data") {
+ TextField("Data directory override", text: $dataDir, prompt: Text(FirstRun.defaultDataDir().path))
+ .onChange(of: dataDir) { _, _ in scheduleSave() }
+ .onSubmit { persist() }
+ Text("Empty keeps ~/Library/Application Support/ai-memory. Changing this does not move existing files.")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ Section("Login") {
+ Toggle("Launch menu bar app at login", isOn: $launchAtLogin)
+ .onChange(of: launchAtLogin) { _, enabled in
+ setLoginItem(enabled)
+ }
+ if let loginError {
+ Text(loginError)
+ .font(.caption)
+ .foregroundStyle(.red)
+ }
+ }
+ }
+ .formStyle(.grouped)
+ .frame(minWidth: 480, minHeight: 320)
+ .onAppear {
+ serverURL = model.settings.serverURL.absoluteString
+ dataDir = model.settings.dataDirOverride?.path ?? ""
+ launchAtLogin = SMAppService.mainApp.status == .enabled
+ }
+ .onDisappear {
+ persist()
+ }
+ }
+
+ private func scheduleSave() {
+ saveTask?.cancel()
+ saveTask = Task { @MainActor in
+ try? await Task.sleep(for: .milliseconds(400))
+ guard !Task.isCancelled else { return }
+ persist()
+ }
+ }
+
+ private func persist() {
+ saveTask?.cancel()
+ model.saveSettings(
+ serverURLString: serverURL,
+ dataDirOverride: dataDir,
+ token: token.isEmpty ? nil : token,
+ clearToken: false
+ )
+ }
+
+ private func setLoginItem(_ enabled: Bool) {
+ let currentlyEnabled = SMAppService.mainApp.status == .enabled
+ guard enabled != currentlyEnabled else { return }
+ do {
+ if enabled {
+ try SMAppService.mainApp.register()
+ } else {
+ try SMAppService.mainApp.unregister()
+ }
+ loginError = nil
+ } catch {
+ loginError = error.localizedDescription
+ launchAtLogin = SMAppService.mainApp.status == .enabled
+ }
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenu/StatusOutputView.swift b/companions/ai-memory-macos/Sources/AIMemoryMenu/StatusOutputView.swift
new file mode 100644
index 00000000..2b210fea
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenu/StatusOutputView.swift
@@ -0,0 +1,35 @@
+import AppKit
+import SwiftUI
+
+struct StatusOutputView: View {
+ @Environment(AppModel.self) private var model
+
+ var body: some View {
+ VStack(alignment: .leading, spacing: 8) {
+ HStack {
+ Text("ai-memory status")
+ .font(.headline)
+ Spacer()
+ Button("Refresh") {
+ Task { await model.refreshStatusOutput() }
+ }
+ .disabled(model.isBusy)
+ Button("Copy") {
+ NSPasteboard.general.clearContents()
+ NSPasteboard.general.setString(model.statusOutput, forType: .string)
+ }
+ .disabled(model.statusOutput.isEmpty)
+ }
+ ScrollView {
+ Text(model.statusOutput.isEmpty ? "Running ai-memory status…" : model.statusOutput)
+ .font(.system(.body, design: .monospaced))
+ .textSelection(.enabled)
+ .frame(maxWidth: .infinity, alignment: .leading)
+ .padding(8)
+ }
+ .background(Color(nsColor: .textBackgroundColor))
+ }
+ .padding()
+ .frame(minWidth: 560, minHeight: 360)
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenuCore/AppSettings.swift b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/AppSettings.swift
new file mode 100644
index 00000000..b5132665
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/AppSettings.swift
@@ -0,0 +1,49 @@
+import Foundation
+
+public struct AppSettings: Equatable, Sendable {
+ public var serverURL: URL
+ public var dataDirOverride: URL?
+
+ public static let defaultServerURL = URL(string: "http://127.0.0.1:49374")!
+
+ public init(serverURL: URL = defaultServerURL, dataDirOverride: URL? = nil) {
+ self.serverURL = serverURL
+ self.dataDirOverride = dataDirOverride
+ }
+
+ public var resolvedDataDir: URL {
+ dataDirOverride ?? FirstRun.defaultDataDir()
+ }
+
+ public static func load(defaults: UserDefaults = .standard) -> AppSettings {
+ let url: URL
+ if let stored = defaults.string(forKey: Keys.serverURL),
+ let parsed = URL(string: stored)
+ {
+ url = parsed
+ } else {
+ url = defaultServerURL
+ }
+ let override: URL?
+ if let path = defaults.string(forKey: Keys.dataDir), !path.isEmpty {
+ override = URL(fileURLWithPath: path)
+ } else {
+ override = nil
+ }
+ return AppSettings(serverURL: url, dataDirOverride: override)
+ }
+
+ public func save(defaults: UserDefaults = .standard) {
+ defaults.set(serverURL.absoluteString, forKey: Keys.serverURL)
+ if let dataDirOverride {
+ defaults.set(dataDirOverride.path, forKey: Keys.dataDir)
+ } else {
+ defaults.removeObject(forKey: Keys.dataDir)
+ }
+ }
+
+ private enum Keys {
+ static let serverURL = "serverURL"
+ static let dataDir = "dataDirOverride"
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenuCore/BundledRuntime.swift b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/BundledRuntime.swift
new file mode 100644
index 00000000..c79b7a1c
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/BundledRuntime.swift
@@ -0,0 +1,101 @@
+import Foundation
+
+/// Layout of `Contents/Resources/runtime/`: the release-tarball sibling pair
+/// (`ai-memory` + `hooks/`) plus the launchd template.
+public struct RuntimeLayout: Equatable, Sendable {
+ public var root: URL
+
+ public init(root: URL) {
+ self.root = root
+ }
+
+ public var binary: URL {
+ root.appending(path: "ai-memory")
+ }
+
+ public var hooks: URL {
+ root.appending(path: "hooks")
+ }
+
+ public var plistTemplate: URL {
+ root.appending(path: "packaging/launchd/\(LaunchdController.label).plist")
+ }
+
+ public func validate(fileManager: FileManager = .default) -> Bool {
+ fileManager.isExecutableFile(atPath: binary.path)
+ && fileManager.fileExists(atPath: hooks.path)
+ && fileManager.fileExists(atPath: plistTemplate.path)
+ }
+
+ /// Prefers the staged bundle resource; `AI_MEMORY_MENU_RUNTIME` is a
+ /// developer override for `swift run` without wrapping an `.app`.
+ public static func resolve(
+ bundle: Bundle = .main,
+ environment: [String: String] = ProcessInfo.processInfo.environment,
+ fileManager: FileManager = .default
+ ) -> RuntimeLayout? {
+ if let env = environment["AI_MEMORY_MENU_RUNTIME"], !env.isEmpty {
+ let layout = RuntimeLayout(root: URL(fileURLWithPath: env))
+ if layout.validate(fileManager: fileManager) {
+ return layout
+ }
+ }
+ if let resourceRoot = bundle.resourceURL {
+ let layout = RuntimeLayout(root: resourceRoot.appending(path: "runtime"))
+ if layout.validate(fileManager: fileManager) {
+ return layout
+ }
+ }
+ return nil
+ }
+}
+
+public enum FirstRun {
+ public static func needsInit(dataDir: URL, fileManager: FileManager = .default) -> Bool {
+ !fileManager.fileExists(atPath: dataDir.appending(path: "config.toml").path)
+ }
+
+ public static func defaultDataDir(fileManager: FileManager = .default) -> URL {
+ let base = fileManager.urls(for: .applicationSupportDirectory, in: .userDomainMask).first
+ ?? URL(fileURLWithPath: NSHomeDirectory())
+ .appending(path: "Library/Application Support")
+ return base.appending(path: "ai-memory")
+ }
+}
+
+public struct BundledCLI: Sendable {
+ public var runtime: RuntimeLayout
+ public var runner: any CommandRunning
+
+ public init(runtime: RuntimeLayout, runner: any CommandRunning = ProcessRunner()) {
+ self.runtime = runtime
+ self.runner = runner
+ }
+
+ public func initDataDir(_ dataDir: URL) throws -> ProcessResult {
+ try run(arguments: ["--data-dir", dataDir.path, "init"], extraEnv: [:])
+ }
+
+ public func status(serverURL: URL, token: String?, dataDir: URL?) throws -> ProcessResult {
+ var args: [String] = []
+ var env: [String: String] = [
+ "AI_MEMORY_SERVER_URL": serverURL.absoluteString,
+ ]
+ if let dataDir {
+ args.append(contentsOf: ["--data-dir", dataDir.path])
+ }
+ if let token, !token.isEmpty {
+ env["AI_MEMORY_AUTH_TOKEN"] = token
+ }
+ args.append("status")
+ return try run(arguments: args, extraEnv: env)
+ }
+
+ private func run(arguments: [String], extraEnv: [String: String]) throws -> ProcessResult {
+ let result = try runner.run(binary: runtime.binary, arguments: arguments, extraEnv: extraEnv)
+ if result.exitCode != 0 {
+ throw CliError.failed(result.exitCode, result.combinedOutput)
+ }
+ return result
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenuCore/HealthClient.swift b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/HealthClient.swift
new file mode 100644
index 00000000..fcc235b4
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/HealthClient.swift
@@ -0,0 +1,60 @@
+import Foundation
+
+public enum HealthError: Error, Equatable, Sendable {
+ case badURL
+ case http(Int)
+ case decode
+ case transport(String)
+}
+
+public struct HealthClient: Sendable {
+ public var timeout: TimeInterval
+ private let session: URLSession
+
+ public init(timeout: TimeInterval = 3) {
+ self.timeout = timeout
+ let config = URLSessionConfiguration.ephemeral
+ config.timeoutIntervalForRequest = timeout
+ config.timeoutIntervalForResource = timeout
+ config.requestCachePolicy = .reloadIgnoringLocalCacheData
+ config.waitsForConnectivity = false
+ session = URLSession(configuration: config)
+ }
+
+ public func fetch(baseURL: URL, token: String?) async throws -> StatusReport {
+ let url = baseURL.appending(path: "admin/status")
+ var request = URLRequest(url: url)
+ request.timeoutInterval = timeout
+ request.cachePolicy = .reloadIgnoringLocalCacheData
+ request.setValue("application/json", forHTTPHeaderField: "Accept")
+ if let token, !token.isEmpty {
+ request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+ }
+
+ let data: Data
+ let response: URLResponse
+ do {
+ (data, response) = try await session.data(for: request)
+ } catch {
+ throw HealthError.transport(error.localizedDescription)
+ }
+
+ guard let http = response as? HTTPURLResponse else {
+ throw HealthError.transport("non-HTTP response")
+ }
+ guard (200 ..< 300).contains(http.statusCode) else {
+ throw HealthError.http(http.statusCode)
+ }
+ do {
+ return try JSONDecoder().decode(StatusReport.self, from: data)
+ } catch {
+ throw HealthError.decode
+ }
+ }
+}
+
+public enum HealthURL {
+ public static func webUI(from baseURL: URL) -> URL {
+ baseURL.appending(path: "web")
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenuCore/HealthModels.swift b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/HealthModels.swift
new file mode 100644
index 00000000..91e019f2
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/HealthModels.swift
@@ -0,0 +1,281 @@
+import Foundation
+
+/// Wire shape of `GET /admin/status`. Unknown fields are ignored so an
+/// older or newer server still decodes the headlines this wrapper shows.
+public struct StatusReport: Decodable, Equatable, Sendable {
+ public var version: String
+ public var dataDir: String?
+ public var bind: String?
+ public var counts: StatusCounts
+ public var writeQueue: WriteQueue?
+ public var providers: ProviderHealthSnapshot?
+ public var ingest: IngestSnapshot?
+
+ public init(
+ version: String,
+ dataDir: String? = nil,
+ bind: String? = nil,
+ counts: StatusCounts,
+ writeQueue: WriteQueue? = nil,
+ providers: ProviderHealthSnapshot? = nil,
+ ingest: IngestSnapshot? = nil
+ ) {
+ self.version = version
+ self.dataDir = dataDir
+ self.bind = bind
+ self.counts = counts
+ self.writeQueue = writeQueue
+ self.providers = providers
+ self.ingest = ingest
+ }
+
+ enum CodingKeys: String, CodingKey {
+ case version
+ case bind
+ case counts
+ case providers
+ case ingest
+ case dataDir = "data_dir"
+ case writeQueue = "write_queue"
+ }
+
+ public var isDegraded: Bool {
+ if let queue = writeQueue, queue.queued > 0 {
+ return true
+ }
+ if providers?.llm.status == "error" {
+ return true
+ }
+ if providers?.embedding.status == "error" {
+ return true
+ }
+ return false
+ }
+
+ public var llmHeadline: String {
+ roleHeadline(label: "LLM", role: providers?.llm)
+ }
+
+ public var embeddingHeadline: String {
+ roleHeadline(label: "Embed", role: providers?.embedding)
+ }
+
+ /// Lines shown in the menu extra. Counts come from `GET /admin/status`.
+ public var statisticLines: [String] {
+ var lines: [String] = []
+ if let bind, !bind.isEmpty {
+ lines.append("Bind \(bind)")
+ }
+ lines.append(contentsOf: [
+ "Pages \(counts.pagesLatest) (all versions \(counts.pagesAll))",
+ "Sessions \(counts.sessions)",
+ "Observations \(counts.observations)",
+ llmHeadline,
+ embeddingHeadline,
+ ])
+ if let queue = writeQueue, queue.queued > 0 {
+ lines.append("Write queue \(queue.queued)/\(queue.capacity)")
+ }
+ if let ingest {
+ lines.append("Ingest accepted \(ingest.accepted)")
+ if ingest.droppedByPolicy > 0 {
+ lines.append("Dropped by policy \(ingest.droppedByPolicy)")
+ }
+ lines.append("Last write \(Self.lastWriteLabel(ingest.lastPersistedMs))")
+ }
+ return lines
+ }
+
+ private func roleHeadline(label: String, role: ProviderRoleHealth?) -> String {
+ guard let role else {
+ return "\(label) unknown"
+ }
+ var text = "\(label) \(role.status)"
+ if let provider = role.provider, !provider.isEmpty {
+ if let model = role.model, !model.isEmpty {
+ text += " \(provider)/\(model)"
+ } else {
+ text += " \(provider)"
+ }
+ }
+ return text
+ }
+
+ public static func lastWriteLabel(_ unixMs: UInt64?) -> String {
+ guard let unixMs else {
+ return "—"
+ }
+ let nowMs = UInt64(max(0, Date().timeIntervalSince1970 * 1000))
+ let ageMs = nowMs > unixMs ? nowMs - unixMs : 0
+ let secs = ageMs / 1000
+ if secs < 60 {
+ return "\(secs)s ago"
+ }
+ if secs < 3600 {
+ return "\(secs / 60)m ago"
+ }
+ if secs < 86_400 {
+ return "\(secs / 3600)h ago"
+ }
+ return "\(secs / 86_400)d ago"
+ }
+}
+
+public struct IngestSnapshot: Decodable, Equatable, Sendable {
+ public var accepted: UInt64
+ public var droppedByPolicy: UInt64
+ public var shedSaturated: UInt64
+ public var shedRateLimited: UInt64
+ public var lastPersistedMs: UInt64?
+
+ public init(
+ accepted: UInt64 = 0,
+ droppedByPolicy: UInt64 = 0,
+ shedSaturated: UInt64 = 0,
+ shedRateLimited: UInt64 = 0,
+ lastPersistedMs: UInt64? = nil
+ ) {
+ self.accepted = accepted
+ self.droppedByPolicy = droppedByPolicy
+ self.shedSaturated = shedSaturated
+ self.shedRateLimited = shedRateLimited
+ self.lastPersistedMs = lastPersistedMs
+ }
+
+ enum CodingKeys: String, CodingKey {
+ case accepted
+ case droppedByPolicy = "dropped_by_policy"
+ case shedSaturated = "shed_saturated"
+ case shedRateLimited = "shed_rate_limited"
+ case lastPersistedMs = "last_persisted_ms"
+ }
+
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ accepted = try container.decodeIfPresent(UInt64.self, forKey: .accepted) ?? 0
+ droppedByPolicy = try container.decodeIfPresent(UInt64.self, forKey: .droppedByPolicy) ?? 0
+ shedSaturated = try container.decodeIfPresent(UInt64.self, forKey: .shedSaturated) ?? 0
+ shedRateLimited = try container.decodeIfPresent(UInt64.self, forKey: .shedRateLimited) ?? 0
+ lastPersistedMs = try container.decodeIfPresent(UInt64.self, forKey: .lastPersistedMs)
+ }
+}
+
+public struct StatusCounts: Decodable, Equatable, Sendable {
+ public var pagesLatest: UInt64
+ public var pagesAll: UInt64
+ public var sessions: UInt64
+ public var observations: UInt64
+
+ public init(pagesLatest: UInt64, pagesAll: UInt64, sessions: UInt64, observations: UInt64) {
+ self.pagesLatest = pagesLatest
+ self.pagesAll = pagesAll
+ self.sessions = sessions
+ self.observations = observations
+ }
+
+ enum CodingKeys: String, CodingKey {
+ case pagesLatest = "pages_latest"
+ case pagesAll = "pages_all"
+ case sessions
+ case observations
+ }
+}
+
+/// JSON encoding of the server's `(queued, capacity)` tuple.
+public struct WriteQueue: Decodable, Equatable, Sendable {
+ public var queued: Int
+ public var capacity: Int
+
+ public init(queued: Int, capacity: Int) {
+ self.queued = queued
+ self.capacity = capacity
+ }
+
+ public init(from decoder: Decoder) throws {
+ var container = try decoder.unkeyedContainer()
+ queued = try container.decode(Int.self)
+ capacity = try container.decode(Int.self)
+ }
+}
+
+public struct ProviderHealthSnapshot: Decodable, Equatable, Sendable {
+ public var llm: ProviderRoleHealth
+ public var embedding: ProviderRoleHealth
+
+ public init(llm: ProviderRoleHealth, embedding: ProviderRoleHealth) {
+ self.llm = llm
+ self.embedding = embedding
+ }
+}
+
+public struct ProviderRoleHealth: Decodable, Equatable, Sendable {
+ public var status: String
+ public var provider: String?
+ public var model: String?
+
+ public init(status: String, provider: String? = nil, model: String? = nil) {
+ self.status = status
+ self.provider = provider
+ self.model = model
+ }
+}
+
+public enum IconState: Equatable, Sendable {
+ case unknown
+ case notInstalled
+ case unreachable
+ case starting
+ case authRequired
+ case ok
+ case degraded
+
+ public static func derived(
+ launchd: LaunchdState,
+ report: StatusReport?,
+ fetchFailed: Bool,
+ httpStatus: Int? = nil
+ ) -> IconState {
+ if let report {
+ return report.isDegraded ? .degraded : .ok
+ }
+ if let httpStatus, httpStatus == 401 || httpStatus == 403 {
+ return .authRequired
+ }
+ if fetchFailed {
+ return launchd == .notInstalled ? .notInstalled : .unreachable
+ }
+ return .unknown
+ }
+
+ /// Keep the "starting" overlay until `/admin/status` answers or the grace expires.
+ public static func applyingStartGrace(_ derived: IconState, isStarting: Bool) -> IconState {
+ guard isStarting else {
+ return derived
+ }
+ switch derived {
+ case .ok, .degraded, .authRequired:
+ return derived
+ default:
+ return .starting
+ }
+ }
+
+ public var accessibilityLabel: String {
+ switch self {
+ case .unknown:
+ "ai-memory, status unknown"
+ case .notInstalled:
+ "ai-memory, not installed"
+ case .unreachable:
+ "ai-memory, server down"
+ case .starting:
+ "ai-memory, server is starting"
+ case .authRequired:
+ "ai-memory, running, authentication required"
+ case .ok:
+ "ai-memory, server running"
+ case .degraded:
+ "ai-memory, running with warnings"
+ }
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenuCore/LaunchdController.swift b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/LaunchdController.swift
new file mode 100644
index 00000000..76f731bc
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/LaunchdController.swift
@@ -0,0 +1,136 @@
+import Darwin
+import Foundation
+
+public enum LaunchdState: Equatable, Sendable {
+ case notInstalled
+ case stopped
+ case running
+}
+
+public struct LaunchdController: Sendable {
+ public static let label = "com.github.akitaonrails.ai-memory"
+
+ public var home: URL
+ public var runner: any CommandRunning
+
+ public init(home: URL, runner: any CommandRunning = ProcessRunner()) {
+ self.home = home
+ self.runner = runner
+ }
+
+ public var plistDestination: URL {
+ home.appending(path: "Library/LaunchAgents")
+ .appending(path: "\(Self.label).plist")
+ }
+
+ public var logDirectory: URL {
+ home.appending(path: "Library/Logs/ai-memory")
+ }
+
+ public static func renderTemplate(
+ _ template: String,
+ binary: URL,
+ home: URL,
+ dataDir: URL?
+ ) -> String {
+ var rendered = template
+ .replacingOccurrences(of: "__AI_MEMORY_BIN__", with: binary.path)
+ .replacingOccurrences(of: "__HOME__", with: home.path)
+ if let dataDir {
+ let env = """
+ <key>EnvironmentVariables</key>
+ <dict>
+ <key>AI_MEMORY_DATA_DIR</key>
+ <string>\(xmlEscape(dataDir.path))</string>
+ </dict>
+
+ """
+ if let range = rendered.range(of: "</dict>", options: .backwards) {
+ rendered.replaceSubrange(range, with: env + "</dict>")
+ }
+ }
+ return rendered
+ }
+
+ public static func programArgumentsBinary(inPlist plist: String) -> String? {
+ // First <string> after ProgramArguments is the executable.
+ guard let argsRange = plist.range(of: "<key>ProgramArguments</key>") else {
+ return nil
+ }
+ let rest = plist[argsRange.upperBound...]
+ guard let start = rest.range(of: "<string>") else {
+ return nil
+ }
+ let after = rest[start.upperBound...]
+ guard let end = after.range(of: "</string>") else {
+ return nil
+ }
+ return String(after[..<end.lowerBound])
+ }
+
+ public func writePlist(template: String, binary: URL, dataDir: URL?) throws {
+ let fm = FileManager.default
+ try fm.createDirectory(
+ at: plistDestination.deletingLastPathComponent(),
+ withIntermediateDirectories: true
+ )
+ try fm.createDirectory(at: logDirectory, withIntermediateDirectories: true)
+ let body = Self.renderTemplate(template, binary: binary, home: home, dataDir: dataDir)
+ try body.write(to: plistDestination, atomically: true, encoding: .utf8)
+ }
+
+ public func state() -> LaunchdState {
+ let plistExists = FileManager.default.fileExists(atPath: plistDestination.path)
+ let result = try? runner.run(
+ binary: URL(fileURLWithPath: "/bin/launchctl"),
+ arguments: ["print", domainService],
+ extraEnv: [:]
+ )
+ if let result, result.exitCode == 0 {
+ if result.stdout.contains("state = running") {
+ return .running
+ }
+ return .stopped
+ }
+ return plistExists ? .stopped : .notInstalled
+ }
+
+ public func bootstrap() throws {
+ try runLaunchctl(["bootstrap", domain, plistDestination.path])
+ }
+
+ public func bootout() throws {
+ try runLaunchctl(["bootout", domainService])
+ }
+
+ public func kickstart() throws {
+ try runLaunchctl(["kickstart", "-k", domainService])
+ }
+
+ private func runLaunchctl(_ arguments: [String]) throws {
+ let result = try runner.run(
+ binary: URL(fileURLWithPath: "/bin/launchctl"),
+ arguments: arguments,
+ extraEnv: [:]
+ )
+ if result.exitCode != 0 {
+ throw CliError.failed(result.exitCode, result.combinedOutput)
+ }
+ }
+
+ private var domain: String {
+ "gui/\(getuid())"
+ }
+
+ private var domainService: String {
+ "\(domain)/\(Self.label)"
+ }
+
+ private static func xmlEscape(_ value: String) -> String {
+ value
+ .replacingOccurrences(of: "&", with: "&amp;")
+ .replacingOccurrences(of: "<", with: "&lt;")
+ .replacingOccurrences(of: ">", with: "&gt;")
+ .replacingOccurrences(of: "\"", with: "&quot;")
+ }
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenuCore/ProcessRunner.swift b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/ProcessRunner.swift
new file mode 100644
index 00000000..ab551177
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/ProcessRunner.swift
@@ -0,0 +1,78 @@
+import Foundation
+
+public struct ProcessResult: Equatable, Sendable {
+ public var exitCode: Int32
+ public var stdout: String
+ public var stderr: String
+
+ public init(exitCode: Int32, stdout: String, stderr: String) {
+ self.exitCode = exitCode
+ self.stdout = stdout
+ self.stderr = stderr
+ }
+
+ public var combinedOutput: String {
+ let out = stdout.trimmingCharacters(in: .whitespacesAndNewlines)
+ let err = stderr.trimmingCharacters(in: .whitespacesAndNewlines)
+ if err.isEmpty {
+ return out
+ }
+ if out.isEmpty {
+ return err
+ }
+ return out + "\n" + err
+ }
+}
+
+public protocol CommandRunning: Sendable {
+ func run(binary: URL, arguments: [String], extraEnv: [String: String]) throws -> ProcessResult
+}
+
+public struct ProcessRunner: CommandRunning {
+ public var timeout: TimeInterval
+
+ public init(timeout: TimeInterval = 30) {
+ self.timeout = timeout
+ }
+
+ public func run(binary: URL, arguments: [String], extraEnv: [String: String]) throws -> ProcessResult {
+ let process = Process()
+ process.executableURL = binary
+ process.arguments = arguments
+ var env = ProcessInfo.processInfo.environment
+ for (key, value) in extraEnv {
+ env[key] = value
+ }
+ process.environment = env
+
+ let stdout = Pipe()
+ let stderr = Pipe()
+ process.standardOutput = stdout
+ process.standardError = stderr
+
+ try process.run()
+
+ let deadline = Date().addingTimeInterval(timeout)
+ while process.isRunning, Date() < deadline {
+ Thread.sleep(forTimeInterval: 0.05)
+ }
+ if process.isRunning {
+ process.terminate()
+ throw CliError.timeout
+ }
+
+ let outData = stdout.fileHandleForReading.readDataToEndOfFile()
+ let errData = stderr.fileHandleForReading.readDataToEndOfFile()
+ return ProcessResult(
+ exitCode: process.terminationStatus,
+ stdout: String(data: outData, encoding: .utf8) ?? "",
+ stderr: String(data: errData, encoding: .utf8) ?? ""
+ )
+ }
+}
+
+public enum CliError: Error, Equatable, Sendable {
+ case timeout
+ case missingRuntime
+ case failed(Int32, String)
+}
diff --git a/companions/ai-memory-macos/Sources/AIMemoryMenuCore/TokenStore.swift b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/TokenStore.swift
new file mode 100644
index 00000000..5a7efd48
--- /dev/null
+++ b/companions/ai-memory-macos/Sources/AIMemoryMenuCore/TokenStore.swift
@@ -0,0 +1,106 @@
+import Foundation
+import Security
+
+public protocol TokenStore: Sendable {
+ func read() -> String?
+ func save(_ token: String) throws
+ func clear() throws
+}
+
+public struct MemoryTokenStore: TokenStore, Sendable {
+ private let box: LockingBox<String?>
+
+ public init(_ initial: String? = nil) {
+ box = LockingBox(initial)
+ }
+
+ public func read() -> String? {
+ box.value
+ }
+
+ public func save(_ token: String) throws {
+ box.value = token
+ }
+
+ public func clear() throws {
+ box.value = nil
+ }
+}
+
+/// Tiny mutex so `MemoryTokenStore` can be `Sendable` in tests.
+final class LockingBox<Value>: @unchecked Sendable {
+ private let lock = NSLock()
+ private var storage: Value
+
+ init(_ value: Value) {
+ storage = value
+ }
+
+ var value: Value {
+ get {
+ lock.lock()
+ defer { lock.unlock() }
+ return storage
+ }
+ set {
+ lock.lock()
+ defer { lock.unlock() }
+ storage = newValue
+ }
+ }
+}
+
+public struct KeychainTokenStore: TokenStore, Sendable {
+ public static let service = "com.github.akitaonrails.ai-memory-menu"
+ public static let account = "bearer"
+
+ public init() {}
+
+ public func read() -> String? {
+ let query: [String: Any] = [
+ kSecClass as String: kSecClassGenericPassword,
+ kSecAttrService as String: Self.service,
+ kSecAttrAccount as String: Self.account,
+ kSecReturnData as String: true,
+ kSecMatchLimit as String: kSecMatchLimitOne,
+ ]
+ var item: CFTypeRef?
+ let status = SecItemCopyMatching(query as CFDictionary, &item)
+ guard status == errSecSuccess, let data = item as? Data else {
+ return nil
+ }
+ return String(data: data, encoding: .utf8)
+ }
+
+ public func save(_ token: String) throws {
+ try clear()
+ let data = Data(token.utf8)
+ let query: [String: Any] = [
+ kSecClass as String: kSecClassGenericPassword,
+ kSecAttrService as String: Self.service,
+ kSecAttrAccount as String: Self.account,
+ kSecValueData as String: data,
+ kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
+ ]
+ let status = SecItemAdd(query as CFDictionary, nil)
+ guard status == errSecSuccess else {
+ throw KeychainError.unhandled(status)
+ }
+ }
+
+ public func clear() throws {
+ let query: [String: Any] = [
+ kSecClass as String: kSecClassGenericPassword,
+ kSecAttrService as String: Self.service,
+ kSecAttrAccount as String: Self.account,
+ ]
+ let status = SecItemDelete(query as CFDictionary)
+ guard status == errSecSuccess || status == errSecItemNotFound else {
+ throw KeychainError.unhandled(status)
+ }
+ }
+}
+
+public enum KeychainError: Error, Equatable, Sendable {
+ case unhandled(OSStatus)
+}
diff --git a/companions/ai-memory-macos/Tests/AIMemoryMenuTests/AppSettingsTests.swift b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/AppSettingsTests.swift
new file mode 100644
index 00000000..1eb50b86
--- /dev/null
+++ b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/AppSettingsTests.swift
@@ -0,0 +1,23 @@
+import Foundation
+import Testing
+@testable import AIMemoryMenuCore
+
+struct AppSettingsTests {
+ @Test func loadAndSaveRoundTrip() throws {
+ let name = "ai-memory-menu-settings-test-\(UUID().uuidString)"
+ let suite = try #require(UserDefaults(suiteName: name))
+ defer { suite.removePersistentDomain(forName: name) }
+
+ var settings = AppSettings.load(defaults: suite)
+ #expect(settings.serverURL == AppSettings.defaultServerURL)
+ #expect(settings.dataDirOverride == nil)
+
+ settings.serverURL = URL(string: "http://127.0.0.1:8080")!
+ settings.dataDirOverride = URL(fileURLWithPath: "/tmp/custom-memory")
+ settings.save(defaults: suite)
+
+ let loaded = AppSettings.load(defaults: suite)
+ #expect(loaded.serverURL.absoluteString == "http://127.0.0.1:8080")
+ #expect(loaded.dataDirOverride?.path == "/tmp/custom-memory")
+ }
+}
diff --git a/companions/ai-memory-macos/Tests/AIMemoryMenuTests/HealthModelsTests.swift b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/HealthModelsTests.swift
new file mode 100644
index 00000000..7f729178
--- /dev/null
+++ b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/HealthModelsTests.swift
@@ -0,0 +1,108 @@
+import Foundation
+import Testing
+@testable import AIMemoryMenuCore
+
+struct HealthModelsTests {
+ @Test func decodesStatusFixture() throws {
+ let url = try #require(Bundle.module.url(forResource: "status", withExtension: "json", subdirectory: "fixtures"))
+ let data = try Data(contentsOf: url)
+ let report = try JSONDecoder().decode(StatusReport.self, from: data)
+ #expect(report.version == "2.3.2")
+ #expect(report.counts.pagesLatest == 138)
+ #expect(report.counts.sessions == 27)
+ #expect(report.writeQueue == WriteQueue(queued: 0, capacity: 128))
+ #expect(report.providers?.llm.status == "ok")
+ #expect(report.providers?.embedding.status == "disabled")
+ #expect(report.ingest?.accepted == 4198)
+ #expect(!report.isDegraded)
+ #expect(report.llmHeadline.contains("ok"))
+ let stats = report.statisticLines
+ #expect(stats.contains { $0.hasPrefix("Pages 138") })
+ #expect(stats.contains { $0.hasPrefix("Sessions 27") })
+ #expect(stats.contains { $0.hasPrefix("Observations 4198") })
+ #expect(stats.contains { $0.hasPrefix("Bind ") })
+ #expect(stats.contains { $0.hasPrefix("Ingest accepted 4198") })
+ }
+
+ @Test func decodesOlderPayloadWithoutWriteQueueOrProviders() throws {
+ let json = """
+ {
+ "version": "1.0.0",
+ "counts": {
+ "pages_latest": 1,
+ "pages_all": 1,
+ "sessions": 0,
+ "observations": 0
+ }
+ }
+ """.data(using: .utf8)!
+ let report = try JSONDecoder().decode(StatusReport.self, from: json)
+ #expect(report.writeQueue == nil)
+ #expect(report.providers == nil)
+ #expect(!report.isDegraded)
+ }
+
+ @Test func degradedWhenProviderErrorsOrQueueIsBusy() {
+ let ok = StatusReport(
+ version: "2.3.2",
+ counts: StatusCounts(pagesLatest: 1, pagesAll: 1, sessions: 0, observations: 0),
+ writeQueue: WriteQueue(queued: 0, capacity: 8),
+ providers: ProviderHealthSnapshot(
+ llm: ProviderRoleHealth(status: "ok"),
+ embedding: ProviderRoleHealth(status: "disabled")
+ )
+ )
+ #expect(!ok.isDegraded)
+
+ var queued = ok
+ queued.writeQueue = WriteQueue(queued: 1, capacity: 8)
+ #expect(queued.isDegraded)
+
+ var llmError = ok
+ llmError.writeQueue = WriteQueue(queued: 0, capacity: 8)
+ llmError.providers = ProviderHealthSnapshot(
+ llm: ProviderRoleHealth(status: "error"),
+ embedding: ProviderRoleHealth(status: "ok")
+ )
+ #expect(llmError.isDegraded)
+
+ var embedError = ok
+ embedError.providers = ProviderHealthSnapshot(
+ llm: ProviderRoleHealth(status: "ok"),
+ embedding: ProviderRoleHealth(status: "error")
+ )
+ #expect(embedError.isDegraded)
+ }
+}
+
+struct IconStateTests {
+ @Test func derivedStates() {
+ let report = StatusReport(
+ version: "2.3.2",
+ counts: StatusCounts(pagesLatest: 1, pagesAll: 1, sessions: 0, observations: 0)
+ )
+ #expect(IconState.derived(launchd: .running, report: report, fetchFailed: false) == .ok)
+
+ var degraded = report
+ degraded.writeQueue = WriteQueue(queued: 3, capacity: 8)
+ #expect(IconState.derived(launchd: .running, report: degraded, fetchFailed: false) == .degraded)
+
+ #expect(IconState.derived(launchd: .notInstalled, report: nil, fetchFailed: true) == .notInstalled)
+ #expect(IconState.derived(launchd: .stopped, report: nil, fetchFailed: true) == .unreachable)
+ #expect(IconState.derived(launchd: .running, report: nil, fetchFailed: true) == .unreachable)
+ #expect(IconState.derived(launchd: .notInstalled, report: nil, fetchFailed: false) == .unknown)
+ #expect(
+ IconState.derived(
+ launchd: .running,
+ report: nil,
+ fetchFailed: true,
+ httpStatus: 401
+ ) == .authRequired
+ )
+ #expect(
+ IconState.applyingStartGrace(.unreachable, isStarting: true) == .starting
+ )
+ #expect(IconState.applyingStartGrace(.ok, isStarting: true) == .ok)
+ #expect(IconState.applyingStartGrace(.unreachable, isStarting: false) == .unreachable)
+ }
+}
diff --git a/companions/ai-memory-macos/Tests/AIMemoryMenuTests/LaunchdControllerTests.swift b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/LaunchdControllerTests.swift
new file mode 100644
index 00000000..164b8479
--- /dev/null
+++ b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/LaunchdControllerTests.swift
@@ -0,0 +1,74 @@
+import Foundation
+import Testing
+@testable import AIMemoryMenuCore
+
+struct LaunchdControllerTests {
+ @Test func substitutesPlaceholders() {
+ let template = """
+ <string>__AI_MEMORY_BIN__</string>
+ <string>__HOME__/Library/Logs/ai-memory/stderr.log</string>
+ """
+ let rendered = LaunchdController.renderTemplate(
+ template,
+ binary: URL(fileURLWithPath: "/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"),
+ home: URL(fileURLWithPath: "/Users/ada"),
+ dataDir: nil
+ )
+ #expect(rendered.contains("/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"))
+ #expect(rendered.contains("/Users/ada/Library/Logs/ai-memory/stderr.log"))
+ #expect(!rendered.contains("__AI_MEMORY_BIN__"))
+ #expect(!rendered.contains("EnvironmentVariables"))
+ }
+
+ @Test func injectsDataDirEnvironment() {
+ let template = """
+ <dict>
+ <key>Label</key>
+ <string>com.github.akitaonrails.ai-memory</string>
+ </dict>
+ """
+ let rendered = LaunchdController.renderTemplate(
+ template,
+ binary: URL(fileURLWithPath: "/bin/ai-memory"),
+ home: URL(fileURLWithPath: "/Users/ada"),
+ dataDir: URL(fileURLWithPath: "/Users/ada/.ai-memory")
+ )
+ #expect(rendered.contains("<key>AI_MEMORY_DATA_DIR</key>"))
+ #expect(rendered.contains("<string>/Users/ada/.ai-memory</string>"))
+ #expect(rendered.contains("<key>EnvironmentVariables</key>"))
+ }
+
+ @Test func rendersCheckedInLaunchdTemplate() throws {
+ let templateURL = repoRoot()
+ .appending(path: "packaging/launchd/com.github.akitaonrails.ai-memory.plist")
+ let template = try String(contentsOf: templateURL, encoding: .utf8)
+ let binary = URL(fileURLWithPath: "/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory")
+ let home = URL(fileURLWithPath: "/Users/ada")
+ let rendered = LaunchdController.renderTemplate(template, binary: binary, home: home, dataDir: nil)
+ #expect(LaunchdController.programArgumentsBinary(inPlist: rendered) == binary.path)
+ #expect(rendered.contains("/Users/ada/Library/Logs/ai-memory/stderr.log"))
+ #expect(rendered.contains("serve"))
+ #expect(rendered.contains("--enable-web"))
+ #expect(!rendered.contains("__HOME__"))
+ }
+
+ @Test func xmlEscapesDataDir() {
+ let template = "<dict></dict>"
+ let rendered = LaunchdController.renderTemplate(
+ template,
+ binary: URL(fileURLWithPath: "/bin/ai-memory"),
+ home: URL(fileURLWithPath: "/Users/ada"),
+ dataDir: URL(fileURLWithPath: "/tmp/a&b<c>")
+ )
+ #expect(rendered.contains("/tmp/a&amp;b&lt;c&gt;"))
+ }
+}
+
+private func repoRoot(file: String = #filePath) -> URL {
+ URL(fileURLWithPath: file)
+ .deletingLastPathComponent() // Tests/AIMemoryMenuTests
+ .deletingLastPathComponent() // Tests
+ .deletingLastPathComponent() // companions/ai-memory-macos
+ .deletingLastPathComponent() // companions
+ .deletingLastPathComponent() // repo
+}
diff --git a/companions/ai-memory-macos/Tests/AIMemoryMenuTests/RuntimeAndCliTests.swift b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/RuntimeAndCliTests.swift
new file mode 100644
index 00000000..84592bae
--- /dev/null
+++ b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/RuntimeAndCliTests.swift
@@ -0,0 +1,132 @@
+import Foundation
+import Testing
+@testable import AIMemoryMenuCore
+
+struct RuntimeAndCliTests {
+ @Test func layoutPointsAtTarballSiblings() {
+ let root = URL(fileURLWithPath: "/tmp/runtime")
+ let layout = RuntimeLayout(root: root)
+ #expect(layout.binary.path.hasSuffix("/runtime/ai-memory"))
+ #expect(layout.hooks.path.hasSuffix("/runtime/hooks"))
+ #expect(layout.plistTemplate.path.hasSuffix("/packaging/launchd/com.github.akitaonrails.ai-memory.plist"))
+ }
+
+ @Test func validateRequiresBinaryHooksAndPlist() throws {
+ let dir = FileManager.default.temporaryDirectory
+ .appending(path: "ai-memory-menu-runtime-\(UUID().uuidString)")
+ defer { try? FileManager.default.removeItem(at: dir) }
+
+ let layout = RuntimeLayout(root: dir)
+ #expect(!layout.validate())
+
+ try FileManager.default.createDirectory(at: layout.hooks, withIntermediateDirectories: true)
+ try FileManager.default.createDirectory(
+ at: layout.plistTemplate.deletingLastPathComponent(),
+ withIntermediateDirectories: true
+ )
+ try Data().write(to: layout.binary)
+ try Data().write(to: layout.plistTemplate)
+ #expect(!layout.validate())
+
+ try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: layout.binary.path)
+ #expect(layout.validate())
+ }
+
+ @Test func resolvePrefersEnvironmentOverride() throws {
+ let dir = FileManager.default.temporaryDirectory
+ .appending(path: "ai-memory-menu-env-\(UUID().uuidString)")
+ defer { try? FileManager.default.removeItem(at: dir) }
+ let layout = RuntimeLayout(root: dir)
+ try FileManager.default.createDirectory(at: layout.hooks, withIntermediateDirectories: true)
+ try FileManager.default.createDirectory(
+ at: layout.plistTemplate.deletingLastPathComponent(),
+ withIntermediateDirectories: true
+ )
+ try Data().write(to: layout.binary)
+ try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: layout.binary.path)
+ try Data().write(to: layout.plistTemplate)
+
+ let resolved = RuntimeLayout.resolve(
+ bundle: Bundle.main,
+ environment: ["AI_MEMORY_MENU_RUNTIME": dir.path]
+ )
+ #expect(resolved?.root.path == dir.path)
+ }
+
+ @Test func needsInitOnlyWhenConfigMissing() throws {
+ let dir = FileManager.default.temporaryDirectory
+ .appending(path: "ai-memory-menu-init-\(UUID().uuidString)")
+ defer { try? FileManager.default.removeItem(at: dir) }
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ #expect(FirstRun.needsInit(dataDir: dir))
+ try "bind = \"127.0.0.1:49374\"\n".write(
+ to: dir.appending(path: "config.toml"),
+ atomically: true,
+ encoding: .utf8
+ )
+ #expect(!FirstRun.needsInit(dataDir: dir))
+ }
+
+ @Test func bundledCLIInvokesInitAndStatus() throws {
+ let runner = MockRunner()
+ runner.results.append(ProcessResult(exitCode: 0, stdout: "initialized\n", stderr: ""))
+ runner.results.append(ProcessResult(exitCode: 0, stdout: "ai-memory 2.3.2 (server)\n", stderr: ""))
+ let cli = BundledCLI(
+ runtime: RuntimeLayout(root: URL(fileURLWithPath: "/tmp/runtime")),
+ runner: runner
+ )
+ let dataDir = URL(fileURLWithPath: "/tmp/data")
+ _ = try cli.initDataDir(dataDir)
+ _ = try cli.status(
+ serverURL: URL(string: "http://127.0.0.1:49374")!,
+ token: "secret",
+ dataDir: dataDir
+ )
+ #expect(runner.calls.count == 2)
+ #expect(runner.calls[0].arguments == ["--data-dir", "/tmp/data", "init"])
+ #expect(runner.calls[1].arguments == ["--data-dir", "/tmp/data", "status"])
+ #expect(runner.calls[1].extraEnv["AI_MEMORY_SERVER_URL"] == "http://127.0.0.1:49374")
+ #expect(runner.calls[1].extraEnv["AI_MEMORY_AUTH_TOKEN"] == "secret")
+ }
+
+ @Test func bundledCLISurfacesNonZeroExit() {
+ let runner = MockRunner()
+ runner.results.append(ProcessResult(exitCode: 2, stdout: "", stderr: "could not reach server\n"))
+ let cli = BundledCLI(
+ runtime: RuntimeLayout(root: URL(fileURLWithPath: "/tmp/runtime")),
+ runner: runner
+ )
+ do {
+ _ = try cli.status(
+ serverURL: URL(string: "http://127.0.0.1:49374")!,
+ token: nil,
+ dataDir: nil
+ )
+ Issue.record("expected failure")
+ } catch let CliError.failed(code, output) {
+ #expect(code == 2)
+ #expect(output.contains("could not reach server"))
+ } catch {
+ Issue.record("wrong error \(error)")
+ }
+ }
+}
+
+private final class MockRunner: CommandRunning, @unchecked Sendable {
+ struct Call {
+ var binary: URL
+ var arguments: [String]
+ var extraEnv: [String: String]
+ }
+
+ var calls: [Call] = []
+ var results: [ProcessResult] = []
+
+ func run(binary: URL, arguments: [String], extraEnv: [String: String]) throws -> ProcessResult {
+ calls.append(Call(binary: binary, arguments: arguments, extraEnv: extraEnv))
+ if results.isEmpty {
+ return ProcessResult(exitCode: 0, stdout: "", stderr: "")
+ }
+ return results.removeFirst()
+ }
+}
diff --git a/companions/ai-memory-macos/Tests/AIMemoryMenuTests/fixtures/status.json b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/fixtures/status.json
new file mode 100644
index 00000000..ea0ca486
--- /dev/null
+++ b/companions/ai-memory-macos/Tests/AIMemoryMenuTests/fixtures/status.json
@@ -0,0 +1,31 @@
+{
+ "version": "2.3.2",
+ "data_dir": "/Users/test/Library/Application Support/ai-memory",
+ "bind": "127.0.0.1:49374",
+ "db_path": "/Users/test/Library/Application Support/ai-memory/db/memory.sqlite",
+ "counts": {
+ "pages_latest": 138,
+ "pages_all": 162,
+ "sessions": 27,
+ "observations": 4198
+ },
+ "write_queue": [0, 128],
+ "providers": {
+ "llm": {
+ "status": "ok",
+ "provider": "openai",
+ "model": "gpt-4.1"
+ },
+ "embedding": {
+ "status": "disabled"
+ },
+ "llm_candidates": []
+ },
+ "ingest": {
+ "accepted": 4198,
+ "dropped_by_policy": 12,
+ "shed_saturated": 0,
+ "shed_rate_limited": 0,
+ "last_persisted_ms": 1700000000000
+ }
+}
diff --git a/companions/ai-memory-macos/build.sh b/companions/ai-memory-macos/build.sh
new file mode 100755
index 00000000..e215e41e
--- /dev/null
+++ b/companions/ai-memory-macos/build.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Build AI Memory.app: Swift menu bar + staged ai-memory runtime (binary + hooks).
+set -euo pipefail
+
+COMPANION="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$COMPANION/../.." && pwd)"
+DIST="${1:-$COMPANION/dist/AI Memory.app}"
+CONFIG="${CONFIGURATION:-release}"
+
+echo "building ai-memory ($CONFIG) from $ROOT"
+if [[ "$CONFIG" == "release" ]]; then
+ cargo build --release --bin ai-memory --manifest-path "$ROOT/Cargo.toml"
+ BINARY="$ROOT/target/release/ai-memory"
+ SWIFT_FLAGS=(-c release)
+else
+ cargo build --bin ai-memory --manifest-path "$ROOT/Cargo.toml"
+ BINARY="$ROOT/target/debug/ai-memory"
+ SWIFT_FLAGS=(-c debug)
+fi
+
+echo "building AIMemoryMenu"
+swift build "${SWIFT_FLAGS[@]}" --package-path "$COMPANION"
+BIN_PATH="$(swift build "${SWIFT_FLAGS[@]}" --package-path "$COMPANION" --show-bin-path)"
+
+APP="$DIST"
+echo "staging $APP"
+rm -rf "$APP"
+mkdir -p "$APP/Contents/MacOS"
+mkdir -p "$APP/Contents/Resources/runtime/packaging/launchd"
+
+cp "$BIN_PATH/AIMemoryMenu" "$APP/Contents/MacOS/AIMemoryMenu"
+cp "$COMPANION/Info.plist" "$APP/Contents/Info.plist"
+printf 'APPL????' > "$APP/Contents/PkgInfo"
+
+cp "$BINARY" "$APP/Contents/Resources/runtime/ai-memory"
+chmod 755 "$APP/Contents/Resources/runtime/ai-memory"
+rsync -a --delete "$ROOT/hooks/" "$APP/Contents/Resources/runtime/hooks/"
+cp "$ROOT/packaging/launchd/com.github.akitaonrails.ai-memory.plist" \
+ "$APP/Contents/Resources/runtime/packaging/launchd/"
+
+echo "built $APP"
+echo "runtime: $APP/Contents/Resources/runtime/ai-memory"
+echo "open with: open \"$APP\""
diff --git a/docs/companion-crates.md b/docs/companion-crates.md
index 68005d60..e577cf7b 100644
--- a/docs/companion-crates.md
+++ b/docs/companion-crates.md
@@ -178,6 +178,56 @@ Re-home by kind:
6. Only after repeated usage, consider whether ai-memory core lacks a small,
generic API seam; do not start by patching core endpoints.
+## `ai-memory-macos`: menu bar wrapper
+
+Self-contained macOS accessory app at
+[`companions/ai-memory-macos`](../companions/ai-memory-macos). It is a
+**wrapper**, not a data-seam dashboard: it ships the `ai-memory` binary and
+`hooks/` tree inside an `.app`, governs the existing LaunchAgent, and opens
+`/web`, `ai-memory status`, `config.toml`, the data directory, and logs.
+
+It is not a root workspace member. Build and test it separately:
+
+```bash
+./companions/ai-memory-macos/build.sh
+swift test --package-path companions/ai-memory-macos
+```
+
+### Goal
+
+Give macOS a first-class install that does not require a prior tarball, without
+reimplementing status, search, wiki browsing, or config editing in SwiftUI.
+
+### How it talks to ai-memory
+
+- `GET /admin/status` for the menu-bar traffic light and two headline lines
+ (version, page/session counts, LLM role).
+- Bundled `ai-memory status` / `ai-memory init` via `Process` (the real CLI).
+- `launchctl` against `com.github.akitaonrails.ai-memory` and the checked-in
+ plist template in `packaging/launchd/`.
+- `NSWorkspace` to open `/web`, `config.toml`, the data dir, and logs.
+
+It does not open SQLite or the wiki, does not call writable `/admin` routes, and
+does not add MCP tools.
+
+### Data vs bundle
+
+Durable state stays in `~/Library/Application Support/ai-memory` (the binary’s
+existing macOS default) and logs under `~/Library/Logs/ai-memory`. Replacing
+`/Applications/AI Memory.app` does not rewrite that tree. An optional data-dir
+override is written only into the rendered LaunchAgent plist
+(`AI_MEMORY_DATA_DIR`), never into the bundle.
+
+### Safety requirements
+
+- Do not silently start the LaunchAgent on first launch; **Install & Start**
+ is an explicit click.
+- Do not write `AI_MEMORY_AUTH_TOKEN` into the plist. The menu bar’s own HTTP
+ client may keep a bearer in the Keychain.
+- Do not sandbox the app in a way that blocks `launchctl` or LaunchAgents.
+
+See [`docs/macos.md`](macos.md#scenario-d-menu-bar-app).
+
## `ai-memory-web-editor`: browser chat/editor companion
This is the companion shape for PR #123.
diff --git a/docs/cookbook.md b/docs/cookbook.md
index c32f086e..12198f2b 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -1,7 +1,8 @@
# ai-memory cookbook
A task-oriented cheat sheet: "I want to do X" → how. For the full reference see
-[`ARCHITECTURE.md`](ARCHITECTURE.md); for install see [`install.md`](install.md);
+[`ARCHITECTURE.md`](ARCHITECTURE.md); for install see [`install.md`](install.md)
+(including the [macOS menu bar app](install.md#macos-menu-bar-app));
for the tool-routing table see [`usage.md`](usage.md).
## What ai-memory is, in one paragraph
@@ -87,6 +88,30 @@ before implementing against it.
add the export endpoint" (`memory_message_send`), and over there "check my
inbox" (`memory_message_pop`). See [`agent-messaging.md`](agent-messaging.md).
+## Recipe: run the server on a Mac
+
+Use the menu bar app when you want one `.app` that starts the server and
+opens the existing tools (web UI, `ai-memory status`, config, logs). It does
+not replace those tools with a second dashboard.
+
+```bash
+./companions/ai-memory-macos/build.sh
+open "companions/ai-memory-macos/dist/AI Memory.app"
+```
+
+Drag **AI Memory.app** to `/Applications`, then **Install & Start Server**
+from the menu extra. Wire an agent with the bundled binary:
+
+```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 stays in `~/Library/Application Support/ai-memory`. Replacing the
+`.app` does not rewrite it. Full paths (tarball, source, Docker, launchd):
+[`macos.md`](macos.md).
+
## From the terminal (CLI)
Most people never need these — the agent does it — but they exist:
diff --git a/docs/install.md b/docs/install.md
index 1e86f884..df10acad 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,13 +1,16 @@
# Installation cookbook
The [README quick-start](../README.md#quick-start) covers the happy
-path (docker + Claude Code). This page covers everything else:
+paths (Docker + Claude Code, Arch AUR, macOS menu bar app). This page
+covers everything else:
- [Server on a different machine](#server-on-a-different-machine)
(homelab, LAN box, remote server)
- [Configuring the CLI URL and auth](#configuring-the-cli-url-and-auth)
- [Arch Linux native packages (AUR)](#arch-linux-native-packages-aur)
(systemd system service or user service)
+- [macOS menu bar app](#macos-menu-bar-app)
+ (self-contained `.app` + LaunchAgent)
- [Configuring other agent CLIs](#configuring-other-agent-clis)
(Codex, Command Code, Devin CLI, OpenCode, OMP, Pi, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, Grok Build CLI, Zero, ZCode, Kimi Code, Kiro CLI, Pool, OpenClaw, VS Code Copilot, Zed)
- [Installing hooks without docker](#installing-hooks-without-docker)
@@ -714,6 +717,42 @@ AI_MEMORY_NATIVE_TEST_IMAGE=quay.io/toolbx/arch-toolbox:latest scripts/test-nati
---
+## macOS menu bar app
+
+On a Mac, the self-contained menu bar app is the GUI install: it bundles the
+native `ai-memory` binary and `hooks/` tree, governs the existing LaunchAgent
+(`com.github.akitaonrails.ai-memory`), and opens `/web`, `ai-memory status`,
+`config.toml`, the data directory, and logs. It does not replace those tools
+with a second dashboard.
+
+Needs a Rust toolchain and Xcode / Swift 6 (the same as a source build):
+
+```bash
+git clone https://github.com/akitaonrails/ai-memory
+cd ai-memory
+./companions/ai-memory-macos/build.sh
+open "companions/ai-memory-macos/dist/AI Memory.app"
+```
+
+Drag **AI Memory.app** to `/Applications`, then **Install & Start Server**
+from the menu extra (no Dock icon). When the status item is green, wire an
+agent with the bundled binary so `install-hooks` finds the sibling `hooks/`
+tree:
+
+```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
+```
+
+Durable memory stays in `~/Library/Application Support/ai-memory`. Replacing
+the `.app` is an update and does not rewrite that tree. Prebuilt tarball,
+source-build, Docker-wrapper, and hand-installed launchd paths remain in
+[`docs/macos.md`](macos.md). Companion source:
+[`companions/ai-memory-macos`](../companions/ai-memory-macos).
+
+---
+
## Configuring other agent CLIs
> `install-mcp --server-url` accepts either the bare server origin or the full
@@ -1543,7 +1582,9 @@ The `serve` subcommand also accepts:
| _(config only)_ | `AI_MEMORY_HOOK_RATE_PER_SEC`, `AI_MEMORY_HOOK_RATE_BURST` | Optional per-actor/session hook ingest token bucket. Unset/`0` rate disables it; burst defaults to the rate (minimum one token when enabled). |
On macOS, see [`docs/macos.md`](macos.md); use the archive matching your
-architecture: `aarch64` for Apple Silicon, `x86_64` for Intel. On Windows, see
+architecture: `aarch64` for Apple Silicon, `x86_64` for Intel. The
+[menu bar app](#macos-menu-bar-app) is the self-contained GUI path (bundles
+the binary, starts the LaunchAgent, opens `/web` and status). On Windows, see
[`docs/windows.md`](windows.md).
The short version: run the install commands from the same environment that
launches the agent. WSL2-launched agents need WSL paths and POSIX `.sh` hooks.
@@ -2369,6 +2410,11 @@ unrelated Compose project just because its file occupies a conventional path;
the wrapper instead writes the inspected standalone recreation script for
review, preserving the existing `/data` mount and other runtime options.
+The macOS menu bar app is not covered by `ai-memory upgrade`. Rebuild with
+`./companions/ai-memory-macos/build.sh` (or replace `/Applications/AI Memory.app`
+with a newer staged bundle). Wiki, SQLite, config, and models stay in
+`~/Library/Application Support/ai-memory`.
+
Set `AI_MEMORY_NO_VERSION_CHECK=1` to silence the daily check. To pin wrapper
self-upgrades to a fork or tagged release, set `AI_MEMORY_WRAPPER_URL=<url>`;
the wrapper requires `<url>.sha256` unless
@@ -2412,6 +2458,8 @@ write to `~/.local/share/ai-memory/hooks/`.
## See also
+- [`docs/macos.md`](macos.md) - macOS install paths: menu bar app, native
+ release tarball, source build, Docker wrapper, and launchd
- [`docs/deploy.md`](deploy.md) - homelab deploy walkthrough
(`bin/deploy`, cloudflared TLS, env-file management)
- [`docs/usage.md`](usage.md) - handoffs, proactive querying, web UI, slim
diff --git a/docs/macos.md b/docs/macos.md
index f1215822..389d7675 100644
--- a/docs/macos.md
+++ b/docs/macos.md
@@ -4,12 +4,23 @@ 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** (a prebuilt release or a source build) is the
-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.
+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)** — self-contained
+ `.app` that bundles the binary, starts the LaunchAgent, and opens `/web`,
+ status, and config. 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)** — 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. There is no WSL-vs-native split to get wrong.
@@ -32,6 +43,10 @@ normal Terminal.
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)
Use this when you want a local server plus native hooks without a Rust toolchain
@@ -174,10 +189,56 @@ 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.
+3. **Open Web UI**, **Show Status…**, **Open Config**, **Open Data Directory**,
+ and **Open Logs** call the existing browser UI, the bundled CLI, and Finder.
+
+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)
-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
+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
@@ -329,6 +390,16 @@ wrapper's `posix` shell-script path does not. Re-run `install-hooks --agent
reuse that stale copy instead and report success. Run `install-hooks` via
the real extracted/built path instead of the symlink
until that's fixed.
+- **No Dock icon after opening AI Memory.app:** that is the menu extra. Look
+ in the menu bar (brain / status symbol), not the Dock.
+- **Menu extra says "Runtime not bundled":** `swift run` from the package
+ does not stage `ai-memory` + `hooks/`. Use
+ `./companions/ai-memory-macos/build.sh`.
+- **Install & Start does not turn the item green:** check
+ `~/Library/Logs/ai-memory/stderr.log` and
+ `launchctl print gui/$(id -u)/com.github.akitaonrails.ai-memory`. The app
+ never writes into its own bundle; a missing `config.toml` is created under
+ `~/Library/Application Support/ai-memory` by bundled `ai-memory init`.
## Suggested Test Checklist
@@ -343,6 +414,11 @@ wrapper's `posix` shell-script path does not. Re-run `install-hooks --agent
5. Launch the agent, call `memory_status`, send a prompt, then confirm capture
(`ai-memory status` shows non-zero observations, or query the SQLite
`observations` table).
+6. **Scenario D:** after **Install & Start Server**, the menu extra is green;
+ **Open Web UI** loads `http://127.0.0.1:49374/web`;
+ `launchctl print gui/$(id -u)/com.github.akitaonrails.ai-memory` shows
+ `state = running`; replacing the `.app` leaves
+ `~/Library/Application Support/ai-memory` untouched.
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.
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 91595628..295e904e 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -7,7 +7,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, which include a per-user launchd agent. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](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. A source-built menu bar app (`companions/ai-memory-macos`) bundles that binary, starts the LaunchAgent, and opens `/web` and `ai-memory status` — README quick-start and [`docs/macos.md`](macos.md) Scenario D. |
| 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`](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/usage.md b/docs/usage.md
index dd80012d..2ab55183 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -385,6 +385,9 @@ Start the server with `--enable-web` and open
ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web
```
+On macOS the [menu bar app](macos.md#scenario-d-menu-bar-app) already starts
+the LaunchAgent with `--enable-web`; **Open Web UI** opens that same URL.
+
Docker compose users can add the flag to the service command:
```yaml