Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: use Cline's documented MCP schema
AkitaOnRailsc28465b6f389
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8b06ce15..d3648063 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,7 +16,7 @@ version in [`docs/changelog/`](docs/changelog/):--agent cline --apply` writes Cline's nine supported event files globally orper project, refuses user-owned and symlinked targets, and keeps embeddedbearer credentials owner-only. `install-mcp --client cline --apply` writes- Cline's nested transport schema and explicitly selects Streamable HTTP.+ Cline's top-level transport fields and explicitly selects Streamable HTTP.Detached start hooks recover handoffs through MCP; yolo mode disables hooks.Also added `install-mcp --client freebuff --apply`, which registers thesessionless stdio bridge in `~/.agents/mcp.json` without starting anotherdiff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rsindex f9b0b57a..8508d967 100644--- a/crates/ai-memory-cli/src/commands/install_mcp.rs+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs@@ -372,7 +372,8 @@ fn stdio_bridge_entry(args: &InstallMcpArgs) -> Option<serde_json::Value> {| McpClient::KimiCode| McpClient::KiroCli| McpClient::Openclaw- | McpClient::IbmBob => plain(),+ | McpClient::IbmBob+ | McpClient::Cline => plain(),McpClient::GeminiCli | McpClient::AntigravityCli => json!({"command": BRIDGE_COMMAND,"args": bridge,@@ -381,15 +382,6 @@ fn stdio_bridge_entry(args: &InstallMcpArgs) -> Option<serde_json::Value> {McpClient::Cursor | McpClient::VsCodeCopilot | McpClient::Swival | McpClient::Zero => {typed("stdio")}- McpClient::Cline => json!({- "transport": {- "type": "stdio",- "command": BRIDGE_COMMAND,- "args": bridge,- },- "disabled": false,- "autoApprove": [],- }),McpClient::Freebuff => {let env = args.auth_token@@ -1786,22 +1778,20 @@ fn build_mcp_entry_opencode(args: &InstallMcpArgs) -> Result<serde_json::Value>Ok(serde_json::Value::Object(entry))}-/// Cline's CLI writer uses a nested transport object. Keeping the explicit+/// Cline's MCP entry uses top-level transport fields. Keeping the explicit/// `streamableHttp` discriminator is load-bearing: a bare `url` is parsed as/// legacy SSE and sends GET requests to ai-memory's POST-only MCP endpoint.fn build_mcp_entry_cline(args: &InstallMcpArgs) -> Result<serde_json::Value> {let base_url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL);- let mut transport = serde_json::Map::new();- transport.insert("type".into(), json!("streamableHttp"));- transport.insert("url".into(), json!(flavored_url_for(args, base_url)));+ let mut entry = serde_json::Map::new();+ entry.insert("type".into(), json!("streamableHttp"));+ entry.insert("url".into(), json!(flavored_url_for(args, base_url)));if let Some(bearer) = bearer_header_value(args.auth_token.as_deref()) {- transport.insert("headers".into(), json!({"Authorization": bearer}));+ entry.insert("headers".into(), json!({"Authorization": bearer}));}- Ok(json!({- "transport": transport,- "disabled": false,- "autoApprove": [],- }))+ entry.insert("disabled".into(), json!(false));+ entry.insert("autoApprove".into(), json!([]));+ Ok(serde_json::Value::Object(entry))}/// OpenCode 2.0 beta MCP entry: `type: "remote"` + `url` + optional@@ -2704,16 +2694,64 @@ mod tests {#[test]fn cline_entry_explicitly_selects_streamable_http() {let entry = build_json_mcp_entry(&args_with_token(McpClient::Cline)).unwrap();- assert_eq!(entry["transport"]["type"], "streamableHttp");- assert_eq!(entry["transport"]["url"], "http://127.0.0.1:49374/mcp");+ assert_eq!(entry["type"], "streamableHttp");+ assert_eq!(entry["url"], "http://127.0.0.1:49374/mcp");assert_eq!(- entry["transport"]["headers"]["Authorization"],+ entry["headers"]["Authorization"],"Bearer test-token-deadbeef");+ assert!(entry.get("transport").is_none(), "{entry:#}");assert_eq!(entry["disabled"], false);assert_eq!(entry["autoApprove"], json!([]));}+ #[test]+ fn cline_apply_replaces_the_old_nested_entry_and_preserves_siblings() {+ let tmp = tempfile::tempdir().unwrap();+ let file = tmp.path().join("cline_mcp_settings.json");+ fs::write(+ &file,+ json!({+ "mcpServers": {+ "ai-memory": {+ "transport": {+ "type": "streamableHttp",+ "url": "https://old.example/mcp"+ },+ "disabled": false,+ "autoApprove": []+ },+ "other": {"command": "other"}+ },+ "keep": true+ })+ .to_string(),+ )+ .unwrap();+ let mut args = args_for(McpClient::Cline);+ args.apply = true;+ args.config_file = Some(file.clone());+ args.server_url = Some("https://memory.example/mcp".into());++ apply_to_config_file(&args).unwrap();+ let first = fs::read_to_string(&file).unwrap();+ apply_to_config_file(&args).unwrap();+ assert_eq!(first, fs::read_to_string(&file).unwrap());++ let root: serde_json::Value = serde_json::from_str(&first).unwrap();+ assert_eq!(root["keep"], true);+ assert_eq!(root["mcpServers"]["other"]["command"], "other");+ assert_eq!(+ root["mcpServers"]["ai-memory"],+ json!({+ "type": "streamableHttp",+ "url": "https://memory.example/mcp",+ "disabled": false,+ "autoApprove": []+ })+ );+ }+#[test]fn freebuff_entry_uses_sessionless_bridge_not_a_second_server() {let mut args = args_for(McpClient::Freebuff);@@ -4328,6 +4366,10 @@ mod tests {assert_eq!(entry(McpClient::CommandCode)["transport"], "stdio");assert_eq!(entry(McpClient::VsCodeCopilot)["type"], "stdio");assert!(entry(McpClient::Zed).get("type").is_none());+ let cline = entry(McpClient::Cline);+ assert_eq!(cline["command"], "ai-memory");+ assert_eq!(cline["args"][0], "mcp-bridge");+ assert!(cline.get("transport").is_none(), "{cline:#}");// Kimi Code's schema dialect rides the bridge's upstream URL.assert_eq!(entry(McpClient::KimiCode)["args"][3],diff --git a/docs/install.md b/docs/install.mdindex db22acb8..15e869b7 100644--- a/docs/install.md+++ b/docs/install.md@@ -2336,9 +2336,9 @@ ai-memory install-hooks --agent cline --apply```The MCP writer reads `CLINE_MCP_SETTINGS_PATH` or defaults to-`~/.cline/data/settings/cline_mcp_settings.json`; it writes the nested-`transport` object and explicitly selects `streamableHttp` rather than Cline's-legacy SSE default. The hook writer targets the CLI's `~/.cline/hooks` files;+`~/.cline/data/settings/cline_mcp_settings.json`; it writes top-level `type`,+`url`, and optional `headers` fields and explicitly selects `streamableHttp`+rather than Cline's legacy SSE default. The hook writer targets the CLI's `~/.cline/hooks` files;use `--scope project` for `.cline/hooks` in one checkout. Restart Cline afterinstallation. Yolo mode disables Cline hooks, and task-start hooks aredetached, so recover pending handoffs through MCP. The VS Code extension'sdiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 42f9a8ec..49327236 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -191,7 +191,7 @@ ai-memory install-hooks --agent cline --applyThe MCP writer targets`${CLINE_MCP_SETTINGS_PATH:-~/.cline/data/settings/cline_mcp_settings.json}`-and writes Cline's nested `transport` schema with+and writes Cline's top-level `type`, `url`, and optional `headers` fields with`type: "streamableHttp"`; omitting that type makes Cline try legacy SSE. Thehook writer creates Cline CLI's supported event files under `~/.cline/hooks`.Use `--scope project` for `.cline/hooks` in the current checkout. Existingdiff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex b93e5587..080ce732 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -46,7 +46,7 @@| Meta Muse Code | Supported | MCP config (`install-mcp --client muse`, aliases `muse-code`, `musecode`) + lifecycle hooks (`install-hooks --agent muse`), both merged into `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json` around your own keys, servers and hooks. The writers add the mandatory `"schema_version": 1` when it is absent (without it every `muse` command fails at startup) and never rewrite an existing value. The MCP entry is a stdio `ai-memory mcp-bridge --agent muse` that forwards the `MUSE_SESSION_ID` Muse gives its stdio servers, so Muse is session-aware; it carries `"mode": "optional"` (Muse's default `required` aborts the run when a server cannot start) and the install's `--data-dir`, because Muse starts stdio servers and hooks with a cleared environment. It goes under `mcpServers`, or under the legacy `mcp_servers` when the file already uses it; Muse ignores every MCP server when both maps are present, so `--apply` refuses that file and `doctor` reports it. Hooks run the native `ai-memory hook --event … --agent muse` command (no script bundle) with an empty matcher and a 30-second timeout, and native commands enforce capture exclusions over Muse's `read_file`, `write_file`, `edit_file`, `apply_patch`, `search`, `bash`, `monitor`, `web_fetch` and memory tools; a relative `path` resolves lexically against `cwd`, and Muse's `tool_use_id` is kept as the call id. Eight events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PreCompact`, `Stop`, `SessionEnd`; `SubagentStart`/`SubagentStop` are left out because Muse fires them every turn for its built-in reminder observers. The `SessionStart` hook delivers the prior session's handoff through `hookSpecificOutput.additionalContext`, and Muse's own `SessionEnd` closes the session. Verified offline against Muse Code 1.4.7: hook capture, exclusions, MCP session routing and handoff injection, run end to end in an isolated network namespace with a stand-in model provider. Skills need no extra step: Muse reads `~/.agents/skills` and `AGENTS.md`. `setup` detects Muse by its config or data directory. No managed workstream (`ai-memory run muse`) and no transcript backfill. See [`install.md`](install.md#meta-muse-code). || IBM Bob | Supported | Native Streamable HTTP MCP in `~/.bob/settings/mcp.json` plus five lifecycle hooks shared by Bob IDE and Bob Shell in `~/.bob/settings/settings.json`. `SessionStart` injects the prior handoff as plain context, and Claude-shaped tool events enforce capture exclusions. Bob exposes no true `SessionEnd`, so run `ai-memory finalize-session --agent ibm-bob` after the final turn. `ai-memory run ibm-bob` and transcript backfill are not claimed because Bob does not document a stable transcript-store contract. See [`mcp-install.md`](mcp-install.md#ibm-bob). || DeepSeek Harness (DSH) | Hooks + MCP | MCP: `install-mcp --client dsh` (aliases `deepseek-harness`, `deepseek_harness`) prints a Cordis patch fragment (a `- insert:` item for `@deepseek-ai/dsh-mcp-client`) to merge into `$DSH_HOME/profiles/<profile>/cordis.patch.yml`; DSH has no fixed MCP config file, so `--apply` is refused. Lifecycle hooks: `install-hooks --agent dsh` stages the `hooks/dsh` script bundle, generates a Claude Code `hooks.json` for DSH's official `@deepseek-ai/dsh-hooks-claude-code` bridge, and prints the bridge patch fragment — again merged by hand into `cordis.patch.yml` (the generated `hooks.json` itself is written to the data dir by `--apply`). The bridge delivers exactly seven Claude Code events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`, `SubagentStop`) — no `PreCompact` or `SessionEnd` — and runs `SessionStart` detached, so DSH sessions are stored as `agent=dsh`, pending handoffs are recovered via MCP `memory_handoff_list` then `memory_handoff_accept`, and finished sessions close with `ai-memory finalize-session --agent dsh`. No managed workstream. |-| Cline CLI | Hooks + MCP | `install-mcp --client cline --apply` merges Cline's required nested `transport` entry into `${CLINE_MCP_SETTINGS_PATH:-~/.cline/data/settings/cline_mcp_settings.json}` and explicitly selects Streamable HTTP (a bare URL selects legacy SSE). `install-hooks --agent cline --apply` writes the nine supported CLI event files to `~/.cline/hooks` (or project `.cline/hooks` with `--scope project`): task start/resume, prompt, pre/post tool, complete/cancel/error, and shutdown. The generated owner-only files refuse user-owned files and final-component symlinks. Cline starts task hooks detached, so pending handoffs are accepted through MCP; yolo mode disables hooks, and Cline must be restarted after installation. This installs Cline CLI hooks only; the VS Code extension uses a separate `~/Documents/Cline/Hooks` convention. No managed workstream. |+| Cline CLI | Hooks + MCP | `install-mcp --client cline --apply` merges Cline's required top-level `type`, `url`, and optional `headers` fields into `${CLINE_MCP_SETTINGS_PATH:-~/.cline/data/settings/cline_mcp_settings.json}` and explicitly selects Streamable HTTP (a bare URL selects legacy SSE). `install-hooks --agent cline --apply` writes the nine supported CLI event files to `~/.cline/hooks` (or project `.cline/hooks` with `--scope project`): task start/resume, prompt, pre/post tool, complete/cancel/error, and shutdown. The generated owner-only files refuse user-owned files and final-component symlinks. Cline starts task hooks detached, so pending handoffs are accepted through MCP; yolo mode disables hooks, and Cline must be restarted after installation. This installs Cline CLI hooks only; the VS Code extension uses a separate `~/Documents/Cline/Hooks` convention. No managed workstream. || FreeBuff | MCP-only | `install-mcp --client freebuff --apply` merges an `ai-memory mcp-bridge --no-session-id` stdio entry into `~/.agents/mcp.json`. FreeBuff discovers that file from the current directory, its parents, or the home directory and already reads `AGENTS.md`; it has no documented lifecycle-hook or managed-workstream surface. The bridge reaches the configured local or remote server without attempting to start a second server that would contend for the data-dir lock. || Prime Agent | MCP-only | `install-mcp --client prime-agent` merges an HTTP entry (`type: "http"` + `url`) into the `mcpServers` map of `$PRIME_AGENT_CODING_AGENT_DIR/settings.json` (default `~/.prime/agent/settings.json`), preserving other settings and servers; a project's `.prime/agent/settings.json` works through `--config-file`. A token is referenced as `"bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"`, never written: Prime Agent 0.10 counts a user HTTP server as connected and names it in the model's prompt only with that variable set or an OAuth grant. A credential-less entry is still callable through `mcp.call_tool("ai-memory", ...)` but is not listed. The model reaches MCP tools from its Python REPL (`await mcp.call_tool("ai-memory", "memory_query", {...})`), and Prime Agent sends no session id or cwd, so pass `workspace` and `project` on project-scoped calls. Lifecycle capture and managed workstreams are not claimed: Prime Agent 0.10 removed the TypeScript extensions its 0.9 releases had and has no hook surface. Verified against Prime Agent 0.10.0. || Hermes Agent | Supported | `install-hooks --agent hermes` (alias `hermes-agent`) prints a ready-to-paste `hooks:` block for `~/.hermes/config.yaml`. Hermes splits each configured `command` with `shlex.split` and runs it with no shell, passing the event JSON on stdin, so the entries invoke the native `ai-memory hook` command (exec form, like Zero and ZCode — no script bundle is staged); ai-memory never writes that YAML file, which is yours to edit and which Hermes itself gates behind its hook-acceptance prompt (`hooks_auto_accept`). Two tool events are wired, `pre_tool_call` → `pre-tool-use` and `post_tool_call` → `post-tool-use`; their `tool_name` / `tool_input` payload drives concrete session attribution, tool-family titles, and capture exclusions. Hermes reports its own process directory as `cwd`, so the native hook locates each event's `.ai-memory.toml` from the tool's absolute `workdir` (`terminal`) or `path` (file tools, `search_files`); a call with no absolute location stays with the process directory. Session lifecycle (recall, prompt capture, session-end, automatic handoff) is owned by the community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) memory provider, so no hook-driven `session-end` is installed and nothing is duplicated; review that plugin's compatibility matrix, install/uninstall scripts, and secret handling before enabling it. No first-party `install-mcp` client and no managed workstream are claimed yet, and because Hermes ignores session-start hook stdout a pending handoff is recovered through MCP (`memory_handoff_list` then `memory_handoff_accept`). |