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.mdindex 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. Proxyrequests must assert either a username or the complete OIDC issuer/subjectdiff --git a/README.md b/README.mdindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.sqlnew file mode 100644index 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.rsindex 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.mdindex 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 settingsshould stay in environment or local config references rather than generatedplugin 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 externalbridge: map known events onto ai-memory's canonical hook events wherepossible, and use extension metadata for source-specific events instead of