Skip to content

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

Rust

Merge branch 'main' into pr-569; port the launchd note to the split-out support matrix

AkitaOnRails0daf34157904
diff --cc CHANGELOG.md
index 1227908f,ea601c30..91471f37
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -7,23 -7,244 +7,260 @@@ and this project adheres to [Semantic V
## [Unreleased]
+ ### Fixed
+ - `install-hooks` now writes the capture-mode opt-in atomically. It was
+ written in place, and every reader maps an unrecognised value onto
+ `denylist` — the less private mode — so a crash, a full disk or a killed
+ `ai-memory upgrade` mid-write left a truncated file that silently reverted
+ an `--capture-mode allowlist` opt-in to capture-by-default, which is exactly
+ what `persist_capture_mode` documents it must never do. The fallback itself
+ is correct and stays; the torn write that triggered it is gone. Now routed
+ through the same `write_atomic` (tmp + fsync + rename) the rest of the CLI
+ already uses, per the project's atomic-writes invariant.
+ ||||||| parent of f14775e5 (fix: post-audit findings across the 2.0 range)
+ - The 2.0 pre-release audit findings (post-merge adversarial review of
+ the whole range): `export-okf` no longer fails on real deployments —
+ scope manifests are OKF-typed at their writer (ending a startup
+ tug-of-war that reverted the migration's typing on the same boot and
+ self-healing manifests reverted by pre-fix binaries), approved
+ auto-improve pages land conformant like every other write (also
+ preventing phantom supersedes on the first reindex after a binary
+ upgrade), and `_pending/` proposal sidecars are excluded from the
+ export walk. Pages retired WITHOUT a successor (decay tombstones,
+ purge-regenerate, workspace merges) now close their entity-link
+ validity windows so `as_of` cannot resurrect retired knowledge, with
+ a V58 backfill for previously retired rows. The experience pass no
+ longer burns its cadence window or stages an empty run when a scope
+ has too few session pages. Backup destination guards canonicalize
+ paths; `as_of` parse errors return invalid-params; the FTS5 probe
+ connection is cached per thread.
+ - `status` no longer overstates missing embeddings: empty-body pages —
+ which no embedder can ever cover and the backfill skips by rule — are
+ excluded from the "latest pages missing" figure and reported on their
+ own line (observed live as a permanently stuck 427).
+ - Natural-language searches no longer surface stopword trash: bare
+ queries drop English stopwords before the FTS5 OR-join, so a page
+ containing five "the"s cannot outrank the page whose content matches,
+ and pages matching only stopwords no longer appear at all. Quoted
+ phrases and explicit-operator queries are untouched, and an
+ all-stopword query still searches its literal terms. Guarded by a
+ CI-runnable search-quality suite asserting ranking usefulness, not
+ just machinery.
+ - `memory_query` no longer fails with `fts5: syntax error` when the query is
+ natural language containing parentheses, apostrophe-quoted phrases, or a
+ stray `OR`/`AND` (e.g. *"my visit to the Museum of Modern Art (MoMA) and
+ the 'Ancient Civilizations' exhibit"*). Prepared FTS5 queries are now
+ validated against the engine's own parser and degrade to an always-valid
+ quoted bag of words when the preserved operator form does not parse;
+ deliberate well-formed operator queries are preserved as before. Found by
+ the new LongMemEval retrieval harness on its first full run.
+
+ - `ai-memory serve` now takes an exclusive lock on `<data-dir>/.serve.lock`
+ before opening the store, so a second server pointed at the same data
+ directory refuses at startup and names the holding process instead of
+ silently contending the single-writer actor, the wiki git handle, and the
+ active-project pointer. The OS releases the lock when the process exits,
+ so a crashed server never leaves the operator locked out; `--force` starts
+ unguarded for an operator who knows the previous server is gone, and a
+ filesystem that cannot lock at all downgrades the guard to a warning
+ instead of refusing to start. (#563)
+
+ - `install-hooks` now writes the capture-mode opt-in atomically. It was
+ written in place, and every reader maps an unrecognised value onto
+ `denylist` — the less private mode — so a crash, a full disk or a killed
+ `ai-memory upgrade` mid-write left a truncated file that silently reverted
+ an `--capture-mode allowlist` opt-in to capture-by-default, which is exactly
+ what `persist_capture_mode` documents it must never do. The fallback itself
+ is correct and stays; the torn write that triggered it is gone. Now routed
+ through the same `write_atomic` (tmp + fsync + rename) the rest of the CLI
+ already uses, per the project's atomic-writes invariant.
+ - `status` no longer overstates missing embeddings: empty-body pages —
+ which no embedder can ever cover and the backfill skips by rule — are
+ excluded from the "latest pages missing" figure and reported on their
+ own line (observed live as a permanently stuck 427).
+ - Natural-language searches no longer surface stopword trash: bare
+ queries drop English stopwords before the FTS5 OR-join, so a page
+ containing five "the"s cannot outrank the page whose content matches,
+ and pages matching only stopwords no longer appear at all. Quoted
+ phrases and explicit-operator queries are untouched, and an
+ all-stopword query still searches its literal terms. Guarded by a
+ CI-runnable search-quality suite asserting ranking usefulness, not
+ just machinery.
+ - `memory_query` no longer fails with `fts5: syntax error` when the query is
+ natural language containing parentheses, apostrophe-quoted phrases, or a
+ stray `OR`/`AND` (e.g. *"my visit to the Museum of Modern Art (MoMA) and
+ the 'Ancient Civilizations' exhibit"*). Prepared FTS5 queries are now
+ validated against the engine's own parser and degrade to an always-valid
+ quoted bag of words when the preserved operator form does not parse;
+ deliberate well-formed operator queries are preserved as before. Found by
+ the new LongMemEval retrieval harness on its first full run.
+
+ - `ai-memory serve` now takes an exclusive lock on `<data-dir>/.serve.lock`
+ before opening the store, so a second server pointed at the same data
+ directory refuses at startup and names the holding process instead of
+ silently contending the single-writer actor, the wiki git handle, and the
+ active-project pointer. The OS releases the lock when the process exits,
+ so a crashed server never leaves the operator locked out; `--force` starts
+ unguarded for an operator who knows the previous server is gone, and a
+ filesystem that cannot lock at all downgrades the guard to a warning
+ instead of refusing to start. (#563)
+
+ - `install-hooks` now writes the capture-mode opt-in atomically. It was
+ written in place, and every reader maps an unrecognised value onto
+ `denylist` — the less private mode — so a crash, a full disk or a killed
+ `ai-memory upgrade` mid-write left a truncated file that silently reverted
+ an `--capture-mode allowlist` opt-in to capture-by-default, which is exactly
+ what `persist_capture_mode` documents it must never do. The fallback itself
+ is correct and stays; the torn write that triggered it is gone. Now routed
+ through the same `write_atomic` (tmp + fsync + rename) the rest of the CLI
+ already uses, per the project's atomic-writes invariant.
+ - `status` no longer overstates missing embeddings: empty-body pages —
+ which no embedder can ever cover and the backfill skips by rule — are
+ excluded from the "latest pages missing" figure and reported on their
+ own line (observed live as a permanently stuck 427).
+ - Natural-language searches no longer surface stopword trash: bare
+ queries drop English stopwords before the FTS5 OR-join, so a page
+ containing five "the"s cannot outrank the page whose content matches,
+ and pages matching only stopwords no longer appear at all. Quoted
+ phrases and explicit-operator queries are untouched, and an
+ all-stopword query still searches its literal terms. Guarded by a
+ CI-runnable search-quality suite asserting ranking usefulness, not
+ just machinery.
+ - `memory_query` no longer fails with `fts5: syntax error` when the query is
+ natural language containing parentheses, apostrophe-quoted phrases, or a
+ stray `OR`/`AND` (e.g. *"my visit to the Museum of Modern Art (MoMA) and
+ the 'Ancient Civilizations' exhibit"*). Prepared FTS5 queries are now
+ validated against the engine's own parser and degrade to an always-valid
+ quoted bag of words when the preserved operator form does not parse;
+ deliberate well-formed operator queries are preserved as before. Found by
+ the new LongMemEval retrieval harness on its first full run.
+
+ - `ai-memory serve` now takes an exclusive lock on `<data-dir>/.serve.lock`
+ before opening the store, so a second server pointed at the same data
+ directory refuses at startup and names the holding process instead of
+ silently contending the single-writer actor, the wiki git handle, and the
+ active-project pointer. The OS releases the lock when the process exits,
+ so a crashed server never leaves the operator locked out; `--force` starts
+ unguarded for an operator who knows the previous server is gone, and a
+ filesystem that cannot lock at all downgrades the guard to a warning
+ instead of refusing to start. (#563)
+
+ - Preserved third-party string-form lifecycle hooks whose commands merely
+ contain `ai-memory` or `ai_memory` when `install-hooks --apply` refreshes
+ ai-memory's own entries. Legacy ai-memory script and native hook commands
+ remain recognized by their specific hook signatures.
+ ||||||| a613bf6d
+ ### Added
+ - `status` tells more of the truth (2.0 status audit): the wiki-format
+ line (OKF migration state and the pre-migration backup archive while
+ it exists), stored embedding triples by provider/model/dim, typed-edge
+ counts by relation, and a write-queue depth gauge that surfaces a
+ backpressured (wedged) writer — shown only when non-zero.
+ - An opt-in cross-session "experience" pass
+ (`[auto_improve.scheduler] experience_every_sessions`): every N newly
+ completed sessions, the last few session summaries are reviewed side
+ by side and knowledge visible only ACROSS trajectories — repeated
+ workflows, re-stated preferences, architecture facts every session
+ re-discovers, contradictions with stored decisions — is proposed
+ through the identical schema-constrained, validated, eval-gated,
+ pending-writes staging path as per-session auto-improve. Evidence
+ must span at least two sessions; off by default and LLM-hosted, so
+ the zero-LLM path is untouched. See `docs/experience.md`.
+ - `AI_MEMORY_EMBEDDING_PROVIDER=local` — in-process sentence embeddings
+ (pure-Rust candle BERT, `all-MiniLM-L6-v2`, 384-dim) with no API key
+ and no external server. The ~87 MB model is fetched once into
+ `<data_dir>/models/` with source-pinned sha256s (offline installs drop
+ the files in manually); vectors coexist with any provider's via the
+ stored `(provider, model, dim)` triple, and switching is a config
+ change. Feature-gated (`local-embeddings`, default on). The eval
+ harness gained `--embeddings local` and publishes the hybrid
+ LongMemEval row next to the zero-LLM baseline. See
+ `docs/local-embeddings.md`.
+ - The entity index carries ingestion-time validity windows
+ (bi-temporal-lite): entity links open at their page version's creation
+ and close when the version is superseded, backfilled for existing
+ stores by an additive migration. `memory_query` gains an `as_of`
+ ISO-8601 argument that turns the call into an entity-timeline lookup —
+ "what did we know about X then" — returning the page versions valid at
+ that instant, including ones superseded since. Ingestion time only,
+ documented honestly as such. See `docs/temporal.md`.
+ - Pages can declare typed relation edges in `relations:` frontmatter —
+ a closed `causes` / `fixes` / `contradicts` vocabulary riding the
+ existing `links.link_type` column (no schema migration). Declared
+ `contradicts` edges surface as zero-LLM `contradiction` lint findings
+ (including stale declarations whose target no longer resolves), and
+ the session-end consolidation prompt may emit relations under the
+ same schema-constrained vocabulary. See `docs/typed-edges.md`.
+ - `ai-memory export-okf --project <p> -o <bundle.tar.gz>` and
+ `POST /admin/export-okf` — stream one project's wiki as a validated
+ OKF v0.2 bundle with a freshly generated index; a non-conformant page
+ fails the export. Importing needs no command: unpack a bundle's
+ concept files into a project's wiki directory and the watcher (or
+ `reindex`) ingests them.
+ - Added a LongMemEval retrieval benchmark to the evaluation harness
+ (`cargo run -p ai-memory-eval -- retrieval`). It drives a real
+ `ai-memory serve` subprocess end to end: haystack chat histories replay
+ through `POST /hook/batch` at the production hook cadence, questions run
+ through MCP `memory_query`, and results are scored session-level
+ (`hit@k` / `recall@k` per question category, abstention questions
+ reported separately). The 278 MB dataset is fetched on demand with a
+ pinned sha256; baselines are published under `docs/benchmarks/`. The
+ existing LLM A/B harness moved to the `ab` subcommand.
+ ### Changed
+ - Hybrid retrieval is on by default: an install with no
+ `embedding_provider` configured now gets in-process local embeddings
+ best-effort — the model downloads in the background on first start
+ (hybrid search enables on the next restart), existing pages are
+ backfilled by a one-shot startup pass, and hosts that cannot fetch
+ the model keep the previous FTS-only behaviour with a warning. Opt
+ out with `embedding_provider = "none"`; configured providers are
+ never overridden. Measured on LongMemEval-S: overall hit@5 rises
+ from 0.617 (FTS-only) to 0.779 with local embeddings.
+ - An unscoped `memory_write_page` / `memory_handoff_begin` from a caller whose
+ active-project pointer does not resolve is now refused instead of written to
+ the server's default project. The page such a write produced was real,
+ attributed and searchable, and in a project nobody goes looking in. The error
+ names both remedies — pass explicit `workspace`/`project`, or install the
+ lifecycle hooks so the pointer is populated. Reads are unchanged: a read
+ answering from the default is a wrong answer the caller can see, a write is a
+ misfile they cannot. Callers with no identity coordinate at all
+ (anonymous/legacy) keep resolving through the shared slot, and an install with
+ no pointer information anywhere still resolves to the configured default
+ ([#564]).
+ - The wiki's on-disk format is now natively the Open Knowledge Format
+ (OKF) v0.2: every page write fills the spec's `type`, `generated`,
+ `sources` and `stale_after` keys (ai-memory's own fields ride along as
+ spec-safe extensions), and each project directory is a conformant OKF
+ bundle with an `okf_version` index. Existing stores are migrated
+ automatically on the first 2.0 start — **backup-gated**: the entire
+ data dir is archived to the user's home (or `AI_MEMORY_BACKUP_DIR`)
+ and verified first, or the migration refuses to run; pages are
+ rewritten in place (same ids, same version rows, timestamps
+ untouched), and the wiki homepage shows where the archive is until it
+ is deleted. A data dir migrated by a newer binary is refused by older
+ 2.0+ binaries instead of silently mixing formats. See
+ `docs/okf.md` and `docs/MIGRATION-2.0.md`.
+
+ ||||||| 7907fd4d
+ ## [1.39.0] - 2026-09-01
+
### Added
+- Added a per-user launchd agent for macOS at
+ `packaging/launchd/com.github.akitaonrails.ai-memory.plist`, the counterpart
+ of the systemd user unit, shipped in both macOS release tarballs and
+ documented in [`docs/macos.md`](docs/macos.md). Until now macOS had no
+ documented way to keep the server running once the terminal that started it
+ closed, which silently stopped hook delivery. (#569)
+
+ launchd expands nothing, so the template carries explicit
+ `__AI_MEMORY_BIN__` / `__HOME__` placeholders rather than a home specifier,
+ and passes neither `--data-dir` nor `--config` — both already resolve to the
+ macOS platform defaults. `ProcessType` is pinned to `Interactive` because
+ leaving it unset makes launchd throttle the job's CPU and I/O bandwidth,
+ which the hook ingress budget cannot absorb. A bearer token, if one is
+ configured at all, goes in the rendered plist's `EnvironmentVariables`:
+ launchd has no `EnvironmentFile` equivalent.
+
- Added `ai-memory resume`, an interactive picker for recent managed
workstreams from the current checkout and validated client-local links. It
launches the selected named workstream with the established automatic harness
diff --cc docs/support-matrix.md
index 00000000,5b62997c..30ce3174
mode 000000,100644..100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@@ -1,0 -1,38 +1,38 @@@
+ # 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. |
-| macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](docs/macos.md). |
++| macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries, which include a per-user launchd agent. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](docs/macos.md). |
+ | Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. |
+ | Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](docs/windows.md). |
+ | Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). |
+ | Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. No automatic true session-end hook, so run `ai-memory finalize-session` when you need a final summary/handoff. |
+ | 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. `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. |
+ | 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, 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`](docs/managed-workstreams.md). |
+ | Claude Desktop | MCP-only | Uses `mcp-remote`; no lifecycle hooks. |
+ | 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. `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. |
+ | 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; no hook handoff injection — Grok ignores `SessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. `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_accept`. |
+ | 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. `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_accept`. 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`](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. |
+ | Hermes Agent | Community | Core hook ingestion recognizes `agent=hermes` and Hermes' documented shell-hook `tool_name` / `tool_input` payload for concrete session attribution, tool-family titles, and capture exclusions. A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available, but no first-party installer is shipped; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. Hermes ignores session-start hook stdout, so recover handoffs through MCP. |
+ | LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode Zen/Go, 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. |