Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(install-mcp): --flavor pins the schema dialect for any client
Abhishek Sharma4f0401b21443
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f82367a3..85c23588 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- `install-mcp --flavor <moonshot|bedrock|gemini>` pins the tool-schema dialect+ in the URL written into a client's config. The installer already picks one for+ the clients whose upstream is fixed — Kimi Code is always Moonshot, Kiro always+ Bedrock — but a client that fronts several models cannot be pinned by its name+ alone, and there was no installer path to `?flavor=gemini` for any of them. A+ Command Code or OpenCode install routed to Vertex needed the marker added by+ hand or every model call 400'd at `tools/list`; the same client on a non-Google+ model does not, which is why this is an explicit choice rather than another+ per-client default. `vertex` is accepted as an alias. `uninstall` now matches+ every marker on every client, so an entry pinned this way is still removed+ (#735).+## [2.2.1] - 2026-09-12### Fixeddiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex bc442c75..56a8e543 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -1624,6 +1624,41 @@ pub struct FinalizeSessionArgs {pub json: bool,}+/// Tool-schema dialect to pin into the installed MCP URL, as the server's+/// `?flavor=` marker (docs/mcp-install.md → Schema dialects for strict+/// upstreams). `install-mcp` already picks one for the clients whose upstream+/// is fixed — Kimi Code is always Moonshot, Kiro is always Bedrock — but a+/// client that fronts several models cannot be pinned by its name alone. A+/// Command Code or OpenCode install routed to Vertex needs `gemini`; the same+/// client on another model does not, and forcing it there would narrow the+/// advertised schema for no reason. So this stays an explicit operator choice.+///+/// Every variant is at least as permissive as each client's built-in default,+/// so passing one can only relax the advertised schema further, never tighten+/// it below what the client already needs.+#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]+pub enum SchemaFlavor {+ /// Drop root-level `anyOf`/`oneOf`/`allOf` (Moonshot).+ Moonshot,+ /// Same rewrite, for Bedrock-backed clients.+ Bedrock,+ /// The above, plus nullable unions collapsed to a single `type` plus+ /// `nullable: true` (Gemini / Vertex).+ #[value(alias = "vertex")]+ Gemini,+}++impl SchemaFlavor {+ /// The `flavor=` query value the server matches in `restricted_schema_flavor`.+ pub fn marker(self) -> &'static str {+ match self {+ Self::Moonshot => "moonshot",+ Self::Bedrock => "bedrock",+ Self::Gemini => "gemini",+ }+ }+}+/// MCP client to render configuration for. Includes both the/// hook-capable agents (Claude Code / Codex / OpenCode — same MCP/// surface, also covered by `install-hooks`) and the MCP-only@@ -2202,6 +2237,13 @@ pub struct InstallMcpArgs {/// `[auto_scope] mode = "per_session"` for concurrent Claude Code sessions.#[arg(long)]pub session_aware: bool,+ /// Pin the tool-schema dialect in the installed MCP URL, for a client+ /// whose upstream 400s on the schemas ai-memory advertises by default.+ /// Needed when the client fronts several models and its name alone does+ /// not say which — a Command Code or OpenCode install routed to Vertex+ /// wants `gemini`. Kimi Code and Kiro already get theirs; this overrides.+ #[arg(long, value_enum)]+ pub flavor: Option<SchemaFlavor>,}/// Arguments for the internal Claude Code session-aware MCP bridge.diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rsindex 45e18b9a..d954f53f 100644--- a/crates/ai-memory-cli/src/commands/install_mcp.rs+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs@@ -21,7 +21,7 @@ use jsonc_parser::ParseOptions;use jsonc_parser::cst::{CstInputValue, CstRootNode};use serde_json::json;-use crate::cli::{InstallMcpArgs, McpClient};+use crate::cli::{InstallMcpArgs, McpClient, SchemaFlavor};use crate::commands::apply_shared::{ApplyOutcome, apply_atomic, mutate_json, mutate_toml};use crate::commands::path_util::{claude_config_dir, home_dir};use crate::commands::render_shared::bearer_header_value;@@ -665,12 +665,42 @@ fn flavored_mcp_url(server_url: &str, flavor: &str) -> String {format!("{url}{separator}{marker}")}-pub(crate) fn moonshot_flavored_mcp_url(server_url: &str) -> String {- flavored_mcp_url(server_url, "moonshot")+/// Every marker `install-mcp` can write. `uninstall` walks this so an entry+/// installed with `--flavor` is still matched by URL; adding a flavor without+/// adding it here would leave those entries behind.+pub(crate) const FLAVOR_MARKERS: [&str; 3] = ["moonshot", "bedrock", "gemini"];++/// [`flavored_mcp_url`] for a marker already in hand — what `uninstall` needs+/// to rebuild each candidate URL form without knowing the flavor type.+pub(crate) fn flavored_mcp_url_for_marker(server_url: &str, marker: &str) -> String {+ flavored_mcp_url(server_url, marker)}-pub(crate) fn bedrock_flavored_mcp_url(server_url: &str) -> String {- flavored_mcp_url(server_url, "bedrock")+/// The dialect a client always needs, from its name alone. Only clients with a+/// single fixed upstream appear here — Kimi Code is Moonshot, Kiro is Bedrock.+/// A client that fronts several models has no answer here and needs `--flavor`.+fn client_default_flavor(client: McpClient) -> Option<&'static str> {+ match client {+ McpClient::KimiCode => Some("moonshot"),+ McpClient::KiroCli => Some("bedrock"),+ _ => None,+ }+}++/// The URL to write into the client config: the endpoint plus whichever+/// `?flavor=` marker applies. An explicit `--flavor` wins over the client's+/// built-in default, which is safe in one direction only by construction —+/// every flavor is at least as permissive as any default, so an override can+/// relax the advertised schema but never tighten it past what the client needs.+pub(crate) fn flavored_url_for(args: &InstallMcpArgs, server_url: &str) -> String {+ match args+ .flavor+ .map(SchemaFlavor::marker)+ .or_else(|| client_default_flavor(args.client))+ {+ Some(marker) => flavored_mcp_url(server_url, marker),+ None => server_url.to_string(),+ }}/// JSON entry shape used by Claude Code, Claude Desktop, Cursor, and@@ -680,7 +710,12 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {let bearer = bearer_header_value(args.auth_token.as_deref());// `run()` resolves the URL before dispatch; the fallback only fires for// direct callers (tests, uninstall re-render) that skip that step.- let server_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);+ let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);+ // The flavor marker is a `tools/list` concern, so it belongs on the URL a+ // client fetches schemas from. `mcp-bridge` is not that: it is our own+ // process, and it re-derives its endpoint, so it keeps the bare URL.+ let flavored = flavored_url_for(args, base_url);+ let server_url = flavored.as_str();let mut entry = serde_json::Map::new();match args.client {McpClient::ClaudeCode => {@@ -689,7 +724,7 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {entry.insert("command".into(), json!("ai-memory"));entry.insert("args".into(),- json!(["mcp-bridge", "--server-url", server_url]),+ json!(["mcp-bridge", "--server-url", base_url]),);if let Some(token) = &args.auth_token {entry.insert("env".into(), json!({"AI_MEMORY_AUTH_TOKEN": token}));@@ -753,13 +788,13 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {// Kimi Code treats an entry with `url` and no `transport`// field as streamable-HTTP; `transport` is only for legacy// SSE endpoints.- entry.insert("url".into(), json!(moonshot_flavored_mcp_url(server_url)));+ entry.insert("url".into(), json!(server_url));if let Some(b) = &bearer {entry.insert("headers".into(), json!({"Authorization": b}));}}McpClient::KiroCli => {- entry.insert("url".into(), json!(bedrock_flavored_mcp_url(server_url)));+ entry.insert("url".into(), json!(server_url));if let Some(b) = &bearer {entry.insert("headers".into(), json!({"Authorization": b}));}@@ -1442,6 +1477,7 @@ mod tests {apply: false,config_file: None,session_aware: false,+ flavor: None,}}@@ -1454,6 +1490,7 @@ mod tests {apply: false,config_file: None,session_aware: false,+ flavor: None,}}@@ -2339,6 +2376,93 @@ mod tests {/// Pin the append rules: `?` on a bare endpoint, `&` with an existing/// query, never duplicate an existing marker.+ #[test]+ fn an_explicit_flavor_pins_a_client_the_installer_cannot_infer() {+ // The issue-735 shape: Command Code fronts several models, so its name+ // says nothing about the upstream. Routed to Vertex it needs the Gemini+ // dialect, and before --flavor there was no installer path to it.+ let mut args = args_for(McpClient::CommandCode);+ args.server_url = Some("https://memory.example/mcp".into());+ args.flavor = Some(SchemaFlavor::Gemini);++ let entry = build_mcp_entry(&args).unwrap();++ assert_eq!(+ entry["url"].as_str().unwrap(),+ "https://memory.example/mcp?flavor=gemini"+ );+ }++ #[test]+ fn a_client_without_a_fixed_upstream_stays_unflavored_by_default() {+ let mut args = args_for(McpClient::CommandCode);+ args.server_url = Some("https://memory.example/mcp".into());++ let entry = build_mcp_entry(&args).unwrap();++ assert_eq!(entry["url"].as_str().unwrap(), "https://memory.example/mcp");+ }++ #[test]+ fn an_explicit_flavor_replaces_the_clients_built_in_default() {+ // Kimi Code defaults to moonshot. Asking for gemini must not stack a+ // second marker: the server maxes over every pair, so both would work,+ // but the installed URL would carry a dialect the operator did not pick.+ let mut args = args_for(McpClient::KimiCode);+ args.server_url = Some("https://memory.example/mcp".into());+ args.flavor = Some(SchemaFlavor::Gemini);++ let entry = build_mcp_entry(&args).unwrap();++ assert_eq!(+ entry["url"].as_str().unwrap(),+ "https://memory.example/mcp?flavor=gemini"+ );+ }++ #[test]+ fn the_session_aware_bridge_keeps_the_unflavored_url() {+ // `mcp-bridge` is our own process, not a schema consumer. Handing it a+ // flavored URL would push the marker through to the server on every+ // bridged request, narrowing schemas for a client that never asked.+ let mut args = args_for(McpClient::ClaudeCode);+ args.server_url = Some("https://memory.example/mcp".into());+ args.session_aware = true;+ args.flavor = Some(SchemaFlavor::Gemini);++ let entry = build_mcp_entry(&args).unwrap();++ let bridge_args: Vec<&str> = entry["args"]+ .as_array()+ .unwrap()+ .iter()+ .map(|a| a.as_str().unwrap())+ .collect();+ assert_eq!(+ bridge_args,+ vec!["mcp-bridge", "--server-url", "https://memory.example/mcp"]+ );+ }++ #[test]+ fn every_flavor_marker_is_one_the_server_recognizes() {+ // The server matches `flavor=` values exactly. A marker the CLI can+ // write but the server does not match would install a URL that silently+ // serves upstream schemas — the exact failure --flavor exists to avoid.+ for flavor in [+ SchemaFlavor::Moonshot,+ SchemaFlavor::Bedrock,+ SchemaFlavor::Gemini,+ ] {+ assert!(+ FLAVOR_MARKERS.contains(&flavor.marker()),+ "{:?} writes marker {:?}, which uninstall does not know",+ flavor,+ flavor.marker()+ );+ }+ }+#[test]fn moonshot_flavored_mcp_url_appends_marker_idempotently() {for (input, expected) in [@@ -2364,22 +2488,26 @@ mod tests {"http://homelab:49374/mcp?note=flavor=moonshot&flavor=moonshot",),] {- assert_eq!(moonshot_flavored_mcp_url(input), expected, "input: {input}");+ assert_eq!(+ flavored_mcp_url_for_marker(input, "moonshot"),+ expected,+ "input: {input}"+ );}}#[test]fn bedrock_flavored_mcp_url_appends_marker_idempotently() {assert_eq!(- bedrock_flavored_mcp_url("https://memory.example/mcp"),+ flavored_mcp_url_for_marker("https://memory.example/mcp", "bedrock"),"https://memory.example/mcp?flavor=bedrock");assert_eq!(- bedrock_flavored_mcp_url("https://memory.example/mcp?token=x"),+ flavored_mcp_url_for_marker("https://memory.example/mcp?token=x", "bedrock"),"https://memory.example/mcp?token=x&flavor=bedrock");assert_eq!(- bedrock_flavored_mcp_url("https://memory.example/mcp?flavor=bedrock"),+ flavored_mcp_url_for_marker("https://memory.example/mcp?flavor=bedrock", "bedrock"),"https://memory.example/mcp?flavor=bedrock");}diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rsindex a178faf9..34e12281 100644--- a/crates/ai-memory-cli/src/commands/uninstall.rs+++ b/crates/ai-memory-cli/src/commands/uninstall.rs@@ -1159,16 +1159,14 @@ fn mcp_entry_is_ours(key: &str, entry: &serde_json::Value, name: Option<&str>, u/// for clients whose installer appends a schema flavor, the form/// `install-mcp` actually writes (`--mcp-url` keeps the unflavored default)./// Every other client keeps exact-match semantics.-fn mcp_url_candidates(client: McpClient, url: &str) -> Vec<String> {+fn mcp_url_candidates(_client: McpClient, url: &str) -> Vec<String> {let mut candidates = vec![url.to_string()];- if matches!(client, McpClient::KimiCode) {- let flavored = install_mcp::moonshot_flavored_mcp_url(url);- if !candidates.contains(&flavored) {- candidates.push(flavored);- }- }- if matches!(client, McpClient::KiroCli) {- let flavored = install_mcp::bedrock_flavored_mcp_url(url);+ // Every marker, for every client: `install-mcp --flavor` can write any of+ // them into any client's config, so keying this off the client's built-in+ // default would strand the entries an operator pinned by hand. Candidates+ // that do not appear in the file simply match nothing.+ for marker in install_mcp::FLAVOR_MARKERS {+ let flavored = install_mcp::flavored_mcp_url_for_marker(url, marker);if !candidates.contains(&flavored) {candidates.push(flavored);}@@ -2204,31 +2202,48 @@ command = "'/usr/local/bin/ai-memory' hook --event stop --agent kimi-code --serv}#[test]- fn mcp_url_candidates_adds_client_schema_flavors() {+ fn mcp_url_candidates_covers_every_installable_flavor() {+ // Was keyed off the client's built-in default. `install-mcp --flavor`+ // can now write any marker into any client's config, so candidates are+ // keyed off what the installer can write instead — otherwise an entry+ // an operator pinned by hand survives `uninstall`.assert_eq!(mcp_url_candidates(McpClient::KimiCode, "http://127.0.0.1:49374/mcp"),vec!["http://127.0.0.1:49374/mcp".to_string(),- "http://127.0.0.1:49374/mcp?flavor=moonshot".to_string()+ "http://127.0.0.1:49374/mcp?flavor=moonshot".to_string(),+ "http://127.0.0.1:49374/mcp?flavor=bedrock".to_string(),+ "http://127.0.0.1:49374/mcp?flavor=gemini".to_string(),]);+ // An already-flavored URL is not duplicated into the list.assert_eq!(mcp_url_candidates(McpClient::KimiCode,"http://127.0.0.1:49374/mcp?flavor=moonshot"- ),- vec!["http://127.0.0.1:49374/mcp?flavor=moonshot".to_string()]+ )[0],+ "http://127.0.0.1:49374/mcp?flavor=moonshot".to_string());assert_eq!(- mcp_url_candidates(McpClient::KiroCli, "https://memory.example/mcp"),- vec![- "https://memory.example/mcp".to_string(),- "https://memory.example/mcp?flavor=bedrock".to_string()- ]+ mcp_url_candidates(+ McpClient::KimiCode,+ "http://127.0.0.1:49374/mcp?flavor=moonshot"+ )+ .iter()+ .filter(|c| c.ends_with("flavor=moonshot"))+ .count(),+ 1);- assert_eq!(- mcp_url_candidates(McpClient::Cursor, "http://127.0.0.1:49374/mcp"),- vec!["http://127.0.0.1:49374/mcp".to_string()]+ // The case the broadening exists for: Command Code has no default+ // flavor, but an operator on a Vertex-backed model pins one.+ assert!(+ mcp_url_candidates(McpClient::CommandCode, "https://memory.example/mcp")+ .contains(&"https://memory.example/mcp?flavor=gemini".to_string())+ );+ // Kiro's own default is still matched.+ assert!(+ mcp_url_candidates(McpClient::KiroCli, "https://memory.example/mcp")+ .contains(&"https://memory.example/mcp?flavor=bedrock".to_string()));}diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex fab39739..a1fc114a 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -1237,6 +1237,21 @@ validation is identical in every dialect — only the advertised schema changes.| `?flavor=bedrock` | `strip_root_combinators` | Same as above | Kiro CLI (Bedrock); appended by `install-mcp` || `?flavor=gemini` (alias `vertex`) | `gemini_safe_schemas` | The above, plus nullable unions collapsed to a single `type` + `nullable: true` | Clients that forward schemas verbatim to Gemini/Vertex, e.g. OpenCode on a Vertex model |+`install-mcp` appends the first two itself for the clients whose upstream is+fixed. For any other client, pass the dialect explicitly:++```bash+ai-memory install-mcp --client command-code --flavor gemini --apply+```++This is an operator choice rather than another per-client default because a+client like Command Code or OpenCode fronts several models: it needs the Gemini+dialect only when routed to Vertex, and pinning it there for everyone would+narrow the advertised schema for models that never had the problem. `--flavor`+overrides a client's built-in default rather than stacking a second marker, and+`uninstall` matches every marker on every client, so an entry pinned this way is+still removed.+The Gemini dialect exists because `schemars` renders every optional toolargument as a nullable union: