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.mdindex 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 nowalso wires `on_session_start`, `pre_llm_call` (the prompt, never theconversation 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. Hermesevents route by `TERMINAL_CWD` when it names an existing directory (in agateway, for the default profile only), and a delegated child's lifecycleevents are dropped. When thediff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 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 woulddiff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 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 @@ wherelet 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 @@ wherereturn 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.rsindex 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.rsindex 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 thediff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rsindex 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.rsindex 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.mdindex 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 conversationhistory, `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.mdindex 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.mdindex 31fa70c3..aaef8f8e 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -124,8 +124,9 @@ ai-memory install-skills --scope global --agent hermesThe hooks block runs the native `ai-memory hook` command in exec form, sinceHermes splits each `command` with `shlex.split` and runs it with no shell. Itwires 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 firesit after every turn) and `on_session_finalize` (the session end). Hermes gatesuser hooks behind its own acceptance prompt (`hooks_auto_accept`), so paste theblock 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 themodel passes `workspace` and `project` on project-scoped calls. `--apply` isrefused. Hermes does not read MCP server instructions, so the routing rulesreach 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.mdindex 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). |