Skip to content

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

Rust

feat: install Hermes Agent lifecycle hooks

Caminhar3d84623b98f0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e2684a24..3a2a13e4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -208,6 +208,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
reaches the spool or the wire. The captured excerpt continues the work in
the next session's automatic handoff; it is not rendered into the
git-tracked session page. (#865)
+- `install-hooks --agent hermes` (alias `hermes-agent`) and
+ `setup-agent --agent hermes` for **Hermes Agent** (Nous Research). Hermes
+ splits a configured hook `command` with `shlex.split` and runs it with **no
+ shell**, with the event JSON on stdin, so the generated block invokes the
+ native `hook` subcommand directly — the same shape Zero and ZCode use, and no
+ `.sh`/`.ps1` bundle is staged. Two events are wired, `pre_tool_call` and
+ `post_tool_call`, whose payload (`tool_name` / `tool_input`) is the envelope
+ the router already mapped for `agent=hermes`; this is what finally gives
+ Hermes sessions tool observations. `~/.hermes/config.yaml` is printed, never
+ written: it is YAML the operator also edits, and Hermes gates user hooks
+ behind its own acceptance prompt (`hooks_auto_accept`). Session lifecycle
+ stays with the ai-memory memory-provider plugin, so a hook-driven
+ `session-end` cannot double-close a session. (#623 follow-up, #933)
### Changed
- A capture into a project its author may not write is dropped server-side
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 1b76a0da..a7dba82d 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -1884,6 +1884,19 @@ pub enum AgentChoice {
/// so close sessions with `ai-memory finalize-session --agent zcode`.
#[value(alias = "zai")]
Zcode,
+ /// Hermes Agent (Nous Research) — lifecycle hooks declared in the `hooks:`
+ /// block of `~/.hermes/config.yaml`. Hermes runs each `command` through
+ /// `shlex.split` with the event JSON on stdin and **no shell**, so
+ /// ai-memory's native `hook` subcommand is invoked directly (exec form,
+ /// like Zero and ZCode). ai-memory wires the two events that give Hermes
+ /// tool observations — `pre_tool_call` / `post_tool_call`, whose payload
+ /// carries `tool_name` / `tool_input`, the envelope the router already
+ /// recognises for `agent=hermes`. `~/.hermes/config.yaml` is NOT written:
+ /// it is YAML the installer would have to splice, and Hermes gates user
+ /// hooks behind its own acceptance prompt (`hooks_auto_accept`), so
+ /// `install-hooks --agent hermes` prints the ready-to-paste block.
+ #[value(alias = "hermes-agent")]
+ Hermes,
}
impl AgentChoice {
@@ -1913,6 +1926,7 @@ impl AgentChoice {
Self::CommandCode => AgentKind::CommandCode,
Self::Pool => AgentKind::Pool,
Self::Zcode => AgentKind::Zcode,
+ Self::Hermes => AgentKind::Hermes,
}
}
@@ -1930,7 +1944,8 @@ impl AgentChoice {
| Self::Omp
| Self::Openclaw
| Self::Zero
- | Self::Zcode => None,
+ | Self::Zcode
+ | Self::Hermes => None,
_ => Some(self.kind().as_str()),
}
}
@@ -3667,6 +3682,37 @@ mod tests {
assert_eq!(args.agent, ai_memory_core::AgentKind::Zcode);
}
+ /// Hermes is the second no-shell harness (after ZCode): it splits the
+ /// configured `command` into argv itself, so the generated block invokes
+ /// the native `hook` subcommand instead of a `.sh` bundle.
+ #[test]
+ fn hermes_hook_and_finalize_aliases_parse() {
+ for alias in ["hermes", "hermes-agent"] {
+ let cli = Cli::try_parse_from([
+ "ai-memory",
+ "install-hooks",
+ "--agent",
+ alias,
+ "--server-url",
+ "http://127.0.0.1:49374",
+ ])
+ .unwrap_or_else(|error| panic!("failed to parse Hermes alias {alias}: {error}"));
+ let Command::InstallHooks(args) = cli.command else {
+ panic!("expected install-hooks for Hermes alias {alias}");
+ };
+ assert_eq!(args.agent, AgentChoice::Hermes);
+ assert_eq!(args.agent.kind(), ai_memory_core::AgentKind::Hermes);
+ // Native exec-form integration: no script bundle to stage.
+ assert_eq!(args.agent.script_hook_subdir(), None);
+ }
+ let cli = Cli::try_parse_from(["ai-memory", "finalize-session", "--agent", "hermes"])
+ .expect("failed to parse finalize-session --agent hermes");
+ let Command::FinalizeSession(args) = cli.command else {
+ panic!("expected finalize-session for hermes");
+ };
+ assert_eq!(args.agent, ai_memory_core::AgentKind::Hermes);
+ }
+
#[test]
fn command_code_mcp_and_hook_aliases_parse() {
for alias in ["command-code", "commandcode", "cmdc", "cmd"] {
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 4c36edc4..99f061db 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -589,6 +589,14 @@ pub fn run(config: &Config, mut args: InstallHooksArgs) -> Result<()> {
}
AgentChoice::Zero => apply_to_zero_hooks(&server_url, auth, &config.data_dir, &args),
AgentChoice::Zcode => apply_to_zcode_hooks(&server_url, auth, &config.data_dir, &args),
+ AgentChoice::Hermes => {
+ // Nothing to write or stage: the block invokes the native
+ // `hook` subcommand, and `~/.hermes/config.yaml` is a YAML file
+ // the operator also edits (and Hermes itself gates hooks behind
+ // an acceptance prompt). The render step below prints the
+ // ready-to-paste block.
+ Ok(())
+ }
AgentChoice::Devin => {
let hooks_dir =
resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
@@ -735,6 +743,7 @@ pub fn run(config: &Config, mut args: InstallHooksArgs) -> Result<()> {
}
AgentChoice::Zero => render_zero(&server_url, auth, &config.data_dir, strategy),
AgentChoice::Zcode => render_zcode(&server_url, auth, &config.data_dir, strategy),
+ AgentChoice::Hermes => render_hermes(&server_url, auth, &config.data_dir, strategy),
AgentChoice::Devin => {
let hooks_dir =
resolve_hooks_dir(args.hooks_dir.as_deref(), args.agent, &config.data_dir)?;
@@ -950,6 +959,10 @@ fn existing_agent_config(args: &InstallHooksArgs) -> Option<String> {
AgentChoice::Grok => grok_hooks_path().ok()?,
AgentChoice::Zero => zero_hooks_path().ok()?,
AgentChoice::Zcode => zcode_config_path().ok()?,
+ // Hermes' hook config is `~/.hermes/config.yaml`, which ai-memory
+ // never writes, so there is no install-owned file to recover a
+ // baked project strategy from.
+ AgentChoice::Hermes => return None,
AgentChoice::Devin => devin_hooks_path().ok()?,
AgentChoice::KimiCode => kimi_code_config_path().ok()?,
AgentChoice::KiroCli => return None,
@@ -1361,6 +1374,9 @@ pub(crate) fn mcp_client_for_agent(agent: AgentChoice) -> Option<McpClient> {
// no `McpClient::Zcode` whose config the installer could scrape a
// server URL or token from.
AgentChoice::Zcode => None,
+ // No first-party Hermes MCP installer ships yet, so there is no config
+ // file to infer a server URL or token from.
+ AgentChoice::Hermes => None,
}
}
@@ -5779,6 +5795,63 @@ fn render_zcode(
Ok(())
}
+/// `install-hooks --agent hermes`: print the ready-to-paste `hooks:` block for
+/// `~/.hermes/config.yaml`.
+///
+/// ai-memory deliberately does not write that file. It is YAML the operator
+/// also edits (comments, other hooks) and would have to be spliced, and Hermes
+/// gates user hooks behind its own acceptance prompt (`hooks_auto_accept`
+/// asks before registering one), so entries appearing silently would fight
+/// both. There is nothing to stage either: the block invokes the native `hook`
+/// subcommand, not a `.sh` bundle.
+fn render_hermes(
+ server_url: &str,
+ auth_token: Option<&str>,
+ data_dir: &Path,
+ project_strategy: Option<&str>,
+) -> Result<()> {
+ print!(
+ "{}",
+ render_hermes_output(server_url, auth_token, data_dir, project_strategy)
+ );
+ Ok(())
+}
+
+fn render_hermes_output(
+ server_url: &str,
+ auth_token: Option<&str>,
+ data_dir: &Path,
+ project_strategy: Option<&str>,
+) -> String {
+ let block = super::render_shared::build_hermes_hooks_yaml(
+ server_url,
+ auth_token,
+ Some(data_dir),
+ project_strategy,
+ );
+ let mut out = String::new();
+ out.push_str("# Hermes Agent hooks config — merge the `hooks:` block below\n");
+ out.push_str("# into ~/.hermes/config.yaml and let Hermes accept it when it\n");
+ out.push_str("# prompts (or set `hooks_auto_accept: true`). ai-memory does not\n");
+ out.push_str("# write that file: it is YAML you also edit, and it would have to\n");
+ out.push_str("# be spliced.\n");
+ out.push_str(&format!("# AI-memory server URL: {server_url}\n"));
+ if auth_token.is_some() {
+ out.push_str("# Auth: this snippet embeds the token in each hook command —\n");
+ out.push_str("# treat ~/.hermes/config.yaml as sensitive (chmod 600).\n");
+ }
+ out.push_str("# NOTE: only the two tool events are wired — that is what gives\n");
+ out.push_str("# Hermes tool observations. Session lifecycle (prompts,\n");
+ out.push_str("# session-end, the automatic handoff) is handled by the\n");
+ out.push_str("# ai-memory memory-provider plugin, so nothing is duplicated.\n");
+ out.push_str("# NOTE: each `command` is a bare argv line. Hermes splits it with\n");
+ out.push_str("# shlex.split and runs it without a shell, so the generated\n");
+ out.push_str("# command invokes the ai-memory binary directly.\n");
+ out.push('\n');
+ out.push_str(&block);
+ out
+}
+
fn render_devin(
hooks_dir: &Path,
server_url: &str,
@@ -7123,6 +7196,28 @@ command = "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/a
assert!(!out.contains("AI_MEMORY_AUTH_TOKEN embedded"));
}
+ /// Hermes' output must state the manual paste step (ai-memory does not write
+ /// `~/.hermes/config.yaml`) and must not advertise a staged bundle or a
+ /// session-end hook — the memory-provider plugin owns session lifecycle.
+ #[test]
+ fn render_hermes_output_states_manual_paste_and_plugin_owned_lifecycle() {
+ let out = render_hermes_output("http://127.0.0.1:49374", None, Path::new("/data"), None);
+ assert!(out.contains("~/.hermes/config.yaml"));
+ assert!(out.contains("ai-memory does not"));
+ assert!(out.contains("hooks:\n"));
+ assert!(out.contains("pre_tool_call"));
+ assert!(out.contains("post_tool_call"));
+ assert!(out.contains("--agent hermes"));
+ assert!(out.contains("without a shell"));
+ assert!(out.contains("memory-provider plugin"));
+ // Tool events only: a hook-driven session-end would double-close a
+ // session the plugin already closes.
+ assert!(!out.contains("session_end"));
+ assert!(!out.contains("session-end:"));
+ // No token was passed, so the auth caution line stays out.
+ assert!(!out.contains("chmod 600"));
+ }
+
// Issue #156: Zero hook install writes exec-form entries into Zero's
// hooks.json shape and merges around third-party hooks by id prefix.
#[test]
diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rs
index a85c5d41..15681494 100644
--- a/crates/ai-memory-cli/src/commands/render_shared.rs
+++ b/crates/ai-memory-cli/src/commands/render_shared.rs
@@ -595,6 +595,80 @@ pub(crate) const ZCODE_HOOK_TIMEOUT_MS: u64 = 10_000;
/// (same reasoning as Kiro v2's `max_output_size`).
pub(crate) const ZCODE_HOOK_MAX_OUTPUT_BYTES: usize = 64 * 1024;
+/// Hermes Agent lifecycle events ai-memory hooks. Each pair is
+/// `(event-name-in-~/.hermes/config.yaml, native `hook --event` value)`.
+///
+/// Verified against Hermes v0.21.4 (`agent/shell_hooks.py`): a configured
+/// `command` is split into argv by `shlex.split` and executed **without a
+/// shell**, with the event JSON on stdin — so the generated block invokes the
+/// native `hook` subcommand, the same shape Zero and ZCode use, and no
+/// `.sh`/`.ps1` bundle is staged. Only the two tool events are wired: their
+/// payload carries `tool_name` / `tool_input`, the envelope the router already
+/// maps for `agent=hermes`. Session lifecycle stays with the memory-provider
+/// plugin (`on_session_end`), so a hook-driven `session-end` cannot
+/// double-close a Hermes session.
+pub(crate) const HERMES_EVENTS: [(&str, &str); 2] = [
+ ("pre_tool_call", "pre-tool-use"),
+ ("post_tool_call", "post-tool-use"),
+];
+
+/// Wall-clock bound written into each Hermes hook entry. Capture POSTs are
+/// fire-and-forget, so this only bounds a hung `hook` invocation.
+pub(crate) const HERMES_HOOK_TIMEOUT_SECONDS: u64 = 20;
+
+/// The ready-to-paste `hooks:` block for `~/.hermes/config.yaml`.
+///
+/// `command:` must be a bare argv line — Hermes splits it itself, so the
+/// `KEY=value script` prefix every shell-run harness gets would be parsed as
+/// extra argv entries. The native platform already emits the argv form
+/// (`<exe> [--data-dir …] hook --event … --agent hermes --server-url …`), and
+/// the YAML single-quote keeps any POSIX quoting inside it intact. ai-memory
+/// deliberately does not write the file: it is YAML the installer would have
+/// to splice, and Hermes gates user hooks behind its own acceptance prompt.
+#[must_use]
+pub(crate) fn build_hermes_hooks_yaml(
+ server_url: &str,
+ auth_token: Option<&str>,
+ data_dir: Option<&Path>,
+ project_strategy: Option<&str>,
+) -> String {
+ build_hermes_hooks_yaml_for_platform(
+ server_url,
+ auth_token,
+ HookCommandContext::new(
+ HookCommandPlatform::for_bash_runner(),
+ "hermes",
+ data_dir,
+ project_strategy,
+ ),
+ )
+}
+
+/// Platform-forced variant, so a test can pin POSIX/Windows instead of
+/// asserting whatever the machine running the suite happens to be.
+fn build_hermes_hooks_yaml_for_platform(
+ server_url: &str,
+ auth_token: Option<&str>,
+ context: HookCommandContext<'_>,
+) -> String {
+ let mut out = String::from("hooks:\n");
+ for (hermes_event, our_event) in HERMES_EVENTS {
+ // The native platforms derive the event token from the script stem, so
+ // the synthetic filename carries the ai-memory event name.
+ let command = hook_command(
+ Path::new(&format!("{our_event}.sh")),
+ server_url,
+ auth_token,
+ context,
+ );
+ out.push_str(&format!(
+ " {hermes_event}:\n - command: {}\n timeout: {HERMES_HOOK_TIMEOUT_SECONDS}\n",
+ yaml_single_quote(&command)
+ ));
+ }
+ out
+}
+
/// Devin hook payload for docker/setup-agent script snippets.
/// Devin uses HookShape::Nested (same as Claude Code/Grok) but with
/// DEVIN_EVENTS (PostCompaction instead of PreCompact, no subagent events).
@@ -2879,6 +2953,56 @@ if (inheritOnly) {
assert!(args.iter().all(|arg| !arg.contains(r"\\?\")));
}
+ /// The public entry point must emit a complete `hooks:` map with both tool
+ /// events, whatever platform it renders for (the suite runs on Windows too).
+ #[test]
+ fn hermes_hooks_yaml_covers_both_tool_events() {
+ let yaml = build_hermes_hooks_yaml("http://127.0.0.1:49374", None, None, None);
+ assert!(yaml.starts_with("hooks:\n"));
+ for (event, _) in HERMES_EVENTS {
+ assert!(yaml.contains(&format!(" {event}:\n")), "missing {event}");
+ assert!(
+ yaml.contains(" - command: '"),
+ "command must be a single-quoted YAML scalar"
+ );
+ }
+ assert_eq!(
+ yaml.matches(&format!("timeout: {HERMES_HOOK_TIMEOUT_SECONDS}"))
+ .count(),
+ HERMES_EVENTS.len()
+ );
+ }
+
+ /// Hermes splits `command` with `shlex.split` and runs it with no shell, so
+ /// the generated line must be bare argv: a `KEY=value` prefix would be
+ /// parsed as extra argv entries and the hook would never reach the server.
+ #[test]
+ fn hermes_hooks_yaml_invokes_the_native_command_without_a_shell() {
+ let yaml = build_hermes_hooks_yaml_for_platform(
+ "http://127.0.0.1:49374",
+ None,
+ HookCommandContext::new(
+ HookCommandPlatform::PosixNative,
+ "hermes",
+ Some(Path::new("/data")),
+ Some("repo-root"),
+ ),
+ );
+ for (_, our_event) in HERMES_EVENTS {
+ assert!(
+ yaml.contains(&format!("hook --event {our_event} --agent hermes")),
+ "missing the native command for {our_event}"
+ );
+ }
+ assert!(
+ !yaml.contains("AI_MEMORY_HOOK_URL="),
+ "an env prefix would be parsed as argv, not environment"
+ );
+ assert!(yaml.contains("--data-dir /data"));
+ assert!(yaml.contains("--server-url http://127.0.0.1:49374"));
+ assert!(yaml.contains("--project-strategy repo-root"));
+ }
+
fn exec_args(script: &str, capture_assistant: bool) -> Vec<String> {
let spec = windows_native_exec_spec_with_exe(
Path::new(r"C:\ai-memory\ai-memory.exe"),
diff --git a/crates/ai-memory-cli/src/commands/setup_agent.rs b/crates/ai-memory-cli/src/commands/setup_agent.rs
index 1fba1544..d2ee4b55 100644
--- a/crates/ai-memory-cli/src/commands/setup_agent.rs
+++ b/crates/ai-memory-cli/src/commands/setup_agent.rs
@@ -84,6 +84,12 @@ pub fn run(config: &Config, args: SetupAgentArgs) -> Result<()> {
emit_zcode(&args)?;
return Ok(());
}
+ // Hermes also runs the native `hook` command directly (no shell), so there
+ // are no scripts to stage — setup-agent prints the YAML block instead.
+ if matches!(args.agent, AgentChoice::Hermes) {
+ emit_hermes(&args)?;
+ return Ok(());
+ }
let Some(agent_sub) = args.agent.script_hook_subdir() else {
bail!("internal: generated integration should have returned before staging hooks")
};
@@ -176,7 +182,8 @@ pub fn run(config: &Config, args: SetupAgentArgs) -> Result<()> {
| AgentChoice::Omp
| AgentChoice::Openclaw
| AgentChoice::Zero
- | AgentChoice::Zcode => {
+ | AgentChoice::Zcode
+ | AgentChoice::Hermes => {
bail!(
"internal: generated integration should have returned before emitting staged hooks"
)
@@ -245,6 +252,35 @@ fn emit_zcode(args: &SetupAgentArgs) -> Result<()> {
Ok(())
}
+/// Print the `hooks:` block for `~/.hermes/config.yaml` (the follow-up to
+/// #623, where Hermes was accepted for capture/storage but had no installer).
+/// No scripts are staged: Hermes splits the configured `command` itself and
+/// runs the ai-memory binary directly with the JSON payload on stdin. The
+/// binary must be reachable on the host that runs Hermes — for docker-wrapper
+/// setups install the native binary or point `command` at the wrapper.
+fn emit_hermes(args: &SetupAgentArgs) -> Result<()> {
+ let block = crate::commands::render_shared::build_hermes_hooks_yaml(
+ &args.server_url,
+ args.auth_token.as_deref(),
+ None,
+ None,
+ );
+ println!("# Hermes Agent — merge the `hooks:` block into ~/.hermes/config.yaml");
+ println!("# The `command` must be an ai-memory binary reachable on the host that");
+ println!("# runs Hermes; prefer `ai-memory install-hooks --agent hermes` from");
+ println!("# that host so the path is resolved for you.");
+ if args.auth_token.is_some() {
+ println!("# Treat the config as sensitive (chmod 600).");
+ }
+ println!("# NOTE: Hermes splits each `command` with shlex.split and runs it with");
+ println!("# no shell, so the generated line is argv, not a shell command.");
+ println!("# NOTE: tool observations only — session lifecycle stays with the");
+ println!("# ai-memory memory-provider plugin.");
+ println!();
+ println!("{block}");
+ Ok(())
+}
+
fn normalise_hook_server_url(url: &str) -> String {
url.trim().trim_end_matches('/').to_string()
}
diff --git a/docs/install.md b/docs/install.md
index ff7c052b..26b69787 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1187,6 +1187,42 @@ ai-memory finalize-session --agent zcode --session-id <uuid>
No first-party `install-mcp` client and no managed workstream
(`ai-memory run zcode`) are claimed yet.
+### 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:
+
+```bash
+ai-memory install-hooks --agent hermes \
+ --server-url "http://homelab:49374" \
+ --auth-token "$TOKEN"
+```
+
+Hermes splits each configured `command` with `shlex.split` and runs it with
+**no shell**, passing the event JSON on stdin — so the generated entry invokes
+the 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.
+
+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`.
+
+No first-party `install-mcp` client and no managed workstream
+(`ai-memory run hermes`) are claimed yet.
+
### OpenCode
```bash
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 4c1a3c08..305abc48 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -65,19 +65,34 @@ calling `/hook` directly. For a third-party bridge that has its own
lifecycle vocabulary, keep the core `event` query param on one of
ai-memory's canonical events when possible:
-### Community-maintained Hermes Agent plugin
+### Hermes Agent
-ai-memory does not currently ship a first-party Hermes Agent installer,
-but a community-maintained
+ai-memory ships a first-party hook installer for Hermes Agent:
+
+```bash
+ai-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-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin)
-is available. Treat it as a third-party bridge: verify the plugin's
-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.
-
-The hook router does recognize `agent=hermes` as a concrete session kind and
+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.
+
+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
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index db651e56..aa1cc0f9 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -35,6 +35,6 @@
| VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). |
| Zed | MCP-only | Native remote MCP under `context_servers` in Zed's user `settings.json`; no lifecycle hooks or managed-workstream support. |
| Muse Code | MCP-only | `install-mcp --client muse` merges a native streamable-HTTP entry with bearer `headers` into the snake_case `mcp_servers` map of `~/.config/muse/settings.json`, preserving sibling servers. The writer adds the mandatory `"schema_version": 1` when absent (without it every `muse` command fails at startup) and never rewrites an existing value, and it sets `"mode": "optional"` because Muse's default `required` aborts the whole run when the server is unreachable. Skills need no extra step: Muse reads `~/.agents/skills`, which `install-skills` already writes. Lifecycle capture and managed workstreams are not claimed — Muse documents a hook surface, but the output contract of its `SessionStart` event is not specified. |
-| Hermes Agent | Community | Core hook ingestion recognizes `agent=hermes` and Hermes' documented shell-hook `tool_name` / `tool_input` payload for concrete session attribution, tool-family titles, and capture exclusions. A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available, but no first-party installer is shipped; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. Hermes ignores session-start hook stdout, so recover handoffs through MCP. |
+| Hermes Agent | Supported | `install-hooks --agent hermes` (alias `hermes-agent`) prints a ready-to-paste `hooks:` block for `~/.hermes/config.yaml`. Hermes splits each configured `command` with `shlex.split` and runs it with no shell, passing the event JSON on stdin, so the entries invoke the native `ai-memory hook` command (exec form, like Zero and ZCode — no script bundle is staged); ai-memory never writes that YAML file, which is yours to edit and which Hermes itself gates behind its hook-acceptance prompt (`hooks_auto_accept`). Two tool events are wired, `pre_tool_call` → `pre-tool-use` and `post_tool_call` → `post-tool-use`; their `tool_name` / `tool_input` payload drives concrete session attribution, tool-family titles, and capture exclusions. Session lifecycle (recall, prompt capture, session-end, automatic handoff) is owned by the community-maintained [`ai-memory-hermes-plugin`](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`). |
| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode (Go and Zen), OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |
| Embedding providers | Supported | OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM. |