Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(hermes): document the first-party lifecycle and MCP client
4nrrydceb62e904aa
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dadedae1..322d8f3d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,16 @@ version in [`docs/changelog/`](docs/changelog/):### Added+- Added a first-party Hermes Agent lifecycle and an `install-mcp --client+ hermes` client. The `hooks:` block `install-hooks --agent hermes` prints now+ also wires `on_session_start`, `pre_llm_call` (the prompt, never the+ conversation history), `on_session_end` as a turn boundary and+ `on_session_finalize` as the session end, and the first turn's+ `pre_llm_call` brings the pending handoff in as `{"context": ...}`. Hermes+ events route by `TERMINAL_CWD` when it names an existing directory. When the+ community memory-provider plugin is installed, only the tool events are+ printed. `install-mcp --client hermes` prints an `mcp_servers:` entry for the+ session-less stdio bridge with no token in it, and refuses `--apply`.- Added bounded local document extraction to the optional`ai-memory-importer` companion. Its dry-run-first `document` command acceptsUTF-8 text/Markdown, text-layer PDF, DOCX, PPTX, XLSX, VTT, anddiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex d1f8927b..f38e6a14 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -407,6 +407,20 @@ apply. Relative, mixed-project, unsupported, and non-project targets keep theharness cwd. Session identity and compiled-session ownership do not move; onlythe raw observations are attributed to the touched project (#932; #1199:Hermes reports its process cwd and locates each tool by `workdir`/`path`).+For Hermes the native hook first replaces that process cwd with+`TERMINAL_CWD`, the variable Hermes exports `terminal.cwd` through, when it+names an existing absolute directory; a gateway's process cwd is wherever the+gateway started. Every Hermes event routes from there, and tool events can+still move by their own locations.++Hermes' lifecycle maps by meaning: `on_session_start` is `session-start` and+only records the start (Hermes ignores its stdout), `pre_llm_call` is+`user-prompt` with the text of `extra.user_message` and never the conversation+history, `on_session_end` is `stop` because Hermes fires it after every turn,+and `on_session_finalize` is `session-end` for the ending session only. The+handoff is claimed on a session's first `pre_llm_call`+(`extra.is_first_turn`) and printed as `{"context": ...}`, the one stdout shape+Hermes adds to a turn.Antigravity's `SessionStart` maps to `session-start`. Its `PreInvocation` hookfires before every model call, so the bridge acts only on the documenteddiff --git a/docs/install.md b/docs/install.mdindex de73a1e3..7e6a46fb 100644--- a/docs/install.md+++ b/docs/install.md@@ -2008,45 +2008,61 @@ CodeBuddy session after installing so it loads the hooks.### Hermes Agent (Nous Research)Hermes declares lifecycle hooks in the `hooks:` block of-`~/.hermes/config.yaml`. `install-hooks --agent hermes` (alias `hermes-agent`)-prints the block to paste there:+`~/.hermes/config.yaml` (`$HERMES_HOME/config.yaml`). `install-hooks --agent+hermes` (alias `hermes-agent`) prints the block to paste there:```bash-ai-memory install-hooks --agent hermes \- --server-url "http://homelab:49374" \- --auth-token "$TOKEN"+ai-memory install-hooks --agent hermes --server-url "http://homelab:49374"```Hermes splits each configured `command` with `shlex.split` and runs it with**no shell**, passing the event JSON on stdin, so the generated entry invokesthe native `ai-memory hook` command directly (the same exec-form shape Zero and-ZCode use) and there is no script bundle to stage. There is also no `--apply`-that writes the file: `~/.hermes/config.yaml` is YAML you also edit, and Hermes-gates user hooks behind its own acceptance prompt (`hooks_auto_accept`). Paste-the block and let Hermes accept it.--Two events are wired: `pre_tool_call` → `pre-tool-use` and `post_tool_call` →-`post-tool-use`. Their payload carries `tool_name` / `tool_input`, which is what-gives Hermes sessions tool observations, tool-family titles, and-`[capture] ignore_paths` exclusion enforcement. Hermes reports its own process-directory (usually `~`) as the payload `cwd`, so the hook finds the project's-`.ai-memory.toml` from each tool's absolute location instead: `terminal`'s-`workdir`, a file tool's `path`, or `search_files`' `path`. A tool call with no-absolute location (a relative `workdir`, the default `search_files` path)-stays with the process directory and, under `capture_mode = allowlist`, is-captured only if that directory carries a marker. See-[marker-file.md](marker-file.md) for the routing rules.--Session lifecycle is deliberately not wired here: automatic recall, prompt-capture, session-end and the automatic handoff for Hermes belong to the memory-provider, the community-maintained-[`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin).-A second, hook-driven `session-end` would close the same session twice. Hermes-ignores session-start hook stdout, so a pending handoff is recovered through-MCP: `memory_handoff_list` then `memory_handoff_accept`.+ZCode use) and there is no script bundle to stage. ai-memory never writes the+file, `--apply` included: `~/.hermes/config.yaml` is YAML you also edit, and+Hermes gates user hooks behind its own acceptance prompt (`hooks_auto_accept`).+Paste the block, let Hermes accept it, and restart Hermes and its gateway.-No first-party `install-mcp` client and no managed workstream-(`ai-memory run hermes`) are claimed yet.+Six events are wired, each with a 20-second timeout:++| Hermes event | ai-memory event | What it does |+| --- | --- | --- |+| `pre_tool_call`, `post_tool_call` | `pre-tool-use`, `post-tool-use` | Tool observations, tool-family titles and `[capture] ignore_paths` enforcement. |+| `on_session_start` | `session-start` | Records the start. Hermes ignores this hook's output, so no handoff is fetched here. |+| `pre_llm_call` | `user-prompt-submit` | Captures the prompt from `extra.user_message` (text parts only, never the conversation history). On the session's first turn it claims the pending handoff and prints `{"context": "..."}`, which Hermes adds to that turn. |+| `on_session_end` | `stop` | A turn boundary: Hermes fires it after every turn, not at session end. |+| `on_session_finalize` | `session-end` | Ends the session on CLI exit, `/new` or gateway shutdown. After a gateway `/new` only the ending session is closed. |++A gateway session that expires idle is never finalized by Hermes. Close it+from the session's project directory, or name it with `--session-id`:++```bash+ai-memory finalize-session --agent hermes+ai-memory finalize-session --agent hermes --session-id <id>+```++Hermes reports its own process directory as the payload `cwd`; for a gateway+that is wherever the gateway started. The hook routes by `TERMINAL_CWD`+instead, the variable Hermes exports `terminal.cwd` through, when it names an+existing absolute directory. A tool call can still move to another checkout+when its absolute location proves one: `terminal`'s `workdir`, a file tool's+`path`, or `search_files`' `path`. With neither, an event stays with the+process directory and, under `capture_mode = allowlist`, is captured only if+that directory carries a marker. See [marker-file.md](marker-file.md) for the+routing rules.++The community [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin)+memory provider also posts prompts and session ends and claims the handoff.+When it is installed in `$HERMES_HOME/plugins/ai-memory`, `install-hooks` and+`setup-agent` print only the two tool events, so prompts are not captured twice+and the handoff is not claimed twice. If you install the plugin later, delete+the four lifecycle entries.++For MCP, `ai-memory install-mcp --client hermes` prints an `mcp_servers:` entry+for the same file (see [mcp-install.md](mcp-install.md#hermes-agent)). Hermes+does not read MCP server instructions, so also install the skills:+`ai-memory install-skills --scope global --agent hermes` writes them to+`~/.hermes/skills`. No managed workstream (`ai-memory run hermes`) is claimed.### OpenCodediff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex cbaf4d35..010f964a 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -26,7 +26,8 @@ Warp, Kilo Code, Goose, Qwen Code and OpenHuman have no> `workspace` and `project` like any static client. Stdio entries name the> `ai-memory` binary by its absolute path, so the client does not need it on> its `PATH`; the Docker wrapper keeps the bare `ai-memory`. ZCode keeps-> HTTP entries only and is refused. Passing `--auth-token` explicitly (or+> HTTP entries only and is refused. Hermes Agent gets the bridge entry+> whatever the token source, so its config never holds a token. Passing `--auth-token` explicitly (or> `AI_MEMORY_AUTH_TOKEN`) keeps the HTTP snippets below, header included.> **Transport is stateless by default.** Since v0.1.2 the HTTP transport@@ -110,39 +111,57 @@ ai-memory's canonical events when possible:### Hermes Agent-ai-memory ships a first-party hook installer for Hermes Agent:+ai-memory ships a first-party Hermes integration: lifecycle hooks and an MCP+entry, both printed for you to merge into `~/.hermes/config.yaml`+(`$HERMES_HOME/config.yaml`), which ai-memory never writes.```bashai-memory install-hooks --agent hermes --server-url "http://homelab:49374"-```--Because Hermes splits each configured `command` with `shlex.split` and runs it-with **no shell**, the printed block invokes the native `ai-memory hook`-command (exec form, the same shape Zero and ZCode use); no `.sh`/`.ps1` bundle-is staged, and there is no `--apply` that writes your config. `~/.hermes/config.yaml`-is a YAML file you also edit, and Hermes gates user hooks behind its own-acceptance prompt (`hooks_auto_accept`), so paste the block and let Hermes-accept it. Two tool events are wired (`pre_tool_call`, `post_tool_call`), which-is what gives Hermes sessions tool observations.--The memory provider remains a community-maintained project: a+ai-memory install-mcp --client hermes+ai-memory install-skills --scope global --agent hermes+```++The hooks block runs the native `ai-memory hook` command in exec form, since+Hermes splits each `command` with `shlex.split` and runs it with no shell. It+wires the tool events and the session lifecycle: `on_session_start`,+`pre_llm_call` (the prompt, plus the pending handoff as `{"context": ...}` on a+session's first turn), `on_session_end` (a turn boundary, because Hermes fires+it after every turn) and `on_session_finalize` (the session end). Hermes gates+user hooks behind its own acceptance prompt (`hooks_auto_accept`), so paste the+block and let Hermes accept it. [install.md](install.md#hermes-agent-nous-research)+has the event table, the `TERMINAL_CWD` routing and the+`finalize-session --agent hermes` step for idle gateway sessions.++`install-mcp --client hermes` (alias `hermes-agent`) prints an entry for the+`mcp_servers:` map that runs `ai-memory mcp-bridge --no-session-id` over stdio+with the install's `--data-dir`. The file gets no token: the bridge sends the+install's own, which matters because Hermes passes MCP servers a filtered+environment without `AI_MEMORY_AUTH_TOKEN`. Hermes is a static client, so the+model passes `workspace` and `project` on project-scoped calls. `--apply` is+refused. Hermes does not read MCP server instructions, so the routing rules+reach the model only through the skills in `~/.hermes/skills` and the handoff+in the first turn.++The community-maintained[`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin)-is available, and it is what owns automatic recall, prompt capture, session-end-and the automatic handoff for Hermes. Treat it as a third-party bridge: verify-its documented Hermes and ai-memory version matrix, install/update/uninstall-behavior, platform coverage, and secret handling before enabling it on a live-ai-memory server. In particular, bearer tokens and endpoint settings should-stay in environment or local config references rather than generated plugin-source files.+memory provider is an alternative for prompts, session ends, recall and the+handoff. Treat it as a third-party bridge: verify its documented Hermes and+ai-memory version matrix, install/update/uninstall behavior, platform coverage,+and secret handling before enabling it on a live ai-memory server. Bearer tokens+and endpoint settings should stay in environment or local config references+rather than generated plugin source files. Run only one lifecycle path: when the+plugin is installed in `$HERMES_HOME/plugins/ai-memory`, `install-hooks --agent+hermes` prints only `pre_tool_call` and `post_tool_call`, so prompts are not+captured twice and the handoff is not claimed twice.The hook router recognizes `agent=hermes` as a concrete session kind and-accepts Hermes' documented shell-hook `tool_name` / `tool_input` envelope for-tool-family metadata and capture-exclusion enforcement. A custom bridge should-map `on_session_start`, `post_tool_call`, and `on_session_end` to ai-memory's-canonical `session-start`, `post-tool-use`, and `session-end` event names while-forwarding the original JSON object. This protocol recognition does not install-or trust a third-party plugin. Hermes ignores session-start hook stdout, so it-cannot consume an automatic handoff there; use MCP `memory_handoff_accept`.+accepts Hermes' shell-hook `tool_name` / `tool_input` envelope for tool-family+metadata and capture-exclusion enforcement. A custom bridge should map+`pre_llm_call`, `post_tool_call`, `on_session_end` and `on_session_finalize` to+ai-memory's canonical `user-prompt`, `post-tool-use`, `stop` and `session-end`+events, sending the prompt text as `prompt` rather than Hermes' whole `extra`+object, which carries the conversation history. This protocol recognition does+not install or trust a third-party plugin.The same lifecycle guidance below applies to Hermes or any other externalbridge: map known events onto ai-memory's canonical hook events wherediff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 10a3d6f0..c73b0d15 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -93,7 +93,7 @@ means the boundary is not built yet.| 11d | Hook server-profile routing: a marker-selected server gets only its own capture and its own token (#992) | `ai-memory-cli/src/server_profiles.rs` `resolve` (validated `ProfileName`, strict `servers.toml` parse, `roots` required once two profiles exist, component-wise root match) and `marker.rs` `find_server_selection` (inherited down the tree, any value shape counts); `commands/hook.rs` `resolve_hook_route` drops a `Rejected` route before spool, handoff and backfill, and hands the drainer no live token for a profile route; `commands/hook_spool.rs` `static_retry_token` (a profile entry retries only with its own stored token), the loopback reroot skip, and chunk splitting on `profile`; generated TS `captureServerRouted` drops a routed repository and gates `fetchHandoff`; `hooks/_lib.sh` `ai_memory_server_routed` (flag refused by `ai_memory_post_hook`/`ai_memory_get_handoff`) and `hooks/lib/ai-memory-hook.ps1` `Test-AiMemoryServerRouted` drop it in the script hooks; `--check-capture` refuses a rejected server-profile selection without printing its token or URL; once `[auth].bearer_token_file` names `auth-tokens/default` (this install's root bearer), `commands/server.rs` `refuse_the_root_token_name` refuses `server add default` and `server remove default` so no profile can be handed, overwrite or delete the root bearer | `hook.rs` `each_repository_spools_to_its_own_profile_with_its_own_token`, `muse_hooks_honour_marker_scope_profiles_exclusions_and_allowlist` (the Meta Muse Code settings-hook front door: marker workspace/project, the profile's server and token never the install's, the payload's session id, an ignored relative `read_file` dropped with a kept control, allowlist silence from an unmarked checkout with a denylist control), `a_selection_that_does_not_resolve_emits_nothing` (unknown / tokenless / outside roots / roots required / invalid name, plus a resolving control), `session_start_handoff_comes_from_the_profile_server_only`, `a_repository_without_a_server_key_keeps_the_install_default`; `hook_spool.rs` `a_profile_entry_is_never_retried_with_the_install_live_token` (server B accepts exactly the install's live token and must still not get it), `a_profile_entry_recovers_with_its_own_rotated_token` (control), `a_profile_entry_on_a_dead_loopback_port_is_not_rerouted_to_the_default`, `profile_and_default_entries_at_one_address_ride_separate_batches`; `server_profiles.rs` roots/registry/name tests; `marker.rs` `nested_markers_without_server_inherit_the_ancestor_selection`; `install_hooks.rs` `generated_integrations_fail_closed_on_a_server_profile_marker`, `openclaw_plugin.rs` `openclaw_plugin_fails_closed_on_a_server_profile_marker`, and the `server-routed-*` checks in `generated_capture_policy_v1_node_runtime_evidence`; `hook.rs` `an_event_without_a_payload_cwd_routes_by_the_process_cwd`, `a_refused_route_prints_nothing_for_kimi_user_prompts`; `hook_spool.rs` `a_profile_entry_is_not_retried_with_a_token_issued_for_a_new_url`; `server_profiles.rs` `changing_the_url_without_a_token_discards_the_old_token`, `omitted_roots_keep_the_registered_ones`; `marker.rs` `outside_home_the_walk_reaches_a_marker_above_the_checkout_root`, `encoding_noise_cannot_hide_a_server_key`, `an_unreadable_marker_is_a_refused_selection`; `backfill.rs` `a_spawned_backfill_authenticates_like_the_hook_that_spawned_it`; `tests/hooks/test_lib.sh` "server profiles (#992)" section; `hook.rs` `a_mixed_spool_drains_each_event_only_to_its_own_server` (two token-gated servers, one spool, one drain: each server receives exactly its own event with exactly its own bearer); `tests/suite/server_profiles.rs` (the built binary: `server add` → `hook` spools to the profile with its token, unknown profile spools nothing, `uninstall` removes the tokens; `two_real_servers_each_receive_only_their_own_repository` runs two real `ai-memory serve` children with different root tokens and checks on each server which repository landed there); `ai-memory-hooks` `powershell_server_routed.rs` `server_routed_guard_mirrors_the_native_walk` (runs `Test-AiMemoryServerRouted` under real PowerShell: inherited, BOM, look-alike keys, the `$HOME` boundary with its control, past a checkout root outside home, current directory); `hook.rs` `a_selection_that_does_not_resolve_emits_nothing` (rejected routes refuse preflight; resolved profile control passes); `tests/hooks/test_lib.sh` and `powershell_home.rs` `a_trailing_separator_on_home_keeps_the_walk_boundary` (a `$HOME` ending in `/` or `\` keeps both script walks at home: a `server` marker above it routes nothing, with a root-home control that does); `server.rs` `the_root_bearer_file_name_cannot_be_registered_or_removed` (refused at the root bearer path; another name and an install without a root bearer file are the controls); `server_profiles.rs` `a_default_profile_shares_the_root_bearer_only_at_its_path`, `clear_tokens_keeps_the_root_bearer_and_removes_profile_tokens` | STRONG for native hooks, generated TS, `.sh` and `.ps1` hooks. Known gap: an older binary draining a shared spool ignores `profile` || 11e | Native self-upgrade archive confinement (#1025) | `ai-memory-cli/src/commands/upgrade.rs` normalizes every tar/zip path, rejects links and special entries, extracts only the binary and `hooks/`, accepts only the exact non-runtime support layout emitted by `release.yml`, and caps both entry count and declared expanded bytes before writing | `upgrade.rs` `release_workflow_support_assets_are_exact_and_ignored` (shipped support paths admitted, near-miss docs/packaging/template paths refused), `extracts_archive_built_like_release_yml` and `extracts_zip_happy_path_with_hooks` (real workflow-shaped archives succeed but support assets are not written), `validate_rejects_path_traversal`, `zip_extract_rejects_path_traversal`, `tar_extract_rejects_declared_expansion_past_limit`, with binary/hooks extraction as the legitimate control | STRONG || 11f | Native hook executable-path integrity after self-replacement (#1027) | `ai-memory-cli/src/commands/render_shared.rs` `hook_embedded_exe_path` is the single executable resolver for every persisted native hook form (POSIX/Windows command, Windows exec, Zero, ZCode, OpenCode 2 assistant capture): it prefers an existing literal path, strips Linux's trailing ` (deleted)` procfs marker only when the stripped installed binary exists, and otherwise falls back to the platform command name. A binary running from `/nix/store` always renders the bare command (#1275): the store path names one package version that garbage collection deletes, while the profile's `bin/` on `PATH` follows upgrades. Upgrade keeps the already-loaded config and refreshes in-process | `render_shared.rs` `embedded_exe_strips_the_marker_when_the_stripped_path_exists`, `embedded_exe_preserves_a_real_file_whose_name_has_the_marker_suffix`, `embedded_exe_falls_back_when_the_resolved_path_is_missing`, `hook_embedded_exe_path_names_an_existing_file_without_marker` (asserts the bare command only when the test binary itself runs from the Nix store), `hook_rendered_from_a_nix_store_exe_names_the_bare_command` (the existence probe reports the store binary present, so only the store-path guard yields the bare command in the rendered exec hook) with its control `hook_rendered_from_a_normal_exe_keeps_the_absolute_path` (`/usr/bin`, `~/.nix-profile/bin`, and a non-root `.../nix/store/...` keep the absolute path); `upgrade_e2e.rs` `native_upgrade_refreshes_hooks_without_a_deleted_path_or_losing_cli_data_dir` reproduces the replacement window through the shipped binary, plants the corrupt suffix, and proves refresh removes it while preserving a CLI-only data dir | STRONG on Linux reproduction plus platform-neutral resolver/render coverage; Windows path rendering remains covered by its existing command/exec tests and full Windows CI |-| 11g | Cross-project tool attribution cannot bypass source or destination capture, or destination server routing (#932, #1199) | `ai-memory-hooks/src/capture_policy.rs` `absolute_tool_location_paths` accepts only bounded, recognized, absolute locations: file-tool targets, a search/list tool's explicit `path`, or a shell command's structured `workdir` (command text is never parsed for a location); `ai-memory-cli/src/commands/hook.rs` `tool_location_routing_cwd` requires every path to prove the same repository/marker boundary, refuses the reroute when the payload cwd's own capture policy would not keep the event (source `ignore_paths` may name paths outside the source checkout, and a command may name source files while its `workdir` points elsewhere), and resolves that destination before capture policy, allowlist marker, server profile, scope hints, or spool credentials. Relative, mixed-project, unsupported, and arbitrary non-project paths keep the payload cwd | `hook.rs` `absolute_file_target_uses_destination_scope_and_capture_policy` (hostile content under the destination exclusion is never spooled; a public control is routed there), `absolute_file_target_cannot_escape_a_destination_server_profile` (unregistered destination profile drops instead of falling back to source/install default), `file_target_routing_refuses_relative_external_and_mixed_project_paths`, `workdir_reroute_applies_the_destination_capture_policy` (a `workdir`-rerouted command reading a destination-excluded path is dropped, public control kept), **`a_reroute_cannot_escape_the_source_capture_exclusions`** (adversarial: a file read under a source pattern that names another project's directory, and a shell command naming an excluded source file with `workdir` in another project, are both refused; public file and shell controls still reroute; fails with the source-policy check removed), `hermes_tool_location_finds_the_marker_the_process_cwd_lacks` (Hermes `terminal` `workdir`, `read_file` `path` and `search_files` `path` reach the repository marker under allowlist; no-workdir, relative-workdir and relative-search controls stay with the unmarked process cwd); `capture_policy.rs` `absolute_tool_location_paths_cover_search_dirs_and_shell_workdirs` (relative workdir, command-text paths, workdir without a command, and Hermes `process` yield no location) | STRONG for native `ai-memory hook`; generated and compatibility hooks retain cwd-only routing |+| 11g | Cross-project tool attribution cannot bypass source or destination capture, or destination server routing (#932, #1199) | `ai-memory-hooks/src/capture_policy.rs` `absolute_tool_location_paths` accepts only bounded, recognized, absolute locations: file-tool targets, a search/list tool's explicit `path`, or a shell command's structured `workdir` (command text is never parsed for a location); `ai-memory-cli/src/commands/hook.rs` `tool_location_routing_cwd` requires every path to prove the same repository/marker boundary, refuses the reroute when the payload cwd's own capture policy would not keep the event (source `ignore_paths` may name paths outside the source checkout, and a command may name source files while its `workdir` points elsewhere), and resolves that destination before capture policy, allowlist marker, server profile, scope hints, or spool credentials. Relative, mixed-project, unsupported, and arbitrary non-project paths keep the payload cwd. For Hermes, `hook.rs` `hermes_terminal_cwd` replaces the reported process cwd with `TERMINAL_CWD` (read from the captured `RuntimeEnv`) only when it names an existing absolute directory, before the location lookup above, so that checkout's capture policy, allowlist marker and server profile govern the event | `hook.rs` `absolute_file_target_uses_destination_scope_and_capture_policy` (hostile content under the destination exclusion is never spooled; a public control is routed there), `absolute_file_target_cannot_escape_a_destination_server_profile` (unregistered destination profile drops instead of falling back to source/install default), `file_target_routing_refuses_relative_external_and_mixed_project_paths`, `workdir_reroute_applies_the_destination_capture_policy` (a `workdir`-rerouted command reading a destination-excluded path is dropped, public control kept), **`a_reroute_cannot_escape_the_source_capture_exclusions`** (adversarial: a file read under a source pattern that names another project's directory, and a shell command naming an excluded source file with `workdir` in another project, are both refused; public file and shell controls still reroute; fails with the source-policy check removed), `hermes_tool_location_finds_the_marker_the_process_cwd_lacks` (Hermes `terminal` `workdir`, `read_file` `path` and `search_files` `path` reach the repository marker under allowlist; no-workdir, relative-workdir and relative-search controls stay with the unmarked process cwd), **`hermes_terminal_cwd_applies_the_selected_checkout_policy`** (adversarial: with `TERMINAL_CWD` selecting a checkout, a relative read of a path it excludes is never spooled and a marker naming an unregistered server profile drops the event; public control kept; fails with the `TERMINAL_CWD` routing removed), `hermes_terminal_cwd_routes_lifecycle_events` (allowlist: a prompt is captured only through an existing absolute `TERMINAL_CWD`; unset, relative and missing values stay with the unmarked process cwd), `hermes_tool_events_prefer_their_locations_then_terminal_cwd`; `capture_policy.rs` `absolute_tool_location_paths_cover_search_dirs_and_shell_workdirs` (relative workdir, command-text paths, workdir without a command, and Hermes `process` yield no location) | STRONG for native `ai-memory hook`; generated and compatibility hooks retain cwd-only routing || 11h | Docker-wrapper capture-policy capability (#1002) | `bin/ai-memory` routes ordinary Linux/macOS `install-hooks`, upgrade refreshes, and every `hook`/`hook-drain` invocation through the stable checksum-verified native host client, so the hook process executes the capture-policy boundary in 11b before spool/network; a hook config that calls the wrapper never runs in the helper container, and an unavailable client drops the event with exit 0 instead of falling back to it. Only an explicit `AI_MEMORY_HOOK_PLATFORM=posix|windows` retains the documented script compatibility path and its warning; `AI_MEMORY_NATIVE_BIN` may not point back to the wrapper. For a server initialized on the named volume, `bin/ai-memory` `refresh_volume_token` (run only by `install-hooks`) copies `/data/auth-tokens/default` (only when `/data/config.toml` names it) to an owner-only `native-runner/server-token` through the helper's stdout, and `use_volume_token` points the native client at that copy (the managed host commands and `mcp-bridge` only read it and never enter the container engine) with `AI_MEMORY_AUTH__BEARER_TOKEN_FILE`, so it is a file-sourced token (never rendered into a harness config) and never an argv; a refresh that reads no token from a reachable volume deletes the copy, and a successful full `uninstall --apply` deletes it after the container returns; a bind-mounted `AI_MEMORY_DATA_DIR` is read directly and an explicit `AI_MEMORY_AUTH_TOKEN` wins | `scripts/check-native-packaging.sh` `Checking host-launch wrapper routing`: a default allowlist install reaches the fake native client while a Docker executable that always fails proves no container fallback occurred; the explicit `posix` control reaches fake Docker and adds no native invocation; the self-referential native override is refused. `tests/wrapper_upgrade.sh` `lifecycle hook native host routing`: `hook --event session-start` and `hook-drain` reach the fake native client with the stdin payload while `docker`/`podman` stubs on PATH and in `AI_MEMORY_DOCKER` stay unused, and a non-executable `AI_MEMORY_NATIVE_BIN` exits 0 without reaching the engine; `Checking the wrapper hands host commands the volume's root bearer`: for `mcp-bridge`, `install-hooks` and `run` the fake native client receives the token file (mode 600, right content) and the token is absent from its argv; controls: a bind-mounted data dir and an explicit `AI_MEMORY_AUTH_TOKEN` make no copy and ask no container (bite: dropping the export fails the check); `Checking the host token copy goes with the volume's token and with uninstall`: a volume answering with no token removes the copy and hands none over, while an unreachable engine keeps it; a dry-run, `--only hooks` or failing `uninstall` keeps it and a successful `uninstall --apply` removes it (bite: without either removal the check fails); `auth_default_e2e.rs` `a_host_client_given_the_token_file_by_env_authenticates` (the native side of the handoff, with a no-variable control) | STRONG on the shipped Linux/macOS wrapper. Windows and remote/manual script installers remain explicitly outside capture-policy v1 || 11j | Offline recovery journal and transcript replay | `ai-memory-cli/src/commands/recovery.rs` keeps bounded locators, ordered semantic transcript digests, pre-launch cursors and persistent correlated-delivery/loss evidence in an atomic journal, refuses a symlinked data dir and any symlinked component inside it (ancestors above the data dir are trusted, so macOS `/var` → `/private/var` works), sanitizes/caps failure reasons, and bounds each replay plus the whole pass; `hook_spool` coordinates enqueue and quarantine with short filesystem locks, canonically resolves partial scope from the recorded cwd, bounds per-file reads and current global occupancy across the main spool and recovery directories, sweeps completed tombstones, and holds correlated events outside drain until replay succeeds or restores them on failure; degraded resumes use `ai-memory-workstream`'s adapter-validated delta export, whose blocking parse and baseline scans are capped by record, event-count, source-byte and serialized-byte totals; `backfill::import_exact_session` chunks by item and byte limits and requires per-item durable acknowledgements; `run.rs` journals every session launch, including explicit spool-only evidence for unsupported exporters, and journals a resumed export only after capturing its exact pre-launch cursor; `workstream.rs` `/recover/finish` retains owner/project authorization, rejects superseded runs, and validates a finished retry by durable transcript/native/cursor/exit identity without regenerating its checkpoint; validated recovery ingest keys bind session, agent, event kind and sanitized event identity until session purge | `transcript.rs` `persisted_baseline_exports_only_offline_append_and_rejects_rewrite`, parser/baseline cap and ordered-semantic digest tests; CLI `run_offline.rs` real degraded spool-only and overlap/idempotency tests; `recovery.rs` `spool_only_without_correlated_evidence_never_auto_clears`, `a_dropped_spool_event_stays_lost_on_the_next_empty_pass`, loss/time-budget tests, `symlinked_journal_and_ancestor_are_refused`, `a_symlinked_ancestor_of_the_data_dir_is_trusted`, `a_symlink_inside_a_data_dir_under_a_symlinked_ancestor_is_refused`; `hook_spool.rs` partial-scope late enqueue, completion-race, occupancy churn/active-cap, bounded-read and tombstone-sweep tests, plus interval isolation (`completed_tombstone_keeps_a_later_resume_of_the_same_session` proves a post-interval resume hook is delivered, `completing_one_recovery_interval_leaves_the_other_intervals_entries_intact` proves one interval's completion never consumes another's evidence and ambiguous entries fail closed into the main spool); `backfill.rs` `two_sequential_recovery_intervals_on_one_resumed_session_replay_exactly_once` proves the second interval's content and session-end are stored with end-of-session effects while reruns stay pure replays; `transcript.rs` `an_oversized_first_record_is_skipped_by_session_listing_caps` proves the first-record byte caps bite before allocation; store `insert_observation_ingest_dedups_on_key` rejects cross-session and changed-event preclaims; hooks `expired_run_recovery_is_owner_only_and_refuses_superseded_runs` proves changed transcript refusal and changed-checkpoint no-op | STRONG on Unix integration coverage; Unix lock opens use no-follow and atomic replacement rechecks the destination. Windows owner-only ACL/reparse and lock semantics require the PR `windows` lane || 11i | OpenCode executable probing and generated-config cleanup (#1097) | `ai-memory-cli/src/config.rs` captures the full process environment once in typed `RuntimeEnv`; `run.rs` overlays explicit `run --env` values with platform key semantics and uses that same effective environment for executable resolution, probing, and launch without rereading process environment; `opencode_dialect.rs` invokes only direct argv `--version`, caps output and time, and rejects malformed/future majors. Automatic launch skips only OpenCode on probe failure; explicit OpenCode fails. `install_hooks.rs` quarantines the incompatible sibling before reading its exact ownership markers, restores unowned content with an atomic no-replace link, and never deletes or overwrites a concurrent replacement; `install_mcp.rs` owns the shared dual-schema endpoint/token inference used by both installers, rejects conflicting generated V1/V2 entries before mutation, and migrates an alternate-major entry only when endpoint, generated shape, and absent-or-Authorization-only headers match, preserving custom headers and ambiguous entries; auto-wire migrates MCP before hooks infer from that exact config path and skips hook mutation when transition preflight fails | `run.rs` `automatic_opencode_probe_failure_keeps_another_harness_available`, `opencode_executable_probe_selects_v2_for_launch_and_autowire`, effective-child-environment PATH casing controls, fake V1/V2/env-derived-major/malformed/future/timeout executable tests, `setup-agent` V1/V2 no-probe integration controls; `install_hooks.rs` `opencode_plugin_cleanup_removes_only_exact_owned_incompatible_sibling`, `opencode_plugin_cleanup_preserves_a_concurrent_user_replacement`, `opencode_plugin_restore_moves_quarantine_when_destination_is_free`, `opencode_plugin_restore_preserves_an_existing_replacement`, `opencode_plugin_restore_does_not_replace_a_file_created_at_restore_window`, `opencode_plugin_cleanup_does_not_escape_custom_target_directory`; `install_mcp.rs` `opencode_install_reuses_owned_endpoint_and_token_across_major_transitions`, `opencode_install_refuses_conflicting_owned_transition_entries`, `opencode_install_does_not_infer_from_a_user_owned_transition_entry`, `opencode_mcp_migration_moves_only_owned_alternate_shape`, `opencode_mcp_migration_preserves_ambiguous_user_entry`, `opencode_mcp_migration_preserves_custom_headers`, `opencode_mcp_migration_accepts_only_historical_generated_headers` | STRONG for Unix process probes and platform-neutral ownership gates; exact Windows executable resolution remains covered by `run.rs` resolver tests and requires the PR `windows` label |diff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex d0141567..131ab2df 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -49,7 +49,7 @@| Cline CLI | Hooks + MCP | `install-mcp --client cline --apply` merges Cline's required top-level `type`, `url`, and optional `headers` fields into `${CLINE_MCP_SETTINGS_PATH:-~/.cline/data/settings/cline_mcp_settings.json}` and explicitly selects Streamable HTTP (a bare URL selects legacy SSE). `install-hooks --agent cline --apply` writes the nine supported CLI event files to `~/.cline/hooks` (or project `.cline/hooks` with `--scope project`): task start/resume, prompt, pre/post tool, complete/cancel/error, and shutdown. The generated owner-only files refuse user-owned files and final-component symlinks. Cline starts task hooks detached, so pending handoffs are accepted through MCP; yolo mode disables hooks, and Cline must be restarted after installation. This installs Cline CLI hooks only; the VS Code extension uses a separate `~/Documents/Cline/Hooks` convention. No managed workstream. || FreeBuff | MCP-only | `install-mcp --client freebuff --apply` merges an `ai-memory mcp-bridge --no-session-id` stdio entry into `~/.agents/mcp.json`. FreeBuff discovers that file from the current directory, its parents, or the home directory and already reads `AGENTS.md`; it has no documented lifecycle-hook or managed-workstream surface. The bridge reaches the configured local or remote server without attempting to start a second server that would contend for the data-dir lock. || Prime Agent | MCP-only | `install-mcp --client prime-agent` merges an HTTP entry (`type: "http"` + `url`) into the `mcpServers` map of `$PRIME_AGENT_CODING_AGENT_DIR/settings.json` (default `~/.prime/agent/settings.json`), preserving other settings and servers; a project's `.prime/agent/settings.json` works through `--config-file`. A token is referenced as `"bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"`, never written: Prime Agent 0.10 counts a user HTTP server as connected and names it in the model's prompt only with that variable set or an OAuth grant. A credential-less entry is still callable through `mcp.call_tool("ai-memory", ...)` but is not listed. The model reaches MCP tools from its Python REPL (`await mcp.call_tool("ai-memory", "memory_query", {...})`), and Prime Agent sends no session id or cwd, so pass `workspace` and `project` on project-scoped calls. Lifecycle capture and managed workstreams are not claimed: Prime Agent 0.10 removed the TypeScript extensions its 0.9 releases had and has no hook surface. Verified against Prime Agent 0.10.0. |-| 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. Hermes reports its own process directory as `cwd`, so the native hook locates each event's `.ai-memory.toml` from the tool's absolute `workdir` (`terminal`) or `path` (file tools, `search_files`); a call with no absolute location stays with the process directory. Session lifecycle (recall, prompt capture, session-end, automatic handoff) is owned by the community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/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`). |+| Hermes Agent | Supported | `install-hooks --agent hermes` (alias `hermes-agent`) prints a ready-to-paste `hooks:` block for `~/.hermes/config.yaml`; ai-memory never writes that YAML file, which Hermes also gates behind its hook-acceptance prompt (`hooks_auto_accept`). Each entry runs the native `ai-memory hook` command in exec form (Hermes splits `command` with `shlex.split` and uses no shell) with a 20-second timeout. Six events: `pre_tool_call` and `post_tool_call` for tool capture and exclusions; `on_session_start` to record the start; `pre_llm_call` for the prompt (text from `extra.user_message`, never the conversation history); `on_session_end` as a turn boundary, since Hermes fires it after every turn; and `on_session_finalize` to end the session on CLI exit, `/new` or gateway shutdown (after a gateway `/new` only the ending session is closed). Hermes ignores `on_session_start` output, so the pending handoff is claimed on the session's first `pre_llm_call` and printed as `{"context": ...}`, which Hermes adds to that turn. Hermes reports its own process directory as `cwd`; the hook routes by `TERMINAL_CWD` (Hermes' `terminal.cwd`) when it names an existing absolute directory, and a tool call still moves to the checkout its absolute `workdir` or `path` proves. A gateway session that expires idle is never finalized; close it with `ai-memory finalize-session --agent hermes`. When the community [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is installed in `$HERMES_HOME/plugins/ai-memory`, the block wires only the two tool events, because the plugin already captures prompts, ends sessions and claims the handoff. MCP: `install-mcp --client hermes` prints an `mcp_servers:` entry that runs `ai-memory mcp-bridge --no-session-id` (no token in the file, and `--apply` is refused). Hermes does not read MCP server instructions, so install the skills with `install-skills --scope global --agent hermes` (`~/.hermes/skills`). No managed workstream. Modeled on the Hermes v0.22.2 source; not yet run end to end by the maintainers. || GrizzyBot | Supported | [GrizzyBot](https://github.com/Foscoe63/GrizzyBot), a native macOS agent app, ships its own ai-memory bridge: it posts lifecycle events to `/hook` with `agent=grizzybot` (alias `grizzy-bot`) and talks to `/mcp` directly, so there is nothing for `install-hooks` or `install-mcp` to write. Sessions are attributed to `grizzybot`, and its Claude Code-shaped tool payloads (`tool_name`/`tool_input`/`tool_use_id`) are stored as closed-schema tool families, never tool names or arguments. The bridge is maintained in the GrizzyBot repository; review it before pointing it at a shared server. No managed workstream. || Factory Droid | Supported | MCP config (`install-mcp --client droid`, alias `factory-droid` → `~/.factory/mcp.json`, root `mcpServers`, `type: "http"`) + lifecycle hooks (`install-hooks --agent droid` → `~/.factory/hooks.json`) (#1240). The URL is written literally because Droid expands `${VAR}` only in headers; a bearer becomes `Authorization: Bearer ${AI_MEMORY_AUTH_TOKEN}`, so export that variable where droid runs (a token-file install gets the same reference, never the token). Droid sends Claude Code-shaped hook payloads, so each entry runs the native `ai-memory hook --event … --agent droid` command (no script bundle) and native commands enforce capture exclusions over Droid's `Read`, `Create`, `Edit`, `ApplyPatch`, `LS`, `Grep`, `Glob` and `Execute` tools, verified against the Droid 0.240.0 tool schemas; Droid payloads carry no tool-call id. Seven events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`, `SessionEnd`. The `SessionStart` hook delivers the prior session's handoff through `hookSpecificOutput.additionalContext`, and Droid's own `SessionEnd` closes the session, so no `finalize-session` step is needed. `--apply` merges around your own entries, and refuses to create `hooks.json` while `~/.factory/settings.json` keeps hooks under its `hooks` key, because Droid reads those only while `hooks.json` is absent. The issue reporter ran capture and recall end to end with this hook wiring on Droid 0.239.0; the handoff injection follows Droid's documented contract and has not been run end to end yet. No managed workstream (`ai-memory run droid`). See [`install.md`](install.md#factory-droid). || CodeBuddy Code | Hooks-only | Tencent CodeBuddy Code (`codebuddy`, alias `code-buddy`). Lifecycle-hook capture via `install-hooks --agent codebuddy --apply`: native `ai-memory hook` commands (no script bundle) merged into the `hooks` key of `~/.codebuddy/settings.json` around sibling settings and third-party hooks. Payloads are Claude Code-shaped (`session_id`, `cwd`, `tool_name`, `tool_input`, `tool_response`), so tool observations and capture exclusions use that parser. Seven events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`, `SessionEnd`. `SessionStart` stdout (`hookSpecificOutput.additionalContext`) delivers the prior session's handoff; with nothing to deliver, `SessionStart` and `UserPromptSubmit` print nothing, because CodeBuddy appends that stdout to the session. An interactive `SessionStart` may arrive without `cwd`; the hook then uses the `CODEBUDDY_PROJECT_DIR` CodeBuddy exports, and when neither names a directory it captures the event but claims no handoff, which stays open for `memory_handoff_accept`. `setup` detects CodeBuddy when `~/.codebuddy` exists. No `install-mcp` client, no transcript backfill, no headless `codebuddy -p` session close and no managed workstream are claimed. Verified against CodeBuddy's hook documentation and the payloads reported on v2.164–v2.167 (#1299); not yet run end to end by the maintainers. See [`install.md`](install.md#codebuddy-code). |