Skip to content

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

Rust

feat(hermes): add an install-mcp client

4nrry54b48a5f94ab
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 93d8b2d7..b2000c1e 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -2852,6 +2852,14 @@ pub enum McpClient {
/// installed separately with `install-hooks --agent dsh`.
#[value(alias = "deepseek-harness", alias = "deepseek_harness")]
Dsh,
+ /// Hermes Agent (Nous Research) — the `mcp_servers:` map of
+ /// `~/.hermes/config.yaml`. Print-only (--apply is refused): ai-memory has
+ /// no YAML editor for that file, which the operator also edits. The entry
+ /// is a stdio `ai-memory mcp-bridge --no-session-id`, so it carries no
+ /// token. Lifecycle capture is installed separately with `install-hooks
+ /// --agent hermes`.
+ #[value(alias = "hermes-agent")]
+ Hermes,
/// Cline CLI — `~/.cline/data/settings/cline_mcp_settings.json` (or
/// `CLINE_MCP_SETTINGS_PATH`) with an explicit Streamable HTTP transport.
#[value(alias = "cline-cli")]
@@ -4815,6 +4823,14 @@ mod tests {
panic!("expected finalize-session for hermes");
};
assert_eq!(args.agent, ai_memory_core::AgentKind::Hermes);
+ for alias in ["hermes", "hermes-agent"] {
+ let mcp = Cli::try_parse_from(["ai-memory", "install-mcp", "--client", alias])
+ .unwrap_or_else(|error| panic!("{alias}: {error}"));
+ let Command::InstallMcp(args) = mcp.command else {
+ panic!("expected install-mcp for Hermes alias {alias}");
+ };
+ assert_eq!(args.client, McpClient::Hermes);
+ }
}
#[test]
diff --git a/crates/ai-memory-cli/src/commands/auth_enable.rs b/crates/ai-memory-cli/src/commands/auth_enable.rs
index ee9b996e..30c48097 100644
--- a/crates/ai-memory-cli/src/commands/auth_enable.rs
+++ b/crates/ai-memory-cli/src/commands/auth_enable.rs
@@ -210,13 +210,15 @@ fn record_token_file(config_path: &Path) -> Result<bool> {
}
/// Clients `install-mcp --apply` writes a config file for. Pi has no MCP
-/// config (its extension reads the hook credential file) and DeepSeek
-/// Harness is print-only, so neither has an entry to re-point.
+/// config (its extension reads the hook credential file), and DeepSeek
+/// Harness and Hermes Agent are print-only, so none has an entry to
+/// re-point. Hermes' entry is a bridge carrying no token, so a new token
+/// needs no edit there either.
fn rewirable_clients() -> impl Iterator<Item = McpClient> {
<McpClient as clap::ValueEnum>::value_variants()
.iter()
.copied()
- .filter(|client| !matches!(client, McpClient::Pi | McpClient::Dsh))
+ .filter(|client| !matches!(client, McpClient::Pi | McpClient::Dsh | McpClient::Hermes))
}
/// The endpoint without a `?flavor=` (or any) query, normalised to `/mcp`.
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index f2559468..e36ea759 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -1717,9 +1717,10 @@ fn infer_installed_mcp_config(
"url",
)),
McpClient::Pi => Ok(None),
- // DeepSeek Harness has no fixed MCP config file; no AgentChoice
- // counterpart routes here, so this arm only satisfies exhaustiveness.
- McpClient::Dsh => Ok(None),
+ // DeepSeek Harness has no fixed MCP config file, and Hermes' is YAML
+ // ai-memory never writes; no AgentChoice counterpart routes either
+ // here, so this arm only satisfies exhaustiveness.
+ McpClient::Dsh | McpClient::Hermes => Ok(None),
McpClient::AntigravityCli => Ok(infer_json_mcp_config(
&content,
&["mcpServers", "ai-memory"],
@@ -1832,8 +1833,9 @@ pub(crate) fn mcp_client_for_agent(agent: AgentChoice) -> Option<McpClient> {
// no `McpClient::Zcode` whose config the installer could scrape a
// server URL or token from.
AgentChoice::Zcode => None,
- // No first-party Hermes MCP installer ships yet, so there is no config
- // file to infer a server URL or token from.
+ // `install-mcp --client hermes` is print-only: ai-memory never writes
+ // `~/.hermes/config.yaml`, so there is no entry of its own to infer a
+ // server URL or token from.
AgentChoice::Hermes => None,
AgentChoice::CopilotCli => Some(McpClient::CopilotCli),
AgentChoice::Droid => Some(McpClient::Droid),
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index 1d052b73..db27692d 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -126,10 +126,15 @@ pub(crate) fn run_with_opencode_dialect(
// Muse starts stdio servers with a cleared environment (`HOME`, `PATH`
// and its own `MUSE_SESSION_ID`), so the bridge it launches finds this
// install's config and token only through an explicit `--data-dir`, as
- // the Muse hooks do. Not from inside the Docker helper, whose data dir is
- // a container path the host-side bridge cannot open.
- if matches!(args.client, McpClient::Muse | McpClient::Freebuff)
- && config.runtime_env.host_cwd().is_none()
+ // the Muse hooks do. Hermes keeps only a short allowlist (`PATH`, `HOME`,
+ // `XDG_*`, ...; `_build_safe_env` in `tools/mcp_tool_config.py`), which
+ // drops `AI_MEMORY_DATA_DIR` the same way. Not from inside the Docker
+ // helper, whose data dir is a container path the host-side bridge cannot
+ // open.
+ if matches!(
+ args.client,
+ McpClient::Muse | McpClient::Freebuff | McpClient::Hermes
+ ) && config.runtime_env.host_cwd().is_none()
{
args.bridge_data_dir = Some(config.data_dir.clone());
}
@@ -169,6 +174,7 @@ pub(crate) fn run_with_opencode_dialect(
McpClient::Zed => render_zed(&args)?,
McpClient::Muse => render_muse(&args)?,
McpClient::Dsh => render_dsh(&args)?,
+ McpClient::Hermes => render_hermes(&args),
McpClient::PrimeAgent => render_prime_agent(&args)?,
McpClient::Cline => render_json_mcp_fragment(&args)?,
McpClient::Freebuff => render_json_mcp_fragment(&args)?,
@@ -656,6 +662,7 @@ pub(crate) fn mcp_config_path_with(
McpClient::Dsh => bail!(
"DeepSeek Harness has no fixed MCP config file; merge the printed snippet into $DSH_HOME/profiles/<profile>/cordis.patch.yml."
),
+ McpClient::Hermes => bail!(HERMES_MCP_APPLY_GUIDANCE),
// OMP reads mcp.json from its agent dir, the one its extensions live
// in, so a profile, PI_CODING_AGENT_DIR or PI_CONFIG_DIR moves it too.
McpClient::Omp => {
@@ -1036,6 +1043,9 @@ fn apply_to_config_file(args: &InstallMcpArgs) -> Result<()> {
if matches!(args.client, McpClient::Dsh) {
bail!(dsh_mcp_apply_guidance(args));
}
+ if matches!(args.client, McpClient::Hermes) {
+ bail!(HERMES_MCP_APPLY_GUIDANCE);
+ }
let path = resolve_config_file(args)?;
let outcome = match args.client {
McpClient::Codex => apply_atomic(&path, |existing| {
@@ -1148,7 +1158,9 @@ fn json_mcp_location(client: McpClient) -> Option<JsonMcpLocation> {
McpClient::VsCodeCopilot => Some(JsonMcpLocation::RootServers),
McpClient::Zed => Some(JsonMcpLocation::RootContextServers),
McpClient::Muse => Some(JsonMcpLocation::MuseServers),
- McpClient::Codex | McpClient::Grok | McpClient::Pi | McpClient::Dsh => None,
+ McpClient::Codex | McpClient::Grok | McpClient::Pi | McpClient::Dsh | McpClient::Hermes => {
+ None
+ }
}
}
@@ -1178,6 +1190,9 @@ fn build_json_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
McpClient::Dsh => {
bail!("internal: DeepSeek Harness MCP config is a Cordis YAML patch, not JSON")
}
+ McpClient::Hermes => {
+ bail!("internal: Hermes Agent MCP config is ~/.hermes/config.yaml, not JSON")
+ }
_ => build_mcp_entry(args),
}
}
@@ -2468,6 +2483,61 @@ fn dsh_mcp_apply_guidance(args: &InstallMcpArgs) -> String {
)
}
+/// Hermes Agent reads MCP servers from the `mcp_servers:` map of
+/// `~/.hermes/config.yaml` (`$HERMES_HOME/config.yaml`), keyed by server name
+/// with `command`/`args` for a stdio server
+/// (<https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp>,
+/// v0.22.2). Print the entry to merge by hand; --apply is refused.
+///
+/// The entry is always the session-less stdio bridge. Hermes passes an MCP
+/// server a filtered environment with no session id in it, so the client is
+/// static, and a bridge keeps the bearer out of the file: it authenticates
+/// with this install's own token.
+fn render_hermes(args: &InstallMcpArgs) -> String {
+ let token_note = if args.auth_token.is_some() {
+ "#\n\
+ # The token is not written here. The bridge sends this install's\n\
+ # [auth].bearer_token or [auth].bearer_token_file; Hermes does not\n\
+ # pass AI_MEMORY_AUTH_TOKEN from its own environment to MCP servers.\n"
+ } else {
+ ""
+ };
+ format!(
+ "# Hermes Agent - merge the entry below into the `mcp_servers:` map of\n\
+ # ~/.hermes/config.yaml ($HERMES_HOME/config.yaml), then restart\n\
+ # Hermes; a running gateway reloads MCP servers within about a minute.\n\
+ #\n\
+ # Hermes does not read an MCP server's instructions, so the routing\n\
+ # 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\
+ {token_note}\
+ {snippet}\n",
+ snippet = render_hermes_snippet(args),
+ )
+}
+
+fn render_hermes_snippet(args: &InstallMcpArgs) -> String {
+ // Single-quote every scalar, as for DSH: a plain `--name 123` would key
+ // the map with an integer, and a path with ` #` would be cut at the
+ // comment.
+ let mut out = String::from("mcp_servers:\n");
+ out.push_str(&format!(" {}:\n", yaml_single_quote(&args.name)));
+ out.push_str(&format!(
+ " command: {}\n",
+ yaml_single_quote(&bridge_command())
+ ));
+ out.push_str(" args:");
+ for arg in session_less_bridge_args(args) {
+ out.push_str(&format!("\n - {}", yaml_single_quote(&arg)));
+ }
+ out
+}
+
+/// Why `install-mcp --client hermes --apply` writes nothing, and what to do.
+const HERMES_MCP_APPLY_GUIDANCE: &str = "Hermes Agent keeps MCP servers in ~/.hermes/config.yaml, a YAML file ai-memory does not edit; refusing to write MCP config. Re-run without --apply to print the mcp_servers entry, then merge it into ~/.hermes/config.yaml ($HERMES_HOME/config.yaml).";
+
fn render_pi(args: &InstallMcpArgs) -> Result<String> {
Ok(pi_mcp_render_guidance(args))
}
@@ -3544,6 +3614,56 @@ mod tests {
validate_args(&args).expect("valid name");
}
+ /// Hermes' entry is the session-less stdio bridge under `mcp_servers:`,
+ /// every scalar a single-quoted YAML string.
+ #[test]
+ fn hermes_render_is_a_quoted_stdio_bridge_entry() {
+ let mut args = args_for(McpClient::Hermes);
+ args.name = "123".into();
+ args.server_url = Some("http://h:1/mcp?a=\"b\" #c".into());
+ args.bridge_data_dir = Some(PathBuf::from("/data dir/it's"));
+ let rendered = render_hermes(&args);
+ let command = yaml_single_quote(&bridge_command());
+ let expected = format!(
+ "mcp_servers:\n '123':\n command: {command}\n args:\n \
+ - 'mcp-bridge'\n - '--no-session-id'\n - '--server-url'\n \
+ - 'http://h:1/mcp?a=\"b\" #c'\n - '--data-dir'\n - '/data dir/it''s'\n"
+ );
+ assert!(rendered.ends_with(&expected), "{rendered}");
+ // The model never sees ai-memory's MCP instructions in Hermes, so the
+ // 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"));
+ }
+
+ /// No bearer reaches Hermes' config: the bridge authenticates with the
+ /// install's own token.
+ #[test]
+ fn hermes_render_never_embeds_the_token() {
+ let rendered = render_hermes(&args_with_token(McpClient::Hermes));
+ assert!(!rendered.contains("test-token-deadbeef"), "{rendered}");
+ assert!(!rendered.contains("Bearer"), "{rendered}");
+ assert!(!rendered.contains("headers"), "{rendered}");
+ assert!(rendered.contains("The token is not written here"));
+ assert!(!render_hermes(&args_for(McpClient::Hermes)).contains("The token is not"));
+ }
+
+ #[test]
+ fn hermes_apply_and_config_path_are_refused_with_guidance() {
+ let mut args = args_with_token(McpClient::Hermes);
+ args.apply = true;
+ let error = apply_to_config_file(&args).expect_err("apply must be refused");
+ let message = format!("{error}");
+ assert!(message.contains("~/.hermes/config.yaml"), "{message}");
+ assert!(message.contains("without --apply"), "{message}");
+ assert!(!message.contains("test-token-deadbeef"), "{message}");
+ let error = mcp_config_path(McpClient::Hermes).expect_err("no writable config");
+ assert!(format!("{error}").contains("~/.hermes/config.yaml"));
+ assert!(json_mcp_location(McpClient::Hermes).is_none());
+ assert!(build_json_mcp_entry(&args_for(McpClient::Hermes)).is_err());
+ }
+
#[test]
fn dsh_apply_is_refused_with_the_patch_pointer() {
let mut args = args_for(McpClient::Dsh);
@@ -4186,6 +4306,7 @@ mod tests {
McpClient::Zed => render_zed(&args).unwrap(),
McpClient::Muse => render_muse(&args).unwrap(),
McpClient::Dsh => render_dsh(&args).unwrap(),
+ McpClient::Hermes => render_hermes(&args),
McpClient::PrimeAgent => render_prime_agent(&args).unwrap(),
McpClient::Cline => render_json_mcp_fragment(&args).unwrap(),
McpClient::Freebuff => {
@@ -4272,6 +4393,7 @@ mod tests {
McpClient::Zed,
McpClient::Muse,
McpClient::Dsh,
+ McpClient::Hermes,
McpClient::PrimeAgent,
McpClient::Cline,
McpClient::Freebuff,
@@ -4315,6 +4437,7 @@ mod tests {
McpClient::Zed => render_zed(&args).unwrap(),
McpClient::Muse => render_muse(&args).unwrap(),
McpClient::Dsh => render_dsh(&args).unwrap(),
+ McpClient::Hermes => render_hermes(&args),
McpClient::PrimeAgent => render_prime_agent(&args).unwrap(),
McpClient::Cline => render_json_mcp_fragment(&args).unwrap(),
McpClient::Freebuff => {
@@ -4362,7 +4485,7 @@ mod tests {
let config = file_token_config(tmp.path());
let url = DEFAULT_MCP_URL;
for &client in <McpClient as clap::ValueEnum>::value_variants() {
- if matches!(client, McpClient::Pi | McpClient::Dsh) {
+ if matches!(client, McpClient::Pi | McpClient::Dsh | McpClient::Hermes) {
continue; // no config file: an extension, and print-only
}
let ext = if matches!(client, McpClient::Codex | McpClient::Grok) {
diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rs
index 91e3e1ab..b1092b15 100644
--- a/crates/ai-memory-cli/src/commands/uninstall.rs
+++ b/crates/ai-memory-cli/src/commands/uninstall.rs
@@ -1590,7 +1590,9 @@ fn mcp_servers_path(client: McpClient) -> Option<&'static [&'static str]> {
// Muse reads `mcpServers` or the legacy `mcp_servers`;
// `strip_mcp_json` sweeps both.
McpClient::Muse => Some(&["mcpServers"]),
- McpClient::Codex | McpClient::Grok | McpClient::Pi | McpClient::Dsh => None,
+ McpClient::Codex | McpClient::Grok | McpClient::Pi | McpClient::Dsh | McpClient::Hermes => {
+ None
+ }
}
}