Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(install-mcp): add Muse Code as an MCP-only client
Felipe Neves Ricardob4e7d6bf3aa0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6e5b750d..5b28e272 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- `install-mcp --client muse` registers ai-memory with Meta's Muse Code,+ merging a native streamable-HTTP entry with bearer `headers` into the+ snake_case `mcp_servers` map of `~/.config/muse/settings.json` and+ preserving sibling servers. The writer adds the mandatory+ `"schema_version": 1` when it is absent — without that key every `muse`+ command fails at startup with `malformed settings file` — and never+ rewrites an existing value, so a future schema is not downgraded. The entry+ sets `"mode": "optional"` because Muse defaults it to `required`, which+ aborts the whole run when the memory server is unreachable. MCP-only:+ Muse documents a lifecycle hook surface, but the output contract of its+ `SessionStart` event is not specified, so capture and managed workstreams+ are not claimed. Skills need no extra step — Muse reads `~/.agents/skills`,+ which `install-skills` already writes (#659).+### Changed- The managed routing snippet distinguishes a reviewed decision record kept inthe repository (an ADR directory, a Keep the Why `context/` tree) from adiff --git a/README.md b/README.mdindex 1c6ff921..83c12f2f 100644--- a/README.md+++ b/README.md@@ -113,6 +113,7 @@ caveats is in [`docs/support-matrix.md`](docs/support-matrix.md).| Pool | Hooks-only || VS Code Copilot | MCP-only || Zed | MCP-only |+| Muse Code | MCP-only || Hermes Agent | Community || LLM/auth providers | Supported || Embedding providers | Supported |diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 3854fcd1..ef7c405b 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -1671,6 +1671,22 @@ pub enum McpClient {/// `context_servers` map. This integration is MCP-only because Zed/// does not expose ai-memory-compatible lifecycle hooks.Zed,+ /// Muse Code (Meta) — `~/.config/muse/settings.json`, servers under a+ /// top-level snake_case `mcp_servers` map with `transport:+ /// "streamable_http"` + `url` + `headers`.+ ///+ /// Two documented constraints shape the generated entry. The settings+ /// file must carry `"schema_version": 1` or *every* Muse Code command+ /// fails at startup with `malformed settings file`, so the writer adds+ /// the key when it is absent and never rewrites an existing value. And+ /// `mode` defaults to `required`, which aborts the whole Muse run when+ /// the server is unreachable; ai-memory augments a session rather than+ /// gating it, so the entry sets `mode: "optional"` explicitly.+ ///+ /// MCP-only: Muse Code's hook surface is documented but its+ /// `SessionStart` output contract is not, so lifecycle capture and+ /// managed workstreams are not claimed. See `install-mcp --client muse`.+ Muse,}/// Arguments for `commit`.diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex c8181482..81e0ba81 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -1139,6 +1139,14 @@ fn infer_installed_mcp_config(agent: AgentChoice) -> Result<Option<InferredMcpCo&["context_servers", "ai-memory"],"url",)),+ // MCP-only client: no AgentChoice counterpart routes here. Muse+ // Code's hook surface is documented, but its SessionStart output+ // contract is not, so no lifecycle integration claims it yet.+ McpClient::Muse => Ok(infer_json_mcp_config(+ &content,+ &["mcp_servers", "ai-memory"],+ "url",+ )),}}diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rsindex f8c6e3b0..45e18b9a 100644--- a/crates/ai-memory-cli/src/commands/install_mcp.rs+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs@@ -42,6 +42,11 @@ enum JsonMcpLocation {RootServers,/// Top-level `context_servers` key used by Zed's settings.json.RootContextServers,+ /// Top-level snake_case `mcp_servers` key used by Muse Code's+ /// settings.json. Distinct from `RootMcpServers` purely by casing —+ /// Muse documents `mcp_servers`, and the camelCase spelling every+ /// other client uses would be ignored.+ RootMcpServersSnake,}/// Run the `install-mcp` subcommand.@@ -82,6 +87,7 @@ pub fn run(config: &Config, args: InstallMcpArgs) -> Result<()> {McpClient::Swival => render_swival(&args)?,McpClient::VsCodeCopilot => render_vscode_copilot(&args)?,McpClient::Zed => render_zed(&args)?,+ McpClient::Muse => render_muse(&args)?,};println!("{snippet}");Ok(())@@ -250,6 +256,10 @@ pub(crate) fn mcp_config_path(client: crate::cli::McpClient) -> Result<PathBuf>};zed_config_path_in(&config_dir, std::env::consts::OS)}+ // Muse Code documents `~/.config/muse/settings.json`; it also reads+ // $XDG_CONFIG_HOME for its skill roots, so --config-file covers+ // non-default XDG setups (same policy as Zero above).+ McpClient::Muse => home()?.join(".config").join("muse").join("settings.json"),})}@@ -514,6 +524,7 @@ fn json_mcp_location(client: McpClient) -> Option<JsonMcpLocation> {}McpClient::VsCodeCopilot => Some(JsonMcpLocation::RootServers),McpClient::Zed => Some(JsonMcpLocation::RootContextServers),+ McpClient::Muse => Some(JsonMcpLocation::RootMcpServersSnake),McpClient::Codex | McpClient::Grok | McpClient::Pi => None,}}@@ -526,6 +537,7 @@ fn build_json_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {McpClient::Openclaw => build_mcp_entry_openclaw(args),McpClient::Zero => build_mcp_entry_zero(args),McpClient::Zcode => build_mcp_entry_zcode(args),+ McpClient::Muse => build_mcp_entry_muse(args),McpClient::Codex | McpClient::Grok => {bail!("internal: Codex/Grok MCP config is TOML, not JSON")}@@ -584,6 +596,23 @@ fn upsert_json_mcp_entry(.context("`context_servers` is present but not an object")?;servers.insert(args.name.clone(), entry);}+ JsonMcpLocation::RootMcpServersSnake => {+ let servers = root+ .entry("mcp_servers")+ .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))+ .as_object_mut()+ .context("`mcp_servers` is present but not an object")?;+ servers.insert(args.name.clone(), entry);+ }+ }+ // Muse Code fails *every* command at startup when settings.json omits+ // `schema_version`, so creating the file without it would break the+ // user's agent rather than just their memory server. Only fill it in+ // when absent: an unrecognized value is Muse's own error to report,+ // and a future schema 2 must not be silently downgraded here.+ if matches!(args.client, McpClient::Muse) {+ root.entry("schema_version")+ .or_insert_with(|| serde_json::Value::from(1));}Ok(())}@@ -607,6 +636,13 @@ fn render_json_mcp_fragment(args: &InstallMcpArgs) -> Result<String> {JsonMcpLocation::RootContextServers => json!({"context_servers": { args.name.as_str(): entry }}),+ // `schema_version` rides along: a hand-merged Muse settings.json+ // without it fails every command at startup, so the printed+ // snippet has to carry the key the same way --apply does.+ JsonMcpLocation::RootMcpServersSnake => json!({+ "schema_version": 1,+ "mcp_servers": { args.name.as_str(): entry }+ }),};Ok(serde_json::to_string_pretty(&fragment)?)}@@ -840,6 +876,29 @@ fn build_mcp_entry_zcode(args: &InstallMcpArgs) -> Result<serde_json::Value> {Ok(serde_json::Value::Object(entry))}+/// Muse Code MCP entry: `transport: "streamable_http"` + `url` + optional+/// `headers` under `~/.config/muse/settings.json`'s `mcp_servers` map.+///+/// `mode` is written explicitly because Muse Code defaults it to+/// `required`, and a required server that fails to start aborts the whole+/// run. Memory is an augmentation, so an unreachable server should cost+/// the user their recall, not their coding session. No `framing` key is+/// emitted: a non-default `framing` on `streamable_http` fails Muse's own+/// validation.+fn build_mcp_entry_muse(args: &InstallMcpArgs) -> Result<serde_json::Value> {+ let bearer = bearer_header_value(args.auth_token.as_deref());+ let server_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);+ let mut entry = serde_json::Map::new();+ entry.insert("transport".into(), json!("streamable_http"));+ entry.insert("url".into(), json!(server_url));+ if let Some(b) = bearer {+ entry.insert("headers".into(), json!({"Authorization": b}));+ }+ entry.insert("enabled".into(), json!(true));+ entry.insert("mode".into(), json!("optional"));+ Ok(serde_json::Value::Object(entry))+}+/// Insert / replace `[mcp_servers.<name>]` in a Codex `config.toml`.////// Codex parses both forms (block-style `[mcp_servers.foo]` and the@@ -1186,6 +1245,22 @@ fn render_zcode(args: &InstallMcpArgs) -> Result<String> {))}+fn render_muse(args: &InstallMcpArgs) -> Result<String> {+ Ok(format!(+ "# Muse Code (Meta) — merge into ~/.config/muse/settings.json\n\+ # (or re-run this command with --apply), then start a new session.\n\+ #\n\+ # Keep \"schema_version\": 1 — without it every muse command fails\n\+ # at startup with `malformed settings file`.\n\+ #\n\+ # mode is set to \"optional\" on purpose: Muse defaults it to\n\+ # \"required\", which aborts the whole run when the server is\n\+ # unreachable. Auth goes in the headers map.\n\+ {snippet}\n",+ snippet = render_json_mcp_fragment(args)?,+ ))+}+fn render_pi(args: &InstallMcpArgs) -> Result<String> {Ok(pi_mcp_render_guidance(args))}@@ -1382,6 +1457,67 @@ mod tests {}}+ #[test]+ fn muse_entry_uses_documented_streamable_http_shape() {+ let entry = build_json_mcp_entry(&args_with_token(McpClient::Muse)).unwrap();++ assert_eq!(entry["transport"], "streamable_http");+ assert_eq!(entry["url"], "http://127.0.0.1:49374/mcp");+ assert_eq!(+ entry["headers"]["Authorization"],+ "Bearer test-token-deadbeef"+ );+ assert_eq!(entry["enabled"], true);+ // `required` is Muse's default and aborts the entire run when the+ // memory server is unreachable.+ assert_eq!(entry["mode"], "optional");+ // A non-default `framing` on streamable_http fails Muse validation,+ // so the entry must not carry the key at all.+ assert!(entry.get("framing").is_none(), "{entry:#}");+ }++ #[test]+ fn muse_upsert_adds_schema_version_and_preserves_siblings() {+ let mut root = serde_json::Map::new();+ root.insert("telemetry".into(), json!({"enabled": false}));+ root.insert(+ "mcp_servers".into(),+ json!({"my-tools": {"transport": "stdio", "command": "my-mcp-server"}}),+ );++ upsert_json_mcp_entry(&mut root, &args_for(McpClient::Muse)).unwrap();++ // Without this key every muse command fails at startup.+ assert_eq!(root["schema_version"], 1);+ assert_eq!(root["telemetry"]["enabled"], false);+ assert_eq!(root["mcp_servers"]["my-tools"]["command"], "my-mcp-server");+ assert_eq!(+ root["mcp_servers"]["ai-memory"]["transport"],+ "streamable_http"+ );+ }++ #[test]+ fn muse_upsert_never_rewrites_an_existing_schema_version() {+ let mut root = serde_json::Map::new();+ root.insert("schema_version".into(), json!(2));++ upsert_json_mcp_entry(&mut root, &args_for(McpClient::Muse)).unwrap();++ // Downgrading a future schema would break the user's settings file;+ // an unrecognized value is Muse's own error to report.+ assert_eq!(root["schema_version"], 2);+ }++ #[test]+ fn muse_render_carries_schema_version_for_hand_merging() {+ let rendered = render_muse(&args_for(McpClient::Muse)).unwrap();++ assert!(rendered.contains("\"schema_version\": 1"), "{rendered}");+ assert!(rendered.contains("\"mcp_servers\""), "{rendered}");+ assert!(!rendered.contains("\"mcpServers\""), "{rendered}");+ }+#[test]fn opencode2_entry_uses_v2_servers_shape() {// V2 nests under `mcp.servers`, drops v1's `enabled`, and disables@@ -1783,6 +1919,7 @@ mod tests {McpClient::Swival => render_swival(&args).unwrap(),McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),McpClient::Zed => render_zed(&args).unwrap(),+ McpClient::Muse => render_muse(&args).unwrap(),}}@@ -1853,6 +1990,7 @@ mod tests {McpClient::Swival,McpClient::VsCodeCopilot,McpClient::Zed,+ McpClient::Muse,] {let out = render_for_test(client);assert!(@@ -1888,6 +2026,7 @@ mod tests {McpClient::Swival => render_swival(&args).unwrap(),McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),McpClient::Zed => render_zed(&args).unwrap(),+ McpClient::Muse => render_muse(&args).unwrap(),}}diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rsindex e4625243..a178faf9 100644--- a/crates/ai-memory-cli/src/commands/uninstall.rs+++ b/crates/ai-memory-cli/src/commands/uninstall.rs@@ -358,6 +358,7 @@ fn build_plan(args: &UninstallArgs) -> anyhow::Result<Vec<PlannedChange>> {KiroCli,CommandCode,Swival,+ Muse,] {let paths = if matches!(client, ClaudeCode) {claude_config_paths(@@ -1121,6 +1122,9 @@ fn mcp_servers_path(client: McpClient) -> Option<&'static [&'static str]> {McpClient::Openclaw | McpClient::Zero | McpClient::Zcode => Some(&["mcp", "servers"]),McpClient::VsCodeCopilot => Some(&["servers"]),McpClient::Zed => Some(&["context_servers"]),+ // Muse Code spells the key snake_case; the camelCase spelling the+ // clients above use would leave the entry behind.+ McpClient::Muse => Some(&["mcp_servers"]),McpClient::Codex | McpClient::Grok | McpClient::Pi => None,}}diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex dd85c5f6..cdf6fe4d 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -38,8 +38,8 @@ ignore_paths`; legacy shell/PowerShell and remote-only/Docker script bundles donot. Reinstall/refresh an existing hook or plugin to gain it; see[Capture exclusions](marker-file.md#capture-exclusions).-Claude Desktop, VS Code Copilot, and Zed are **MCP-only** here: they-expose long-term memory to their LLMs via ai-memory's MCP tools+Claude Desktop, VS Code Copilot, Zed, and Muse Code are **MCP-only** here:+they expose long-term memory to their LLMs via ai-memory's MCP tools(`memory_query`, `memory_recent`, `memory_handoff_accept`, etc.), butthey do not auto-capture session events into ai-memory's `/hook`endpoint. The trade-off:@@ -120,7 +120,7 @@ metadata.> **One-shot tip:** every snippet below is also reachable from the> CLI:> ```bash-> ai-memory install-mcp --client gemini-cli # or cursor / claude-desktop / openclaw / omp / pi / antigravity-cli / grok / kimi-code / kiro-cli / command-code / swival / devin / zero / zcode / vscode-copilot / zed+> ai-memory install-mcp --client gemini-cli # or cursor / claude-desktop / openclaw / omp / pi / antigravity-cli / grok / kimi-code / kiro-cli / command-code / swival / devin / zero / zcode / vscode-copilot / zed / muse> ```---@@ -337,6 +337,75 @@ Sources: <https://zed.dev/docs/ai/mcp>,---+## Muse Code++**Status:** MCP supported through Muse Code's native streamable-HTTP+transport, including bearer authentication. No lifecycle-hook integration+and no managed-workstream adapter.++**Config file:** `~/.config/muse/settings.json`. Muse also reads+`$XDG_CONFIG_HOME` for its skill roots; on a non-default XDG setup pass the+concrete path with `--config-file`.++Servers live under the top-level snake_case `mcp_servers` key. Note the+casing: `mcpServers`, which most other clients use, is ignored here.++```json+{+ "schema_version": 1,+ "mcp_servers": {+ "ai-memory": {+ "transport": "streamable_http",+ "url": "http://127.0.0.1:49374/mcp",+ "headers": {+ "Authorization": "Bearer <token>"+ },+ "enabled": true,+ "mode": "optional"+ }+ }+}+```++Print or apply the configuration with:++```bash+ai-memory install-mcp --client muse+ai-memory install-mcp --client muse --apply \+ --server-url "http://homelab:49374/mcp" \+ --auth-token "$TOKEN"+```++Two details of Muse's schema are worth knowing before hand-editing the file:++- **`"schema_version": 1` is mandatory.** A settings file that omits it fails+ *every* `muse` command at startup with `malformed settings file`. `--apply`+ adds the key when it is missing and never rewrites an existing value, so a+ future schema is not silently downgraded.+- **`mode` defaults to `required`**, and a required server that fails to start+ aborts the whole Muse run. ai-memory writes `"mode": "optional"` explicitly+ so an unreachable memory server costs you recall rather than the session.++A non-default `framing` value is rejected on `streamable_http`, so the+generated entry omits the key.++**Skills:** no extra step is needed. Muse Code loads user skills from+`$XDG_CONFIG_HOME/muse/skills` and `~/.agents/skills`, and+`ai-memory install-skills` already writes the cross-client `~/.agents/skills`+root, so the ai-memory routing skills are visible to Muse. Confirm with+`muse skills list`.++Muse Code documents a lifecycle hook surface, but the output contract of its+`SessionStart` event is not specified, so automatic capture and automatic+handoff injection are not claimed here. Ask the agent to call+`memory_handoff_begin` before leaving and `memory_handoff_accept` when+resuming when you need continuity.++Sources: <https://dev.meta.ai/docs/muse-code/configuration>,+<https://dev.meta.ai/docs/muse-code/extending>.++---+## Claude Desktop**Status:** ✅ MCP supported (via stdio shim for HTTP). ❌ No lifecycle hooks.diff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex e20a15f1..59488f14 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -34,6 +34,7 @@| Pool | Hooks-only | Poolside Agent CLI (`pool`). Lifecycle-hook capture via `install-hooks --agent pool` (alias `poolside`): Pool reads project-scoped hooks from the repo-root `.poolside/settings.yaml`, so ai-memory stages the scripts and prints a ready-to-paste `hooks:` snippet rather than writing project-local files; native commands enforce capture exclusions. Five Claude-shaped events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and no true session-end — `Stop` is a turn boundary, so run `ai-memory finalize-session --agent pool` after the final turn. `SessionStart` stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP `memory_handoff_accept`. No first-party `install-mcp` client and no managed workstream (`ai-memory run pool`) are claimed: Pool's native session-store contract is not demonstrated (see [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. || 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. |+| Muse Code | MCP-only | `install-mcp --client muse` merges a native streamable-HTTP entry with bearer `headers` into the snake_case `mcp_servers` map of `~/.config/muse/settings.json`, preserving sibling servers. The writer adds the mandatory `"schema_version": 1` when absent (without it every `muse` command fails at startup) and never rewrites an existing value, and it sets `"mode": "optional"` because Muse's default `required` aborts the whole run when the server is unreachable. Skills need no extra step: Muse reads `~/.agents/skills`, which `install-skills` already writes. Lifecycle capture and managed workstreams are not claimed — Muse documents a hook surface, but the output contract of its `SessionStart` event is not specified. || 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 (Go and Zen), 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. |