Skip to content

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.md
index 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 in
the repository (an ADR directory, a Keep the Why `context/` tree) from a
diff --git a/README.md b/README.md
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 do
not. 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.), but
they 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.md
index 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. |