ai-memory/docs/support-matrix.md

Support Matrix

The complete platform and agent matrix, with integration notes. Moved verbatim from the README front page, which keeps a compact view.

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.
NixOS	Supported	Flake package (nix build / nix run) plus nixosModules.default (services.ai-memory.enable) with a hardened systemd unit, typed/freeform settings → generated config.toml, and agenix / sops-nix / environmentFile secrets. Web UI opt-in (enableWeb = false by default). settings (including llm_headers) lands in a world-readable Nix store path — keep secrets in age/sops/env. CI: Linux package + module eval on path-filtered PRs; Darwin package and privileged container smoke on schedule / dispatch / nix or full-ci label. See README NixOS section and docs/install.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 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. Native ai-memory upgrade is supported for writable x86_64 zip installs (checksum-verified zip + rename-aside self-replace + sibling hooks/ refresh). 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.
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).
Codex	Supported	MCP config + lifecycle hooks; native commands enforce capture exclusions. SessionEnd is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and ai-memory finalize-session --agent codex is the fallback. Managed runs (ai-memory run codex) can lose continuity through Codex's shared daemon inheriting a stale run id; launch with --no-daemon until #987 is fixed (see docs/managed-workstreams.md). 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) — Codex's Stop payload carries last_assistant_message, same as Claude Code.
Command Code	Supported	MCP config (~/.commandcode/mcp.json) + its four stable lifecycle-hook events (~/.commandcode/settings.json); native commands enforce capture exclusions and SessionStart injects handoffs. Stop is only a turn boundary, so use ai-memory finalize-session --agent command-code after the final turn; an interactive session launched with ai-memory run command-code is finalized automatically when it exits if the run can tie the session to itself (see docs/managed-workstreams.md). ai-memory run command-code adds exact v3 native-session resume and visible-event import; experimental unsandboxed Mods remain excluded.
Devin CLI	Supported	MCP config + lifecycle hooks. Hooks use Devin's PostCompaction event, inject handoffs via hookSpecificOutput.additionalContext, and omit subagent events because Devin does not expose them.
OpenCode	Supported	Remote MCP config + generated TypeScript plugin; generated plugin enforces capture exclusions.
OpenCode 2 (opencode2 beta)	Supported	V2 mcp.servers remote MCP config + generated TypeScript plugin (ai-memory-opencode2.ts) for the OpenCode 2.0.10+ event API, checked against 2.0.14; shares v1's config dir, session store, and agent kind. Completed root turns checkpoint the session page and baton without ending the shared service's session; MCP calls route by the native _meta session id, so concurrent sessions in different projects stay isolated. --capture-assistant is supported (double opt-in). Managed runs launch, resume, and import; ledger-delta acknowledgement is limited by the shared background service (see managed-workstreams notes).
Cursor	Supported	MCP config + lifecycle hooks.
Gemini CLI	Supported	MCP config + lifecycle hooks.
Oh My Pi / OMP	Supported	Use --client omp / --agent omp (or oh-my-pi) for native .omp MCP config + TypeScript extension; generated extension enforces capture exclusions.
Pi	Supported	Generated ~/.pi/agent/extensions/ai-memory-pi.ts extension provides lifecycle capture and an HTTP MCP bridge; generated extension enforces capture exclusions.
Crush	Managed-only	ai-memory run crush resumes its project-local session database and supplies portable context through a temporary supported global-context file; no lifecycle-hook installer is provided.
Managed workstreams	Opt-in	ai-memory run provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, OpenCode 2 beta, Pi, Crush, Kimi Code, Command Code, both incompatible Kiro CLI engines, OMP, Grok Build CLI, and Antigravity CLI. Direct launches remain unchanged. See docs/managed-workstreams.md.
--yolo safety + ai-jail	Linux/macOS; Windows partial	ai-memory run --yolo warns before it disarms an agent's permission prompts and, on Linux/macOS, offers to re-exec the session inside ai-jail when it is usable — installed and with its sandbox backend present (bwrap / sandbox-exec); otherwise it asks nothing and proceeds (--network, forwarding only already-set credential/config env vars). Accepting the offer shows a checklist of ai-jail toggles pre-marked with smart defaults (credentials present on the host, SSH for an SSH origin, worktree metadata in a linked worktree; Docker socket, GPU, display, Pictures, Tailscale unchecked). --jail re-runs inside ai-jail without asking (also without --yolo and non-interactively; it errors when ai-jail is not usable), --jail=github,aws,no-mise is exact (every unnamed checklist row is forced off with --no-X; all/none too; the checklist likewise passes unchecked rows as --no-X, while bare --jail leaves unmarked rows to your ai-jail config), and --no-jail skips the offer. Only toggles the installed ai-jail supports are offered; the credential mounts (github, aws, kube, gcloud, docker-config) need ai-jail 2.5.0. A project .ai-jail in the launch directory replaces the checklist and the bare---jail defaults (ai-jail loads it as-is; --jail=… still overrides), and every re-exec passes --no-save-config so ai-jail never writes the run's flags into it. Both prompts are skipped on a non-interactive stdin/stderr and when already detected inside ai-jail. Windows gets the warning but never the ai-jail offer (ai-jail is Linux/macOS-only). Opt-in --true-yolo implies --yolo and, for Claude only, additionally forces bypassPermissions over any settings defaultMode (interchangeable with --yolo for other harnesses); claude_true_yolo applies the same Claude extra to --yolo launches. Claude's own explicit ask rules and command-safety checks still prompt in every mode. See docs/design-yolo-safety-ai-jail.md.
Claude Desktop (Chat)	MCP-only	Uses mcp-remote; the ordinary Chat surface does not run plugin hooks. Cowork plugins can run hooks, but ai-memory does not yet ship a Cowork plugin integration; see the explicit boundary in mcp-install.md.
OpenClaw	Supported	MCP config + native plugin lifecycle hooks; generated plugin enforces capture exclusions.
Antigravity CLI	Supported	MCP config (serverUrl) + lifecycle hooks (agy alias). Only PreInvocation with invocationNum = 0 maps to SessionStart; later model calls cannot consume a next-session handoff. No automatic true session-end hook, so run ai-memory finalize-session --agent antigravity-cli after the final turn when you need a summary, handoff, and opt-in SessionEnd consolidation; an interactive session launched with ai-memory run antigravity is finalized automatically when it exits if the run can tie the session to itself (see docs/managed-workstreams.md). ai-memory run antigravity (aliases antigravity-cli, agy) adds managed workstream resume via --conversation; conversation text is not decoded, so the ledger for this harness comes from hook capture. Tool outputs (run_command, view_file, list_dir, etc.) are resolved directly from .system_generated/steps/<stepIdx>/output.txt during post-tool-use while mutation tools preserve code from arguments (#966).
Grok Build CLI	Supported	MCP config (install-mcp --client grok → $GROK_HOME/config.toml, default ~/.grok/config.toml) + lifecycle hooks (install-hooks --agent grok → $GROK_HOME/hooks/ai-memory.json, default ~/.grok/hooks/ai-memory.json, Grok-specific hook bundle). Capture works. SessionStart and UserPromptSubmit do not accept the handoff (Grok discards that stdout). The first PostToolUse prints hookSpecificOutput.additionalContext with the pending handoff and an opted-in [briefing]; the model sees it after that tool result. If no tool runs, recover via MCP memory_handoff_list then memory_handoff_accept with that handoff_id. ai-memory run grok adds managed workstream resume with the context packet delivered natively through --rules. Skills root: .grok/skills / $GROK_HOME/skills (default ~/.grok/skills).
Swival CLI	MCP-only	install-mcp --client swival --apply merges a native HTTP entry into the project-root .swival/mcp.json, preserving sibling servers. Lifecycle and managed-workstream support are not claimed because Swival's callback contract does not expose a stable session identifier.
Zero	Supported	install-mcp --client zero (native HTTP + bearer in ~/.config/zero/config.json) + lifecycle hooks via install-hooks --agent zero --apply (exec-form native commands in ~/.config/zero/hooks.json, JSON payload on stdin, no shell). Capture works incl. specialist (subagent) events; no handoff injection — Zero discards sessionStart stdout, so recover handoffs via MCP memory_handoff_list then memory_handoff_accept with that handoff_id.
ZCode	Supported	install-mcp --client zcode --apply merges a native HTTP entry (strict schema: type/url/headers only) into the mcp.servers map of ~/.zcode/cli/config.json, preserving sibling servers. ZCode (z.ai, zcode, alias zai). Lifecycle-hook capture via install-hooks --agent zcode --apply: exec-form native commands (type: "process", no shell) merged into the root hooks block of ~/.zcode/cli/config.json around any third-party hooks; native commands enforce capture exclusions. Six documented triggers (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop); PostToolUseFailure fires instead of PostToolUse when a tool throws and lands on the same capture channel with the error preserved. PermissionRequest is deliberately not installed — its hook chain races the interactive permission client, so passive capture of that event is unreliable by design. No true session-end — Stop is a per-turn boundary, so run ai-memory finalize-session --agent zcode after the final turn. Unlike Pool and Zero, SessionStart stdout injection works (hookSpecificOutput.additionalContext, verified live against the embedded engine v0.16.5), so the prior session's handoff is delivered automatically. No first-party install-mcp client and no managed workstream are claimed yet.
Kimi Code	Supported	MCP config (url entry in ~/.kimi-code/mcp.json) + lifecycle hooks ([[hooks]] in ~/.kimi-code/config.toml, 10 events including subagent start/stop and PostToolUseFailure for tool-failure capture); both paths honor $KIMI_CODE_HOME. Handoffs inject via UserPromptSubmit stdout (Kimi Code discards SessionStart hook stdout); ai-memory run kimi adds managed workstream resume.
Kiro CLI	Supported	MCP config uses install-mcp --client kiro-cli (alias kiro) and Kiro's Bedrock-compatible schema flavor. install-hooks --agent kiro-cli merges v2 hooks into existing agent configs; the explicit --agent kiro-cli-v3 target writes the incompatible standalone v3 registration. Both preserve unrelated entries, honor $KIRO_HOME, enforce capture exclusions, and inject pending handoffs at session start. Kiro has no true SessionEnd hook; use ai-memory finalize-session --agent kiro-cli, with --session-id <uuid> for concurrent sessions, unless it is an interactive session launched with ai-memory run kiro, which finalizes it automatically when it exits if the run can tie the session to itself (see docs/managed-workstreams.md). ai-memory run kiro manages v2; add --v3, --mode, or --agent-engine v3 for version-safe v3 resume.
Pool	Hooks-only	Poolside Agent CLI (pool). Lifecycle-hook capture via install-hooks --agent pool (alias poolside): Pool reads project-scoped hooks from the repo-root .poolside/settings.yaml, so ai-memory stages the scripts and prints a ready-to-paste hooks: snippet rather than writing project-local files; native commands enforce capture exclusions. Five Claude-shaped events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) and no true session-end — Stop is a turn boundary, so run ai-memory finalize-session --agent pool after the final turn. SessionStart stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP memory_handoff_list then memory_handoff_accept with that handoff_id. No first-party install-mcp client and no managed workstream (ai-memory run pool) are claimed: Pool's native session-store contract is not demonstrated (see docs/managed-harness-contributions.md). Verified against Poolside CLI v1.0.16.
VS Code Copilot	MCP-only	.vscode/mcp.json for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet).
Zed	MCP-only	Native remote MCP under context_servers in Zed's user settings.json; no lifecycle hooks or managed-workstream support.
Muse Code	MCP-only	install-mcp --client muse merges a native streamable-HTTP entry with bearer headers into the snake_case mcp_servers map of ~/.config/muse/settings.json, preserving sibling servers. The writer adds the mandatory "schema_version": 1 when absent (without it every muse command fails at startup) and never rewrites an existing value, and it sets "mode": "optional" because Muse's default required aborts the whole run when the server is unreachable. Skills need no extra step: Muse reads ~/.agents/skills, which install-skills already writes. Lifecycle capture and managed workstreams are not claimed — Muse documents a hook surface, but the output contract of its SessionStart event is not specified.
Hermes Agent	Supported	install-hooks --agent hermes (alias hermes-agent) prints a ready-to-paste hooks: block for ~/.hermes/config.yaml. Hermes splits each configured command with shlex.split and runs it with no shell, passing the event JSON on stdin, so the entries invoke the native ai-memory hook command (exec form, like Zero and ZCode — no script bundle is staged); ai-memory never writes that YAML file, which is yours to edit and which Hermes itself gates behind its hook-acceptance prompt (hooks_auto_accept). Two tool events are wired, pre_tool_call → pre-tool-use and post_tool_call → post-tool-use; their tool_name / tool_input payload drives concrete session attribution, tool-family titles, and capture exclusions. Session lifecycle (recall, prompt capture, session-end, automatic handoff) is owned by the community-maintained ai-memory-hermes-plugin memory provider, so no hook-driven session-end is installed and nothing is duplicated; review that plugin's compatibility matrix, install/uninstall scripts, and secret handling before enabling it. No first-party install-mcp client and no managed workstream are claimed yet, and because Hermes ignores session-start hook stdout a pending handoff is recovered through MCP (memory_handoff_list then memory_handoff_accept).
LLM/auth providers	Supported	Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode (Go and Zen), OpenAI-compatible endpoints, and generic OIDC device auth for native hooks.
Embedding providers	Supported	OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM.