Skip to content

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

Rust

fix(hermes): deliver handoffs to resumed sessions

AkitaOnRails914e1f029510
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04af409f..7d4cbf05 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,8 +17,9 @@ version in [`docs/changelog/`](docs/changelog/):
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
+ `on_session_finalize` as the session end, and each primary-session
+ `pre_llm_call` checks for a pending handoff and brings it into that turn as
+ `{"context": ...}`. This includes a resumed native Hermes session. Hermes
events route by `TERMINAL_CWD` when it names an existing directory (in a
gateway, for the default profile only), and a delegated child's lifecycle
events are dropped. When the
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index b2000c1e..0e0a92c7 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -2459,8 +2459,9 @@ pub enum AgentChoice {
/// ai-memory's native `hook` subcommand is invoked directly (exec form,
/// like Zero and ZCode). ai-memory wires the tool events and the session
/// lifecycle (`on_session_start`, `pre_llm_call`, `on_session_end` as a
- /// turn boundary, `on_session_finalize`); the first turn's `pre_llm_call`
- /// brings the pending handoff in as context. When the community
+ /// turn boundary, `on_session_finalize`); each primary-session
+ /// `pre_llm_call` can bring a pending handoff into the upcoming turn,
+ /// including after resuming an old native session. When the community
/// memory-provider plugin is installed under `$HERMES_HOME/plugins`, only
/// the tool events are wired, since the plugin owns the rest.
/// `~/.hermes/config.yaml` is NOT written: it is YAML the installer would
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index c904b1bb..e043c9a0 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -992,7 +992,7 @@ fn session_start_handoff_envelope(agent: AgentKind, handoff: String) -> serde_js
/// Hermes adds a hook's stdout to the turn only as a JSON object whose
/// `context` is a non-blank string (`_parse_context` in
/// `agent/shell_hooks.py`); plain text and every other key are dropped.
-fn first_prompt_context_envelope(handoff: String) -> serde_json::Value {
+fn hermes_prompt_context_envelope(handoff: String) -> serde_json::Value {
serde_json::json!({ "context": handoff })
}
@@ -1117,10 +1117,10 @@ where
let delivers_context = (hook_event == HookEvent::SessionStart
&& agent_kind.session_start_injects_handoff())
|| (hook_event == HookEvent::UserPrompt && agent_kind.user_prompt_injects_handoff())
- // Hermes takes the handoff on a session's first prompt; which prompt
- // that is shows only in the payload, read below.
+ // Hermes adds a JSON `context` response from every primary-session
+ // pre_llm_call to the upcoming turn.
|| (hook_event == HookEvent::UserPrompt
- && agent_kind.first_user_prompt_injects_handoff())
+ && agent_kind.json_context_user_prompt_injects_handoff())
// Grok delivers the handoff on the first PostToolUse (its SessionStart /
// UserPromptSubmit stdout is discarded); that path is context delivery
// too, so external capture must not suppress it.
@@ -1168,10 +1168,10 @@ where
.then(|| json.get("profile").and_then(serde_json::Value::as_str))
.flatten()
.map(str::to_owned);
- let first_prompt_of_session = hook_event == HookEvent::UserPrompt
- && agent_kind.first_user_prompt_injects_handoff()
- && !hermes_delegated_child
- && ai_memory_hooks::hermes_is_first_turn(&json);
+ let hermes_user_prompt = hook_event == HookEvent::UserPrompt
+ && agent_kind.json_context_user_prompt_injects_handoff()
+ && !hermes_delegated_child;
+ let hermes_first_prompt = hermes_user_prompt && ai_memory_hooks::hermes_is_first_turn(&json);
if agent_kind == AgentKind::Hermes
&& ai_memory_hooks::shape_hermes_lifecycle_body(&mut json, hook_event)
{
@@ -1787,11 +1787,13 @@ where
return Ok(());
}
- // user-prompt: Hermes ignores `on_session_start` stdout, so the handoff
- // rides the session's first `pre_llm_call` instead, the only turn that
- // claims one. Later turns print `{}` without a fetch, so the turn is never
- // held for it, and a handoff written mid-session stays for the next one.
- if first_prompt_of_session && handoff_scoped {
+ // user-prompt: Hermes ignores `on_session_start` stdout, but adds a
+ // `pre_llm_call` JSON `context` to the upcoming turn. Check every primary
+ // prompt so a resumed native session can receive a handoff produced while
+ // another harness was active. Only a genuinely new session asks for the
+ // startup briefing/profile digest; later or resumed prompts request an
+ // already-open handoff only.
+ if hermes_user_prompt && handoff_scoped {
let client = build_client();
let bearer = hook_spool::resolve_bearer(&client, &dd, effective_token).await;
let native_session_qs = canonical_session_id
@@ -1799,14 +1801,32 @@ where
.map_or_else(String::new, |session_id| {
format!("&session_id={}", url_encode(session_id))
});
+ let handoff_qs = if hermes_first_prompt {
+ qs.clone()
+ } else {
+ policy_cwd
+ .as_deref()
+ .map(|cwd| {
+ marker_query_suffix_without_briefing(
+ cwd,
+ args.project_strategy.and_then(|s| s.baked()),
+ )
+ })
+ .unwrap_or_default()
+ };
+ let profile_qs = if hermes_first_prompt {
+ ""
+ } else {
+ "&profile_digest=0"
+ };
let handoff_url = format!(
- "{base}/handoff?agent={}{qs}{managed_qs}{native_session_qs}",
+ "{base}/handoff?agent={}{handoff_qs}{managed_qs}{native_session_qs}{profile_qs}",
args.agent
);
if let Some(handoff) =
get_handoff(&client, &handoff_url, bearer.as_deref(), handoff_timeout()).await
{
- writeln!(stdout, "{}", first_prompt_context_envelope(handoff))?;
+ writeln!(stdout, "{}", hermes_prompt_context_envelope(handoff))?;
return Ok(());
}
}
@@ -8240,10 +8260,10 @@ mod tests {
}
}
- /// The first `pre_llm_call` of a session claims the handoff and prints the
- /// one shape Hermes adds to the turn: `{"context": "..."}`.
+ /// A `pre_llm_call` claims the handoff and prints the one shape Hermes
+ /// adds to the turn: `{"context": "..."}`.
#[tokio::test]
- async fn hermes_first_prompt_prints_the_handoff_as_context() {
+ async fn hermes_prompt_prints_the_handoff_as_context() {
let tmp = tempfile::tempdir().unwrap();
let data_dir = tmp.path().join("data");
let (base, mut requests) = serve_requests("200 OK", "HERMES-HANDOFF").await;
@@ -8283,10 +8303,10 @@ mod tests {
assert!(!entries[0].body.contains("conversation_history"));
}
- /// No pending handoff on the first prompt: `{}`, which Hermes reads as
- /// "no context", never a bare body or an empty `context`.
+ /// No pending handoff: `{}`, which Hermes reads as "no context", never a
+ /// bare body or an empty `context`.
#[tokio::test]
- async fn hermes_first_prompt_without_a_handoff_prints_an_empty_object() {
+ async fn hermes_prompt_without_a_handoff_prints_an_empty_object() {
let tmp = tempfile::tempdir().unwrap();
let (base, mut requests) = serve_requests("404 Not Found", "").await;
let stdout = run_hermes(
@@ -8301,19 +8321,38 @@ mod tests {
assert!(request.starts_with("GET /handoff?"), "{request}");
}
- /// `GET /handoff` claims the baton. A later turn, `on_session_start`
- /// (whose stdout Hermes ignores) and the turn and session ends must never
- /// send it, or the handoff would be consumed where nobody sees it.
+ /// A resumed Hermes session has history, so `is_first_turn` is false. It
+ /// still checks for a handoff produced by the harness that ran in between,
+ /// but suppresses first-turn briefing and profile composition.
#[tokio::test]
- async fn hermes_never_claims_the_handoff_outside_the_first_prompt() {
+ async fn hermes_resumed_prompt_claims_a_handoff_without_startup_context() {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path().join("data");
+ let (base, mut requests) = serve_requests("200 OK", "HERMES-HANDOFF").await;
+ write_briefing_marker(tmp.path());
+ let stdout = run_hermes(
+ &data_dir,
+ hermes_args("user-prompt-submit", &base),
+ hermes_payload("pre_llm_call", tmp.path(), pre_llm_call_extra(false)),
+ RuntimeEnv::default(),
+ )
+ .await;
+ assert_eq!(stdout, b"{\"context\":\"HERMES-HANDOFF\"}\n");
+ let request = first_request(&mut requests).await.unwrap();
+ assert!(request.starts_with("GET /handoff?"), "{request}");
+ assert!(request.contains("session_id=hermes-session"), "{request}");
+ assert!(request.contains("profile_digest=0"), "{request}");
+ assert!(!request.contains("briefing"), "{request}");
+ }
+
+ /// `on_session_start` stdout is ignored, while the turn and session ends
+ /// are not context channels. None may claim a handoff.
+ #[tokio::test]
+ async fn hermes_never_claims_the_handoff_outside_a_primary_prompt() {
let tmp = tempfile::tempdir().unwrap();
let data_dir = tmp.path().join("data");
let (base, mut requests) = serve_requests("200 OK", "HERMES-HANDOFF").await;
for (event, payload) in [
- (
- "user-prompt-submit",
- hermes_payload("pre_llm_call", tmp.path(), pre_llm_call_extra(false)),
- ),
(
"session-start",
hermes_payload(
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 95373939..ca44be44 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -7167,7 +7167,8 @@ pub(crate) fn hermes_hook_set_notes(hook_set: HermesHookSet, plugin_dir: Option<
HermesHookSet::Full => format!(
"# NOTE: tool events plus the session lifecycle. pre_llm_call\n\
# captures each prompt and brings the pending handoff into\n\
- # the session's first turn; on_session_end marks a turn\n\
+ # the next turn, including after a resumed native session;\n\
+ # on_session_end marks a turn\n\
# (Hermes fires it after every turn) and on_session_finalize\n\
# ends the session.\n\
# NOTE: a gateway session that expires idle is never finalized;\n\
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index db27692d..b343b3a9 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -2511,7 +2511,7 @@ fn render_hermes(args: &InstallMcpArgs) -> String {
# rules reach the model through the ai-memory skills\n\
# (`ai-memory install-skills --scope global --agent hermes`, into\n\
# ~/.hermes/skills) and the handoff `install-hooks --agent hermes`\n\
- # brings into a session's first turn.\n\
+ # brings into the next primary-session turn.\n\
{token_note}\
{snippet}\n",
snippet = render_hermes_snippet(args),
@@ -3634,7 +3634,7 @@ mod tests {
// header points at what carries them instead.
assert!(rendered.contains("does not read an MCP server's instructions"));
assert!(rendered.contains("~/.hermes/skills"));
- assert!(rendered.contains("first turn"));
+ assert!(rendered.contains("next primary-session turn"));
}
/// No bearer reaches Hermes' config: the bridge authenticates with the
diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rs
index 80819071..557134cc 100644
--- a/crates/ai-memory-cli/src/commands/render_shared.rs
+++ b/crates/ai-memory-cli/src/commands/render_shared.rs
@@ -1040,8 +1040,8 @@ pub(crate) const HERMES_TOOL_EVENTS: [(&str, &str); 2] = [
/// its stdout, so it only records the start; the handoff is never fetched
/// there, because that fetch claims it.
/// - `pre_llm_call` fires before every turn with the prompt in
-/// `extra.user_message`. On the session's first turn its
-/// `{"context": ...}` stdout carries the handoff into the turn.
+/// `extra.user_message`. Its `{"context": ...}` stdout carries any pending
+/// handoff into the turn, including after a native Hermes session resumes.
/// - `on_session_end` fires at the end of **every turn**, not of the session,
/// so it is a turn boundary (`stop`).
/// - `on_session_finalize` is the real end: CLI exit, `/new`, gateway
@@ -1070,7 +1070,7 @@ pub(crate) enum HermesHookSet {
}
/// Wall-clock bound written into each Hermes hook entry. Capture POSTs are
-/// fire-and-forget and the first-turn handoff fetch has its own short
+/// fire-and-forget and the prompt-time handoff fetch has its own short
/// timeout, so this only bounds a hung `hook` invocation. Hermes bounds a
/// blocking hook's callback at 30 s by default, and `pre_llm_call` holds
/// the turn while it runs, so the entry stays well under that.
diff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rs
index 299a786b..80ad27d8 100644
--- a/crates/ai-memory-core/src/ids.rs
+++ b/crates/ai-memory-core/src/ids.rs
@@ -518,18 +518,17 @@ impl AgentKind {
matches!(self, Self::KimiCode)
}
- /// Whether this agent adds the native `user-prompt` hook's stdout to the
- /// turn only on the first prompt of a session, which the payload itself
- /// marks.
+ /// Whether this agent adds a JSON `context` from the native `user-prompt`
+ /// hook's stdout to the upcoming turn.
///
/// Hermes Agent ignores `on_session_start` stdout but adds a
/// `pre_llm_call` hook's `{"context": "..."}` to the user message, and
- /// flags the session's first turn with `extra.is_first_turn`
- /// (`agent/turn_context.py`, `agent/shell_hooks.py`, v0.22.2). The
- /// handoff is claimed on that turn alone: `pre_llm_call` holds every turn
- /// while it runs, so later turns skip the round-trip.
+ /// (`agent/turn_context.py`, `agent/shell_hooks.py`, v0.22.2). The hook
+ /// checks every primary-session prompt: a resumed Hermes session reports
+ /// `extra.is_first_turn = false`, but still needs to receive a handoff
+ /// produced while another harness was active.
#[must_use]
- pub fn first_user_prompt_injects_handoff(self) -> bool {
+ pub fn json_context_user_prompt_injects_handoff(self) -> bool {
matches!(self, Self::Hermes)
}
@@ -699,7 +698,7 @@ mod tests {
}
#[test]
- fn agent_kind_hermes_round_trips_and_claims_the_handoff_on_the_first_prompt_only() {
+ fn agent_kind_hermes_round_trips_and_claims_handoffs_on_user_prompts() {
assert_eq!(AgentKind::Hermes.as_str(), "hermes");
assert_eq!(AgentKind::from_wire("hermes"), AgentKind::Hermes);
assert_eq!(AgentKind::from_wire("hermes-agent"), AgentKind::Hermes);
@@ -712,13 +711,16 @@ mod tests {
"\"hermes\""
);
// `on_session_start` stdout is ignored, so the destructive fetch must
- // not run there; the first `pre_llm_call` carries it instead.
+ // not run there; a primary-session `pre_llm_call` carries it instead.
assert!(!AgentKind::Hermes.session_start_injects_handoff());
assert!(!AgentKind::Hermes.user_prompt_injects_handoff());
- assert!(AgentKind::Hermes.first_user_prompt_injects_handoff());
+ assert!(AgentKind::Hermes.json_context_user_prompt_injects_handoff());
for other in AgentKind::ALL {
if other != AgentKind::Hermes {
- assert!(!other.first_user_prompt_injects_handoff(), "{other:?}");
+ assert!(
+ !other.json_context_user_prompt_injects_handoff(),
+ "{other:?}"
+ );
}
}
}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 7a6941ab..5610ea8f 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -420,9 +420,11 @@ 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. A `delegate_task` child (`extra.platform` `subagent`;
+handoff is checked on every primary-session `pre_llm_call` and printed as
+`{"context": ...}`, the one stdout shape Hermes adds to a turn. This lets a
+resumed native Hermes session receive a handoff produced by another harness;
+`extra.is_first_turn` only gates startup briefing/profile composition. A
+`delegate_task` child (`extra.platform` `subagent`;
Hermes never sends its `parent_session_id`) also starts with an empty history,
so its lifecycle events are dropped before any spool or handoff request.
diff --git a/docs/install.md b/docs/install.md
index 2e4a9b01..f2f72b71 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -2029,7 +2029,7 @@ Six events are wired, each with a 20-second timeout:
| --- | --- | --- |
| `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. |
+| `pre_llm_call` | `user-prompt-submit` | Captures the prompt from `extra.user_message` (text parts only, never the conversation history). On every primary-session turn it checks for a pending handoff and prints it as `{"context": "..."}`, which Hermes adds to that turn. This also works after a native Hermes session resumes. |
| `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. |
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 31fa70c3..aaef8f8e 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -124,8 +124,9 @@ 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
+`pre_llm_call` (the prompt, plus any pending handoff as `{"context": ...}` on
+the next primary-session turn, including after a native resume),
+`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)
@@ -140,7 +141,7 @@ 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.
+in the next primary-session turn.
The community-maintained
[`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin)
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 23bd9a08..6da0d8db 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; `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 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 (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; `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. |
| 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). |