Skip to content

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

Rust

feat(hooks): recognize Hermes agent protocol

AkitaOnRails7a94b44f219d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7c57593..344e4454 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- Hook ingestion now recognizes Hermes Agent as a concrete session kind and
+ understands its documented shell-hook `tool_name` / `tool_input` envelope
+ for bounded tool-family titles and capture exclusions. Migration V44 expands
+ the session allowlist without losing session ownership, observation
+ watermarks, indexes, or scope-pairing triggers. This remains protocol support,
+ not a first-party Hermes installer, and session-start handoff acceptance stays
+ disabled because Hermes ignores that hook's stdout (#337).
- Trusted-proxy identity now has a dedicated
`[auth].actor_proxy_bearer_token`, distinct from the root bearer. Proxy
requests must assert either a username or the complete OIDC issuer/subject
diff --git a/README.md b/README.md
index dd988bec..c18dfcbf 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@
| Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `UserPromptSubmit` stdout (Kimi Code discards `SessionStart` hook stdout); `ai-memory run kimi` adds managed workstream resume. |
| 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. |
-| Hermes Agent | Community | A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available. It is not part of ai-memory's first-party install surface; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. |
+| 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. |
| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode Zen/Go, 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. |
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 360de879..0fe8768e 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -1488,6 +1488,48 @@ mod tests {
assert_eq!(hook_spool::spool_len(&hook_spool::spool_dir(&data_dir)), 0);
}
+ #[tokio::test]
+ async fn hermes_file_exclusion_drops_before_spool_or_drain() {
+ let tmp = tempfile::tempdir().unwrap();
+ std::fs::write(
+ tmp.path().join(".ai-memory.toml"),
+ "[capture]\nignore_paths = [\"secret/**\"]\n",
+ )
+ .unwrap();
+ let data_dir = tmp.path().join("data");
+ let mut stdout = Vec::new();
+ let called = std::cell::Cell::new(false);
+ let mut args = devin_hook_args("post-tool-use");
+ args.agent = "hermes".into();
+ let raw = serde_json::json!({
+ "hook_event_name": "post_tool_call",
+ "tool_name": "write_file",
+ "tool_input": {
+ "path": "secret/token.txt",
+ "content": "SENTINEL_MUST_NOT_BE_SPOOLED"
+ },
+ "session_id": "hermes-session",
+ "cwd": tmp.path(),
+ "extra": {"tool_call_id": "call-42", "status": "ok"}
+ });
+ run_with_payload(
+ Some(data_dir.clone()),
+ args,
+ raw.to_string(),
+ &mut stdout,
+ |_| {
+ called.set(true);
+ Ok(())
+ },
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(stdout, b"{}\n");
+ assert!(!called.get());
+ assert_eq!(hook_spool::spool_len(&hook_spool::spool_dir(&data_dir)), 0);
+ }
+
#[cfg(unix)]
#[tokio::test]
async fn capture_drop_handles_symlinked_cwd() {
diff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rs
index 8f5dbbee..6bc7b7f2 100644
--- a/crates/ai-memory-core/src/ids.rs
+++ b/crates/ai-memory-core/src/ids.rs
@@ -210,6 +210,8 @@ pub enum AgentKind {
Devin,
/// Kimi Code CLI (Moonshot AI).
KimiCode,
+ /// Hermes Agent (Nous Research).
+ Hermes,
/// Anything else (manual capture, future agents).
Other,
}
@@ -220,7 +222,7 @@ impl AgentKind {
/// CHECK constraint accepts every kind (the Zero integration shipped
/// with the enum variant but without the V26 migration and only a
/// live test caught it). Extend together with the enum.
- pub const ALL: [Self; 16] = [
+ pub const ALL: [Self; 17] = [
Self::ClaudeCode,
Self::Codex,
Self::OpenCode,
@@ -236,6 +238,7 @@ impl AgentKind {
Self::Zero,
Self::Devin,
Self::KimiCode,
+ Self::Hermes,
Self::Other,
];
@@ -258,6 +261,7 @@ impl AgentKind {
Self::Zero => "zero",
Self::Devin => "devin",
Self::KimiCode => "kimi-code",
+ Self::Hermes => "hermes",
Self::Other => "other",
}
}
@@ -283,6 +287,7 @@ impl AgentKind {
"zero" => Self::Zero,
"devin" => Self::Devin,
"kimi-code" | "kimi" => Self::KimiCode,
+ "hermes" | "hermes-agent" => Self::Hermes,
_ => Self::Other,
}
}
@@ -312,7 +317,7 @@ impl AgentKind {
pub fn session_start_injects_handoff(self) -> bool {
!matches!(
self,
- Self::Crush | Self::Grok | Self::Zero | Self::KimiCode | Self::Other
+ Self::Crush | Self::Grok | Self::Zero | Self::KimiCode | Self::Hermes | Self::Other
)
}
@@ -418,6 +423,23 @@ mod tests {
assert!(AgentKind::KimiCode.user_prompt_injects_handoff());
}
+ #[test]
+ fn agent_kind_hermes_round_trips_without_claiming_handoff_delivery() {
+ assert_eq!(AgentKind::Hermes.as_str(), "hermes");
+ assert_eq!(AgentKind::from_wire("hermes"), AgentKind::Hermes);
+ assert_eq!(AgentKind::from_wire("hermes-agent"), AgentKind::Hermes);
+ assert_eq!(
+ serde_json::from_str::<AgentKind>("\"hermes\"").unwrap(),
+ AgentKind::Hermes
+ );
+ assert_eq!(
+ serde_json::to_string(&AgentKind::Hermes).unwrap(),
+ "\"hermes\""
+ );
+ assert!(!AgentKind::Hermes.session_start_injects_handoff());
+ assert!(!AgentKind::Hermes.user_prompt_injects_handoff());
+ }
+
#[test]
fn user_prompt_handoff_injection_is_kimi_only() {
for agent in AgentKind::ALL {
diff --git a/crates/ai-memory-hooks/src/capture_policy.rs b/crates/ai-memory-hooks/src/capture_policy.rs
index 47c4ce9e..c8af4d50 100644
--- a/crates/ai-memory-hooks/src/capture_policy.rs
+++ b/crates/ai-memory-hooks/src/capture_policy.rs
@@ -139,6 +139,14 @@ pub(crate) fn tool_observation_metadata(
object.get("callID").and_then(Value::as_str),
),
AgentKind::AntigravityCli => (object.get("toolCall")?.get("name")?.as_str()?, None),
+ AgentKind::Hermes => (
+ object.get("tool_name")?.as_str()?,
+ object
+ .get("extra")
+ .and_then(Value::as_object)
+ .and_then(|extra| extra.get("tool_call_id"))
+ .and_then(Value::as_str),
+ ),
_ => return None,
};
// PreToolUse needs a proven input shape. PostToolUse deliberately does
@@ -147,11 +155,13 @@ pub(crate) fn tool_observation_metadata(
|| match agent {
AgentKind::AntigravityCli => object.get("toolCall")?.get("args").is_some(),
_ => object
- .get(if agent == AgentKind::ClaudeCode {
- "tool_input"
- } else {
- "args"
- })
+ .get(
+ if matches!(agent, AgentKind::ClaudeCode | AgentKind::Hermes) {
+ "tool_input"
+ } else {
+ "args"
+ },
+ )
.is_some(),
};
has_args.then(|| ToolObservationMetadata {
@@ -507,7 +517,8 @@ fn extract(agent: AgentKind, raw: &Value) -> Extracted {
| AgentKind::Codex
| AgentKind::Cursor
| AgentKind::GeminiCli
- | AgentKind::Devin => object
+ | AgentKind::Devin
+ | AgentKind::Hermes => object
.get("tool_name")
.and_then(Value::as_str)
.map(|name| (name, object.get("tool_input"))),
@@ -574,9 +585,12 @@ fn family(name: &str) -> ToolFamily {
| "replace_file_content"
| "multi_replace_file_content"
| "write_to_file" => ToolFamily::File,
+ "read_file" | "write_file" | "patch" => ToolFamily::File,
"search" | "grep" | "glob" | "find" | "list" | "ls" | "list_files" | "read_dir"
- | "list_dir" | "grep_search" => ToolFamily::SearchList,
- "bash" | "shell" | "execute" | "run_command" | "web_search" => ToolFamily::NonFile,
+ | "list_dir" | "grep_search" | "search_files" => ToolFamily::SearchList,
+ "bash" | "shell" | "execute" | "run_command" | "web_search" | "terminal" => {
+ ToolFamily::NonFile
+ }
_ => ToolFamily::Unknown,
}
}
@@ -984,6 +998,53 @@ mod tests {
.insert("paths".into(), json!(["x"]));
assert!(CaptureProtocol::parse(&bad).is_none());
}
+
+ #[test]
+ fn hermes_official_tool_shape_is_closed_and_honors_exclusions() {
+ let raw = json!({
+ "hook_event_name": "post_tool_call",
+ "tool_name": "write_file",
+ "tool_input": {"path": "secret/token.txt", "content": "do not retain"},
+ "session_id": "hermes-session",
+ "cwd": "/repo",
+ "extra": {"tool_call_id": "call-42", "status": "ok"}
+ });
+ let metadata = tool_observation_metadata(AgentKind::Hermes, &raw, false).unwrap();
+ assert_eq!(metadata.tool_family, ToolFamily::File);
+ assert_eq!(metadata.tool_call_id.as_deref(), Some("call-42"));
+
+ let policy = CapturePolicy::resolve(
+ CaptureSource::Parsed(&CaptureConfig {
+ ignore_paths: vec!["secret/**".into()],
+ }),
+ "/repo",
+ None,
+ );
+ let decision = policy.inspect(AgentKind::Hermes, &raw, "/repo");
+ assert_eq!(decision.protocol().tool_family(), ToolFamily::File);
+ assert_eq!(decision.protocol().disposition(), CaptureDisposition::Drop);
+
+ let unknown = policy.inspect(AgentKind::Other, &raw, "/repo");
+ assert_eq!(
+ unknown.protocol().extraction_state(),
+ ExtractionState::UnsupportedSchema
+ );
+ assert_eq!(unknown.protocol().tool_family(), ToolFamily::Unknown);
+ }
+
+ #[test]
+ fn hermes_documented_tool_names_map_to_canonical_families() {
+ for (tool, expected) in [
+ ("read_file", ToolFamily::File),
+ ("write_file", ToolFamily::File),
+ ("patch", ToolFamily::File),
+ ("search_files", ToolFamily::SearchList),
+ ("terminal", ToolFamily::NonFile),
+ ] {
+ assert_eq!(family(tool), expected, "tool: {tool}");
+ }
+ }
+
#[test]
fn antigravity_native_tools_are_no_longer_unknown() {
for (tool, expected) in [
diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rs
index 48b1670f..3eb05a53 100644
--- a/crates/ai-memory-hooks/src/payload.rs
+++ b/crates/ai-memory-hooks/src/payload.rs
@@ -511,7 +511,11 @@ fn legacy_tool_body(event: HookEvent, agent: AgentKind, raw: &serde_json::Value)
const fn closed_tool_agent(agent: AgentKind) -> bool {
matches!(
agent,
- AgentKind::ClaudeCode | AgentKind::OpenCode | AgentKind::Pi | AgentKind::AntigravityCli
+ AgentKind::ClaudeCode
+ | AgentKind::OpenCode
+ | AgentKind::Pi
+ | AgentKind::AntigravityCli
+ | AgentKind::Hermes
)
}
@@ -1411,6 +1415,8 @@ mod tests {
assert_eq!(parse_agent("omp"), AgentKind::Omp);
assert_eq!(parse_agent("pi"), AgentKind::Pi);
assert_eq!(parse_agent("oh-my-pi"), AgentKind::Omp);
+ assert_eq!(parse_agent("hermes"), AgentKind::Hermes);
+ assert_eq!(parse_agent("hermes-agent"), AgentKind::Hermes);
// Anything else is `Other`. Critical for the hook router:
// a typo in the query string must not crash, it just gets
// attributed to the catch-all bucket.
@@ -1437,6 +1443,41 @@ mod tests {
assert!(env.body_excerpt.is_none());
}
+ #[test]
+ fn hermes_tool_title_uses_only_the_verified_shell_hook_shape() {
+ let raw = serde_json::json!({
+ "hook_event_name": "post_tool_call",
+ "tool_name": "write_file",
+ "tool_input": {"path": "src/lib.rs", "content": "untrusted"},
+ "session_id": "hermes-session",
+ "cwd": "/repo",
+ "extra": {"tool_call_id": "call-42", "status": "ok"}
+ });
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "post-tool-use".into(),
+ agent: Some("hermes".into()),
+ ..Default::default()
+ },
+ raw.clone(),
+ );
+ assert_eq!(env.agent, AgentKind::Hermes);
+ assert_eq!(env.title_hint.as_deref(), Some("tool file"));
+ assert_eq!(env.session_id.as_deref(), Some("hermes-session"));
+ assert_eq!(env.cwd.as_deref(), Some("/repo"));
+
+ let unknown = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "post-tool-use".into(),
+ agent: Some("unverified-agent".into()),
+ ..Default::default()
+ },
+ raw,
+ );
+ assert_eq!(unknown.agent, AgentKind::Other);
+ assert!(unknown.title_hint.is_none());
+ }
+
/// Body is well-formed JSON but the expected `session_id` /
/// `cwd` keys are missing — extraction returns None per key.
#[test]
diff --git a/crates/ai-memory-store/migrations/V44__sessions_hermes_agent_kind.sql b/crates/ai-memory-store/migrations/V44__sessions_hermes_agent_kind.sql
new file mode 100644
index 00000000..13bd2827
--- /dev/null
+++ b/crates/ai-memory-store/migrations/V44__sessions_hermes_agent_kind.sql
@@ -0,0 +1,75 @@
+-- Expand sessions.agent_kind CHECK for Hermes Agent.
+--
+-- The official Hermes shell-hook protocol identifies the agent separately
+-- from ai-memory's third-party installer surface. Rebuilding this table must
+-- retain the V35 observation watermark, V40 owner, every current index, and
+-- every trigger that validates a child row against its session scope.
+
+PRAGMA foreign_keys = OFF;
+
+DROP TRIGGER IF EXISTS auto_improve_scheduler_claims_session_pairing_ai;
+DROP TRIGGER IF EXISTS session_consolidation_jobs_session_pairing_ai;
+
+CREATE TABLE sessions_new (
+ id BLOB PRIMARY KEY NOT NULL,
+ workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+ project_id BLOB NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+ agent_kind TEXT NOT NULL CHECK (agent_kind IN ('claude-code','codex','open-code','cursor','gemini-cli','claude-desktop','openclaw','antigravity-cli','omp','pi','crush','grok','zero','devin','kimi-code','hermes','other')),
+ cwd TEXT,
+ started_at INTEGER NOT NULL,
+ ended_at INTEGER,
+ summary_page_id BLOB REFERENCES pages(id) ON DELETE SET NULL,
+ ended_observation_count INTEGER NOT NULL DEFAULT 0 CHECK (ended_observation_count >= 0),
+ actor_user TEXT
+);
+
+INSERT INTO sessions_new (
+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,
+ summary_page_id, ended_observation_count, actor_user
+)
+SELECT
+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,
+ summary_page_id, ended_observation_count, actor_user
+FROM sessions;
+
+DROP TABLE sessions;
+
+ALTER TABLE sessions_new RENAME TO sessions;
+
+CREATE INDEX idx_sessions_recent ON sessions(workspace_id, project_id, started_at DESC);
+CREATE INDEX idx_sessions_project ON sessions(project_id);
+CREATE INDEX idx_sessions_started_at ON sessions(started_at DESC);
+CREATE INDEX idx_sessions_scope_ended
+ ON sessions(workspace_id, project_id, ended_at ASC)
+ WHERE ended_at IS NOT NULL;
+CREATE INDEX idx_sessions_open_owner
+ ON sessions(workspace_id, project_id, agent_kind, actor_user)
+ WHERE ended_at IS NULL;
+
+CREATE TRIGGER sessions_ws_proj_pairing_ai
+BEFORE INSERT ON sessions
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM projects WHERE id = NEW.project_id)
+BEGIN
+ SELECT RAISE(ABORT, 'sessions.workspace_id does not match the project''s workspace');
+END;
+
+CREATE TRIGGER auto_improve_scheduler_claims_session_pairing_ai
+BEFORE INSERT ON auto_improve_scheduler_claims
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)
+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)
+BEGIN
+ SELECT RAISE(ABORT, 'auto_improve_scheduler_claims scope does not match the session scope');
+END;
+
+CREATE TRIGGER session_consolidation_jobs_session_pairing_ai
+BEFORE INSERT ON session_consolidation_jobs
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)
+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)
+BEGIN
+ SELECT RAISE(ABORT, 'session_consolidation_jobs scope does not match the session scope');
+END;
+
+PRAGMA foreign_keys = ON;
diff --git a/crates/ai-memory-store/src/migrations.rs b/crates/ai-memory-store/src/migrations.rs
index 250e0940..58f0df8c 100644
--- a/crates/ai-memory-store/src/migrations.rs
+++ b/crates/ai-memory-store/src/migrations.rs
@@ -52,7 +52,9 @@ pub(crate) fn run_to(conn: &mut rusqlite::Connection, target: u32) -> Result<(),
#[cfg(test)]
mod tests {
use super::*;
- use ai_memory_core::{AgentKind, HandoffId, NewObservation, ObservationKind, SessionId};
+ use ai_memory_core::{
+ AgentKind, HandoffId, NewObservation, NewSession, ObservationKind, SessionId,
+ };
use rusqlite::{Connection, params};
/// A store migrated by a newer build (an applied version above anything
@@ -502,4 +504,88 @@ mod tests {
);
}
}
+
+ #[test]
+ fn v43_to_v44_preserves_session_state_and_all_scope_guards() {
+ let mut conn = Connection::open_in_memory().unwrap();
+ run_to(&mut conn, 43).unwrap();
+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();
+ let workspace_id = crate::ops::get_or_create_workspace(&mut conn, "default").unwrap();
+ let project_id =
+ crate::ops::get_or_create_project(&mut conn, &workspace_id, "project", None).unwrap();
+ let existing = SessionId::new();
+ conn.execute(
+ "INSERT INTO sessions \
+ (id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at, \
+ ended_observation_count, actor_user) \
+ VALUES (?1, ?2, ?3, 'codex', '/repo', 1, 2, 7, 'user:alice')",
+ params![
+ existing.as_bytes(),
+ workspace_id.as_bytes(),
+ project_id.as_bytes(),
+ ],
+ )
+ .unwrap();
+
+ conn.pragma_update(None, "foreign_keys", "OFF").unwrap();
+ run(&mut conn).unwrap();
+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();
+
+ let preserved: (String, String, i64, Option<String>) = conn
+ .query_row(
+ "SELECT agent_kind, cwd, ended_observation_count, actor_user \
+ FROM sessions WHERE id = ?1",
+ params![existing.as_bytes()],
+ |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)),
+ )
+ .unwrap();
+ assert_eq!(
+ preserved,
+ ("codex".into(), "/repo".into(), 7, Some("user:alice".into()))
+ );
+
+ for index in [
+ "idx_sessions_recent",
+ "idx_sessions_project",
+ "idx_sessions_started_at",
+ "idx_sessions_scope_ended",
+ "idx_sessions_open_owner",
+ ] {
+ assert_eq!(
+ schema_object_count(&conn, "index", index),
+ 1,
+ "V44 dropped session index {index}"
+ );
+ }
+ for trigger in [
+ "sessions_ws_proj_pairing_ai",
+ "auto_improve_scheduler_claims_session_pairing_ai",
+ "session_consolidation_jobs_session_pairing_ai",
+ ] {
+ assert_eq!(
+ schema_object_count(&conn, "trigger", trigger),
+ 1,
+ "V44 dropped scope guard {trigger}"
+ );
+ }
+ let foreign_key_errors: i64 = conn
+ .query_row("SELECT COUNT(*) FROM pragma_foreign_key_check", [], |row| {
+ row.get(0)
+ })
+ .unwrap();
+ assert_eq!(foreign_key_errors, 0);
+
+ crate::ops::begin_session(
+ &mut conn,
+ &NewSession {
+ id: SessionId::new(),
+ workspace_id,
+ project_id,
+ agent_kind: AgentKind::Hermes,
+ cwd: Some("/repo".into()),
+ actor_user: Some("user:alice".into()),
+ },
+ )
+ .unwrap();
+ }
}
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index da1a99e4..1dead391 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -77,6 +77,15 @@ 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
+accepts Hermes' documented shell-hook `tool_name` / `tool_input` envelope for
+tool-family metadata and capture-exclusion enforcement. A custom bridge should
+map `on_session_start`, `post_tool_call`, and `on_session_end` to ai-memory's
+canonical `session-start`, `post-tool-use`, and `session-end` event names while
+forwarding the original JSON object. This protocol recognition does not install
+or trust a third-party plugin. Hermes ignores session-start hook stdout, so it
+cannot consume an automatic handoff there; use MCP `memory_handoff_accept`.
+
The same lifecycle guidance below applies to Hermes or any other external
bridge: map known events onto ai-memory's canonical hook events where
possible, and use extension metadata for source-specific events instead of