Skip to content

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

Rust

feat(hermes): route a gateway's named profiles by a marker in their own Hermes home

4nrryfd7bae42e207
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6609cfa4..8f6dfb78 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,18 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Added
+
+- Added project routing for the named profiles of a multiplexing Hermes
+ gateway. The gateway exports only the default profile's `terminal.cwd`, so
+ every other profile's events used to fall back to the gateway's own working
+ directory and all its bots landed in one project. A gateway event of a named
+ profile now routes by an `.ai-memory.toml` placed in that profile's Hermes
+ home (`~/.hermes/profiles/<name>`, or under the gateway's `HERMES_HOME`), and
+ that marker's capture exclusions and server profile apply. A profile without
+ such a marker keeps the old behavior. The profile name is checked against
+ Hermes' profile-id pattern before it is used as a path (#TBD).
+
## [3.2.0] - 2026-10-21
### Added
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 9b8c3410..800e6fd7 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -1030,10 +1030,7 @@ const HERMES_GATEWAY_HOST_PROFILE: &str = "default";
/// fired. A standalone gateway of another profile loses it too: nothing in
/// the hook's environment tells it apart from a multiplexed one.
fn hermes_terminal_cwd(runtime_env: &RuntimeEnv, profile: Option<&str>) -> Option<String> {
- let in_gateway = runtime_env
- .var_os(HERMES_GATEWAY_ENV)
- .is_some_and(|value| value == "1");
- if in_gateway && profile != Some(HERMES_GATEWAY_HOST_PROFILE) {
+ if hermes_in_gateway(runtime_env) && profile != Some(HERMES_GATEWAY_HOST_PROFILE) {
return None;
}
let path = PathBuf::from(runtime_env.var_os(HERMES_TERMINAL_CWD_ENV)?);
@@ -1043,6 +1040,68 @@ fn hermes_terminal_cwd(runtime_env: &RuntimeEnv, profile: Option<&str>) -> Optio
path.to_str().map(str::to_owned)
}
+fn hermes_in_gateway(runtime_env: &RuntimeEnv) -> bool {
+ runtime_env
+ .var_os(HERMES_GATEWAY_ENV)
+ .is_some_and(|value| value == "1")
+}
+
+/// A gateway event of a profile other than the host's, routed by an
+/// `.ai-memory.toml` the operator placed in that profile's own Hermes home.
+/// Its `terminal.cwd` never reaches the hook (see `hermes_terminal_cwd`), so
+/// without this every bot profile of a gateway lands in the gateway's own
+/// cwd. The profile directory is used only when it holds its own marker: an
+/// unmarked profile keeps the process cwd it always had, rather than turning
+/// into a project named after the profile.
+///
+/// The name comes from the payload, so it must be a Hermes profile id
+/// (`PROFILE_ID_RE` in `hermes_constants.py`) before it becomes a path
+/// component. Profiles live in `<root>/profiles/<name>` (`get_profile_dir` in
+/// `hermes_cli/profiles.py`), where the root is the gateway's `HERMES_HOME`,
+/// else `~/.hermes`; a standalone gateway of a named profile runs with that
+/// profile's directory as its `HERMES_HOME`.
+fn hermes_profile_marker_cwd(runtime_env: &RuntimeEnv, profile: Option<&str>) -> Option<String> {
+ if !hermes_in_gateway(runtime_env) || runtime_env.ignore_marker() {
+ return None;
+ }
+ let profile = profile
+ .filter(|name| *name != HERMES_GATEWAY_HOST_PROFILE && is_hermes_profile_id(name))?;
+ let hermes_home = crate::commands::path_util::agent_config_home(
+ runtime_env.var_os("HERMES_HOME"),
+ )
+ .or_else(|| {
+ runtime_env
+ .home_dir()
+ .map(|home| Path::new(home).join(".hermes"))
+ })?;
+ let standalone = hermes_home.file_name() == Some(std::ffi::OsStr::new(profile))
+ && hermes_home
+ .parent()
+ .and_then(Path::file_name)
+ .is_some_and(|parent| parent == "profiles");
+ let dir = if standalone {
+ hermes_home
+ } else {
+ hermes_home.join("profiles").join(profile)
+ };
+ if !dir.is_absolute() || !dir.join(".ai-memory.toml").is_file() {
+ return None;
+ }
+ dir.to_str().map(str::to_owned)
+}
+
+/// `^[a-z0-9][a-z0-9_-]{0,63}$`, Hermes' `PROFILE_ID_RE`.
+fn is_hermes_profile_id(name: &str) -> bool {
+ let bytes = name.as_bytes();
+ bytes.len() <= 64
+ && bytes
+ .first()
+ .is_some_and(|first| first.is_ascii_lowercase() || first.is_ascii_digit())
+ && bytes
+ .iter()
+ .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || *b == b'_' || *b == b'-')
+}
+
/// Run a single hook end-to-end. Always returns Ok and always writes a JSON
/// object to stdout — a hook must never fail the agent.
///
@@ -1273,10 +1332,14 @@ where
// Hermes reports its own process cwd on every event, which for a gateway
// is wherever the gateway started. The session's working directory is
// `terminal.cwd`, which Hermes exports to hooks as `TERMINAL_CWD`, so that
- // replaces the reported cwd. A tool event can still move to another
- // checkout its own absolute locations prove (below).
+ // replaces the reported cwd; a gateway's other profiles route by a marker
+ // in their own Hermes home instead. A tool event can still move to
+ // another checkout its own absolute locations prove (below).
let payload_cwd = match (agent_kind == AgentKind::Hermes)
- .then(|| hermes_terminal_cwd(&runtime_env, hermes_profile.as_deref()))
+ .then(|| {
+ hermes_terminal_cwd(&runtime_env, hermes_profile.as_deref())
+ .or_else(|| hermes_profile_marker_cwd(&runtime_env, hermes_profile.as_deref()))
+ })
.flatten()
{
Some(cwd) => {
@@ -8688,6 +8751,180 @@ mod tests {
}
}
+ /// A Hermes home with one named profile carrying its own marker.
+ fn hermes_root_with_profile_marker(parent: &Path, profile: &str, marker: &str) -> PathBuf {
+ let root = parent.join("hermes-root");
+ repo_with_marker(&root.join("profiles"), profile, marker);
+ root
+ }
+
+ #[test]
+ fn hermes_profile_marker_cwd_takes_only_a_marked_named_profile_in_a_gateway() {
+ let tmp = tempfile::tempdir().unwrap();
+ let root = hermes_root_with_profile_marker(tmp.path(), "sc-seo", "project = \"p\"\n");
+ std::fs::create_dir_all(root.join("profiles").join("unmarked")).unwrap();
+ let profile_dir = root.join("profiles").join("sc-seo");
+ let root_str = root.to_str().unwrap();
+ let gateway = RuntimeEnv::with_process_env_for_tests(&[
+ ("HERMES_HOME", root_str),
+ ("_HERMES_GATEWAY", "1"),
+ ]);
+ assert_eq!(
+ hermes_profile_marker_cwd(&gateway, Some("sc-seo")).as_deref(),
+ profile_dir.to_str()
+ );
+ assert_eq!(hermes_profile_marker_cwd(&gateway, Some("unmarked")), None);
+ assert_eq!(hermes_profile_marker_cwd(&gateway, Some("missing")), None);
+ assert_eq!(hermes_profile_marker_cwd(&gateway, None), None);
+ // The default profile's directory is the root; its route is `TERMINAL_CWD`.
+ std::fs::write(root.join(".ai-memory.toml"), "project = \"root\"\n").unwrap();
+ assert_eq!(hermes_profile_marker_cwd(&gateway, Some("default")), None);
+ // Outside a gateway the process cwd and `TERMINAL_CWD` are the session's own.
+ let standalone_cli = RuntimeEnv::with_process_env_for_tests(&[("HERMES_HOME", root_str)]);
+ assert_eq!(
+ hermes_profile_marker_cwd(&standalone_cli, Some("sc-seo")),
+ None
+ );
+ // A standalone gateway of the profile runs with its directory as HERMES_HOME.
+ let own_gateway = RuntimeEnv::with_process_env_for_tests(&[
+ ("HERMES_HOME", profile_dir.to_str().unwrap()),
+ ("_HERMES_GATEWAY", "1"),
+ ]);
+ assert_eq!(
+ hermes_profile_marker_cwd(&own_gateway, Some("sc-seo")).as_deref(),
+ profile_dir.to_str()
+ );
+ }
+
+ /// Adversarial: the profile name arrives in the payload, so a name that is
+ /// not a Hermes profile id never becomes a path, even when a marker waits
+ /// where it would lead.
+ #[test]
+ fn hermes_profile_marker_cwd_refuses_a_name_that_is_not_a_profile_id() {
+ let tmp = tempfile::tempdir().unwrap();
+ let root = hermes_root_with_profile_marker(tmp.path(), "sc-seo", "project = \"p\"\n");
+ repo_with_marker(&root, "escape", "project = \"escape\"\n");
+ repo_with_marker(&root.join("profiles"), "Upper", "project = \"upper\"\n");
+ let gateway = RuntimeEnv::with_process_env_for_tests(&[
+ ("HERMES_HOME", root.to_str().unwrap()),
+ ("_HERMES_GATEWAY", "1"),
+ ]);
+ for name in ["../escape", "sc-seo/..", "Upper", "", "-lead", "a/b"] {
+ assert_eq!(
+ hermes_profile_marker_cwd(&gateway, Some(name)),
+ None,
+ "{name}"
+ );
+ }
+ assert!(is_hermes_profile_id(&"a".repeat(64)));
+ assert!(!is_hermes_profile_id(&"a".repeat(65)));
+ // Control: the valid id still routes.
+ assert!(hermes_profile_marker_cwd(&gateway, Some("sc-seo")).is_some());
+ }
+
+ /// A multiplexing gateway reports its own cwd (here an unmarked home) for
+ /// every profile. A named profile whose Hermes home carries a marker is
+ /// routed there under allowlist mode; an unmarked profile keeps the
+ /// gateway cwd, which allowlist mode drops.
+ #[tokio::test]
+ async fn hermes_gateway_profile_routes_by_its_own_marker() {
+ let tmp = tempfile::tempdir().unwrap();
+ let home = tmp.path().join("home");
+ std::fs::create_dir_all(&home).unwrap();
+ let root = hermes_root_with_profile_marker(
+ tmp.path(),
+ "sc-seo",
+ "workspace = \"w\"\nproject = \"smart-compost\"\n",
+ );
+ std::fs::create_dir_all(root.join("profiles").join("sc-unmarked")).unwrap();
+ let gateway = RuntimeEnv::with_process_env_for_tests(&[
+ ("HERMES_HOME", root.to_str().unwrap()),
+ ("_HERMES_GATEWAY", "1"),
+ ]);
+ let payload = |profile: &str| {
+ let mut payload: serde_json::Value = serde_json::from_str(&hermes_payload(
+ "pre_llm_call",
+ &home,
+ pre_llm_call_extra(false),
+ ))
+ .unwrap();
+ payload["profile"] = profile.into();
+ payload.to_string()
+ };
+ let args = || {
+ let mut args = hermes_args("user-prompt-submit", &dead_server_url());
+ args.capture_mode = Some(crate::cli::CaptureModeArg::Allowlist);
+ args
+ };
+ for (profile, spooled) in [("sc-seo", 1), ("sc-unmarked", 0)] {
+ let data_dir = tmp.path().join(format!("data-{profile}"));
+ run_hermes(&data_dir, args(), payload(profile), gateway.clone()).await;
+ let entries = spooled_entries(&data_dir);
+ assert_eq!(entries.len(), spooled, "{profile}");
+ if let Some(entry) = entries.first() {
+ assert_eq!(query_param(&entry.url, "project"), Some("smart-compost"));
+ let body: serde_json::Value = serde_json::from_str(&entry.body).unwrap();
+ assert_eq!(
+ body["cwd"],
+ root.join("profiles").join(profile).to_str().unwrap()
+ );
+ }
+ }
+ }
+
+ /// Adversarial: a profile marker selects where the event lands, so its
+ /// exclusions and server profile govern it, as a checkout's do. An
+ /// excluded relative read is never spooled and an unregistered server
+ /// profile drops the event; a public read is the control.
+ #[tokio::test]
+ async fn hermes_gateway_profile_marker_applies_its_capture_policy() {
+ let tmp = tempfile::tempdir().unwrap();
+ let home = tmp.path().join("home");
+ std::fs::create_dir_all(&home).unwrap();
+ let root = hermes_root_with_profile_marker(
+ tmp.path(),
+ "guarded",
+ "project = \"guarded\"\n[capture]\nignore_paths = [\"secret/**\"]\n",
+ );
+ repo_with_marker(&root.join("profiles"), "routed", "server = \"nobody\"\n");
+ let gateway = RuntimeEnv::with_process_env_for_tests(&[
+ ("HERMES_HOME", root.to_str().unwrap()),
+ ("_HERMES_GATEWAY", "1"),
+ ]);
+ let read = |profile: &str, path: &str| {
+ serde_json::json!({
+ "hook_event_name": "post_tool_call",
+ "tool_name": "read_file",
+ "tool_input": {"path": path},
+ "session_id": "hermes-session",
+ "cwd": home,
+ "profile": profile,
+ "extra": {"tool_call_id": "call-1", "status": "ok", "result": "SENTINEL_CONTENT"}
+ })
+ .to_string()
+ };
+ for (name, profile, path, spooled) in [
+ ("excluded read", "guarded", "secret/token.txt", 0),
+ ("public read", "guarded", "README.md", 1),
+ ("refused profile", "routed", "README.md", 0),
+ ] {
+ let data_dir = tmp.path().join(format!("data-{}", name.replace(' ', "-")));
+ run_hermes(
+ &data_dir,
+ hermes_args("post-tool-use", &dead_server_url()),
+ read(profile, path),
+ gateway.clone(),
+ )
+ .await;
+ let entries = spooled_entries(&data_dir);
+ assert_eq!(entries.len(), spooled, "{name}");
+ assert!(
+ entries.iter().all(|e| !e.body.contains("secret/token")),
+ "{name}"
+ );
+ }
+ }
+
/// Adversarial: `TERMINAL_CWD` selects a checkout, so that checkout's
/// exclusions and server profile apply to what lands there. A relative
/// read of an excluded path is dropped before the spool, a public read is
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 7244bbcc..b66e747b 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -432,8 +432,12 @@ For Hermes the native hook first replaces that process cwd with
names an existing absolute directory; a gateway's process cwd is wherever the
gateway started. A multiplexing gateway exports only the default profile's
`terminal.cwd`, so in a gateway (`_HERMES_GATEWAY=1`) the variable applies only
-to events whose `profile` is `default`. Every Hermes event routes from there,
-and tool events can still move by their own locations.
+to events whose `profile` is `default`. A gateway event of another profile
+routes by that profile's Hermes home (`<HERMES_HOME or ~/.hermes>/profiles/<name>`,
+the name checked against Hermes' profile-id pattern first) when that directory
+holds its own `.ai-memory.toml`, and otherwise keeps the process cwd. 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
diff --git a/docs/install.md b/docs/install.md
index 0f1c5106..f62c3f09 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -2101,8 +2101,21 @@ instead, the variable Hermes exports `terminal.cwd` through, when it names an
existing absolute directory. A multiplexing gateway serves every profile from
the default profile's process and exports only the default profile's
`terminal.cwd`, so inside a gateway the variable is used only for events the
-`default` profile fired; another profile's events keep the process directory.
-A tool call can still move to another checkout
+`default` profile fired. Another profile's events keep the process directory
+unless that profile's own Hermes home (`~/.hermes/profiles/<name>`, under the
+gateway's `HERMES_HOME` when it is set) carries an `.ai-memory.toml`; then the
+hook routes them by that marker. This is how the bots of one gateway reach the
+project they work for:
+
+```toml
+# ~/.hermes/profiles/sc-seo/.ai-memory.toml
+workspace = "default"
+project = "smart-compost"
+```
+
+The marker is an ordinary local marker, so its `[capture]` exclusions and
+`server` profile govern that profile's events. A profile without one is left
+where it was. 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
diff --git a/docs/marker-file.md b/docs/marker-file.md
index 2892a48d..8656bafb 100644
--- a/docs/marker-file.md
+++ b/docs/marker-file.md
@@ -1191,6 +1191,15 @@ only the structured `workdir` field counts. This changes raw observation
attribution only; the session row and its compiled session page remain in the
project where the session began.
+Before that lookup, a Hermes event takes `TERMINAL_CWD` (the session's
+`terminal.cwd`) in place of the process directory. A multiplexing Hermes
+gateway exports only its default profile's `terminal.cwd`, so a gateway event
+of a named profile routes instead by a marker in that profile's own Hermes
+home, `~/.hermes/profiles/<name>/.ai-memory.toml` (under the gateway's
+`HERMES_HOME` when set). It is a normal local marker: `workspace`, `project`,
+`[capture]` and `server` all apply. Without it the event keeps the gateway's
+directory. See [install.md](install.md#hermes-agent-nous-research).
+
Independently of this setting, under `project_strategy = "repo-root"` a
mid-session event whose cwd is outside any git repo *and* any marker (agent
scratch directories, `/tmp`, data folders) already inherits the session's
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 91912ce5..181b3c64 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -145,7 +145,8 @@ the next primary-session turn, including after a native resume),
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
+has the event table, the `TERMINAL_CWD` routing, the per-profile marker for a
+multiplexing gateway's bots and the
`finalize-session --agent hermes` step for idle gateway sessions.
`install-mcp --client hermes` (alias `hermes-agent`) prints an entry for the
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 2d435ee8..c7c99296 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -95,7 +95,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. 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 and, inside a gateway (`_HERMES_GATEWAY=1`), only for an event whose `profile` is `default`, the profile whose `terminal.cwd` a multiplexing gateway exports, 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_gateway_terminal_cwd_routes_only_the_default_profile` (a multiplexed gateway's variable does not route another profile's event), `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 |
+| 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 and, inside a gateway (`_HERMES_GATEWAY=1`), only for an event whose `profile` is `default`, the profile whose `terminal.cwd` a multiplexing gateway exports, before the location lookup above, so that checkout's capture policy, allowlist marker and server profile govern the event. A gateway event of another profile instead goes through `hermes_profile_marker_cwd`, which accepts only a name matching Hermes' profile-id pattern (`^[a-z0-9][a-z0-9_-]{0,63}$`, so no separator or `..` reaches the path), and only when `<HERMES_HOME or ~/.hermes>/profiles/<name>` holds its own `.ai-memory.toml`; that marker's policy then governs the event the same way | `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_gateway_terminal_cwd_routes_only_the_default_profile` (a multiplexed gateway's variable does not route another profile's event), **`hermes_profile_marker_cwd_refuses_a_name_that_is_not_a_profile_id`** (adversarial: `../escape`, `sc-seo/..`, `a/b`, uppercase and over-long names never become a path although a marker waits where they lead; a valid id is the control; fails with the id check removed), **`hermes_gateway_profile_marker_applies_its_capture_policy`** (adversarial: under a profile marker an excluded relative read is never spooled and an unregistered server profile drops the event; public control kept), `hermes_gateway_profile_routes_by_its_own_marker` (allowlist: a marked profile is captured into its project, an unmarked one stays with the gateway cwd and is dropped), `hermes_profile_marker_cwd_takes_only_a_marked_named_profile_in_a_gateway` (default profile, no gateway, unmarked and missing profiles do not route; a standalone gateway's own `HERMES_HOME` does), `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.md
index 302c5abe..4908853b 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`; 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 (an MCP tool, named `mcp__<server>__<tool>`, keeps its server and tool name but never its arguments or result); `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). A `delegate_task` child's lifecycle events are dropped; its tool events are kept. Hermes ignores `on_session_start` output, so every primary-session `pre_llm_call` checks for a pending handoff and prints it as `{"context": ...}`, which Hermes adds to that turn; this includes a resumed native Hermes session. Hermes reports its own process directory as `cwd`; the hook routes by `TERMINAL_CWD` (Hermes' `terminal.cwd`) when it names an existing absolute directory (inside a gateway, only for the `default` profile, whose `terminal.cwd` a multiplexing gateway exports), 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. |
+| 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 (an MCP tool, named `mcp__<server>__<tool>`, keeps its server and tool name but never its arguments or result); `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). A `delegate_task` child's lifecycle events are dropped; its tool events are kept. Hermes ignores `on_session_start` output, so every primary-session `pre_llm_call` checks for a pending handoff and prints it as `{"context": ...}`, which Hermes adds to that turn; this includes a resumed native Hermes session. Hermes reports its own process directory as `cwd`; the hook routes by `TERMINAL_CWD` (Hermes' `terminal.cwd`) when it names an existing absolute directory (inside a gateway, only for the `default` profile, whose `terminal.cwd` a multiplexing gateway exports; another profile's gateway events route by an `.ai-memory.toml` in that profile's own Hermes home, `~/.hermes/profiles/<name>`, when one is there), 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). |