Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
M14: install-mcp subcommand + docs/mcp-install.md for 5 more clients
AkitaOnRails8d8b2a79f151
diff --git a/README.md b/README.mdindex 4a0df650..211b8ec0 100644--- a/README.md+++ b/README.md@@ -118,6 +118,28 @@ url = "http://127.0.0.1:49374/mcp"~/.ai-memory/target/release/ai-memory install-hooks --agent opencode```+### Other MCP clients — Cursor, Claude Desktop, Gemini CLI, OpenClaw, pi++These clients don't currently have lifecycle-hook bundles in+`hooks/`, but ai-memory still works with them via MCP. See+[**`docs/mcp-install.md`**](docs/mcp-install.md) for the per-client+config-file path and snippet.++Quick reference:++```bash+ai-memory install-mcp --client cursor # ~/.cursor/mcp.json+ai-memory install-mcp --client claude-desktop # Claude Desktop config+ai-memory install-mcp --client gemini-cli # ~/.gemini/settings.json+ai-memory install-mcp --client openclaw # ~/.openclaw/config.json+ai-memory install-mcp --client pi # prints why pi is not MCP-supported+```++The MCP-only clients get the read/query side (the LLM can call+`memory_query`, `memory_recent`, `memory_handoff_accept`), but not+auto-capture — you nudge the model to call those tools yourself+(see [the CLAUDE.md snippet](#nudging-the-agent-to-use-memory-proactively)).+## LLM provider, models, and API keysai-memory works in three intensity tiers. **The default Docker run isdiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 808cf8ed..b741dfa4 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -47,6 +47,10 @@ pub enum Command {Restore(RestoreArgs),/// Print (or apply) lifecycle-hook configuration for an agent CLI.InstallHooks(InstallHooksArgs),+ /// Print MCP server registration snippets for any supported client+ /// (Claude Code, Codex, OpenCode, Cursor, Claude Desktop, Gemini+ /// CLI, OpenClaw, pi). See docs/mcp-install.md for the full guide.+ InstallMcp(InstallMcpArgs),/// Stage + commit the wiki tree under git.Commit(CommitArgs),/// Smoke-test an LLM provider by sending one prompt.@@ -126,7 +130,9 @@ pub struct RestoreArgs {pub force: bool,}-/// Agent CLI to install hooks for.+/// Agent CLI to install hooks for. Only the three with lifecycle+/// hooks are listed; for MCP-only clients (Cursor, Claude Desktop,+/// Gemini CLI, OpenClaw), use `install-mcp --client <name>` instead.#[derive(Debug, Clone, Copy, clap::ValueEnum)]pub enum AgentChoice {/// Anthropic Claude Code.@@ -137,6 +143,33 @@ pub enum AgentChoice {OpenCode,}+/// 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+/// clients researched in docs/mcp-install.md.+#[derive(Debug, Clone, Copy, clap::ValueEnum)]+pub enum McpClient {+ /// Anthropic Claude Code — `claude mcp add`.+ ClaudeCode,+ /// OpenAI Codex CLI — `~/.codex/config.toml`.+ Codex,+ /// OpenCode — `opencode.json`.+ OpenCode,+ /// Cursor IDE — `~/.cursor/mcp.json` or `.cursor/mcp.json`.+ Cursor,+ /// Anthropic Claude Desktop — uses the `mcp-remote` stdio shim+ /// to talk to ai-memory's HTTP endpoint (Claude Desktop's JSON+ /// config does not register HTTP transports directly).+ ClaudeDesktop,+ /// Google Gemini CLI — `~/.gemini/settings.json`.+ GeminiCli,+ /// OpenClaw personal AI gateway — `~/.openclaw/config.json`.+ Openclaw,+ /// Mario Zechner's `pi` coding agent. NOT supported via MCP+ /// upstream; this prints the explanation + alternatives.+ Pi,+}+/// Arguments for `commit`.#[derive(Debug, Args)]pub struct CommitArgs {@@ -231,6 +264,20 @@ pub struct InstallHooksArgs {pub server_url: String,}+/// Arguments for `install-mcp`.+#[derive(Debug, Args)]+pub struct InstallMcpArgs {+ /// Which MCP client to render configuration for.+ #[arg(long, value_enum, default_value_t = McpClient::ClaudeCode)]+ pub client: McpClient,+ /// MCP HTTP endpoint URL the client should connect to.+ #[arg(long, default_value = "http://127.0.0.1:49374/mcp")]+ pub server_url: String,+ /// Friendly name the client should show for this server entry.+ #[arg(long, default_value = "ai-memory")]+ pub name: String,+}+/// Transport for the MCP server.#[derive(Debug, Clone, Copy, clap::ValueEnum)]pub enum TransportKind {diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rsnew file mode 100644index 00000000..f2a08b56--- /dev/null+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs@@ -0,0 +1,270 @@+//! `ai-memory install-mcp` — print the MCP server registration+//! snippet for any supported client.+//!+//! The snippet format and the config-file location differ across+//! clients. We render the *content* the user needs to paste; we+//! deliberately do not auto-edit their config (formats are evolving+//! upstream and a bad merge is very user-visible).+//!+//! For clients that don't support remote MCP servers in their JSON+//! config (Claude Desktop today), the rendered snippet uses the+//! community-standard `npx mcp-remote` stdio shim so the same HTTP+//! endpoint still works.+//!+//! For clients that don't support MCP at all (`pi` per the upstream+//! author's stated position), we print an explanation + pointers+//! instead of fabricating a config.++use anyhow::Result;+use serde_json::json;++use crate::cli::{InstallMcpArgs, McpClient};+use crate::config::Config;++/// Run the `install-mcp` subcommand.+///+/// # Errors+/// Returns an error if JSON serialisation fails (should never happen+/// for our handcrafted values).+pub fn run(_config: &Config, args: InstallMcpArgs) -> Result<()> {+ let snippet = match args.client {+ McpClient::ClaudeCode => render_claude_code(&args)?,+ McpClient::Codex => render_codex(&args),+ McpClient::OpenCode => render_opencode(&args)?,+ McpClient::Cursor => render_cursor(&args)?,+ McpClient::ClaudeDesktop => render_claude_desktop(&args)?,+ McpClient::GeminiCli => render_gemini_cli(&args)?,+ McpClient::Openclaw => render_openclaw(&args)?,+ McpClient::Pi => render_pi_explanation(&args),+ };+ println!("{snippet}");+ Ok(())+}++fn render_claude_code(args: &InstallMcpArgs) -> Result<String> {+ Ok(format!(+ "# Claude Code — register the MCP server\n\+ #\n\+ # Recommended (one-shot CLI):\n\+ claude mcp add --transport http {name} {url}\n\+ #\n\+ # Equivalent JSON if you'd rather edit settings directly\n\+ # (~/.claude/settings.json):\n\+ {snippet}\n",+ name = args.name,+ url = args.server_url,+ snippet = serde_json::to_string_pretty(&json!({+ "mcpServers": {+ args.name.as_str(): {+ "type": "http",+ "url": args.server_url,+ }+ }+ }))?,+ ))+}++fn render_codex(args: &InstallMcpArgs) -> String {+ // Codex uses TOML, not JSON. Hand-render the snippet so the+ // table headers stay deterministic.+ format!(+ "# Codex CLI — append to ~/.codex/config.toml\n\+ #\n\+ [mcp_servers.{name}]\n\+ url = \"{url}\"\n",+ name = args.name,+ url = args.server_url,+ )+}++fn render_opencode(args: &InstallMcpArgs) -> Result<String> {+ Ok(format!(+ "# OpenCode — add to ~/.config/opencode/opencode.json under \"mcp\":\n\+ {snippet}\n",+ snippet = serde_json::to_string_pretty(&json!({+ "mcp": {+ args.name.as_str(): {+ "type": "remote",+ "url": args.server_url,+ "enabled": true,+ }+ }+ }))?,+ ))+}++fn render_cursor(args: &InstallMcpArgs) -> Result<String> {+ Ok(format!(+ "# Cursor — write to one of:\n\+ # - ~/.cursor/mcp.json (global, all projects)\n\+ # - .cursor/mcp.json (per-project, in the workspace root)\n\+ #\n\+ # Cursor supports HTTP MCP servers via the `url` field. Restart\n\+ # Cursor (or toggle the server off+on in Settings → MCP) after\n\+ # adding a new entry; live reload landed in recent builds but\n\+ # is still flaky.\n\+ {snippet}\n",+ snippet = serde_json::to_string_pretty(&json!({+ "mcpServers": {+ args.name.as_str(): {+ "url": args.server_url,+ }+ }+ }))?,+ ))+}++fn render_claude_desktop(args: &InstallMcpArgs) -> Result<String> {+ Ok(format!(+ "# Claude Desktop — write to claude_desktop_config.json:\n\+ # - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n\+ # - Windows: %APPDATA%\\Claude\\claude_desktop_config.json\n\+ # - Linux: Claude Desktop is not officially distributed for Linux;\n\+ # use Claude Code or another HTTP client instead.\n\+ #\n\+ # Claude Desktop's JSON config does not support HTTP MCP servers\n\+ # directly. We bridge through the community `mcp-remote` stdio shim\n\+ # (https://www.npmjs.com/package/mcp-remote). Requires Node.js.\n\+ # After editing, fully quit + relaunch Claude Desktop; \"Check for\n\+ # Updates\" is not enough.\n\+ {snippet}\n",+ snippet = serde_json::to_string_pretty(&json!({+ "mcpServers": {+ args.name.as_str(): {+ "command": "npx",+ "args": ["-y", "mcp-remote", args.server_url.as_str()],+ }+ }+ }))?,+ ))+}++fn render_gemini_cli(args: &InstallMcpArgs) -> Result<String> {+ Ok(format!(+ "# Gemini CLI — merge into ~/.gemini/settings.json:\n\+ #\n\+ # Gemini CLI uses `httpUrl` (not `url`) for streamable-HTTP\n\+ # endpoints. The `timeout` is in milliseconds.\n\+ {snippet}\n",+ snippet = serde_json::to_string_pretty(&json!({+ "mcpServers": {+ args.name.as_str(): {+ "httpUrl": args.server_url,+ "timeout": 5000,+ }+ }+ }))?,+ ))+}++fn render_openclaw(args: &InstallMcpArgs) -> Result<String> {+ Ok(format!(+ "# OpenClaw — merge into ~/.openclaw/config.json:\n\+ #\n\+ # OpenClaw distinguishes transports explicitly. Use\n\+ # \"transport\": \"streamable-http\" for ai-memory's HTTP endpoint.\n\+ {snippet}\n",+ snippet = serde_json::to_string_pretty(&json!({+ "mcp": {+ "servers": {+ args.name.as_str(): {+ "url": args.server_url,+ "transport": "streamable-http",+ }+ }+ }+ }))?,+ ))+}++fn render_pi_explanation(_args: &InstallMcpArgs) -> String {+ // No JSON to print. Plain-text explanation + pointers; mirrors+ // the docs/mcp-install.md#pi section so the help is self-contained.+ "# pi (@mariozechner/pi-coding-agent) — NOT supported via MCP\n\+ #\n\+ # pi's author has stated MCP support is not on the roadmap; see\n\+ # https://mariozechner.at/posts/2025-11-30-pi-coding-agent/ for the\n\+ # design rationale (token-budget concerns). agentmemory itself uses\n\+ # pi's native extension surface instead of MCP.\n\+ #\n\+ # Options if you want ai-memory + pi:\n\+ # 1. Run ai-memory and use it from another client (Claude Code,\n\+ # Codex, Cursor, Gemini CLI) for the cross-agent handoff;\n\+ # keep pi for code-edit sessions you don't need to persist.\n\+ # 2. Use the third-party `pi-mcp-adapter` shim\n\+ # (https://github.com/nicobailon/pi-mcp-adapter) — unofficial,\n\+ # community-maintained, may break on pi updates.\n\+ #\n\+ # See docs/mcp-install.md#pi-not-supported for the full discussion.\n"+ .to_string()+}++#[cfg(test)]+mod tests {+ use super::*;++ fn args_for(client: McpClient) -> InstallMcpArgs {+ InstallMcpArgs {+ client,+ server_url: "http://127.0.0.1:49374/mcp".into(),+ name: "ai-memory".into(),+ }+ }++ /// Sanity: every supported client renders without error and the+ /// output mentions the configured server URL (or, for pi, the+ /// "not supported" verbiage).+ #[test]+ fn every_client_renders() {+ for client in [+ McpClient::ClaudeCode,+ McpClient::Codex,+ McpClient::OpenCode,+ McpClient::Cursor,+ McpClient::ClaudeDesktop,+ McpClient::GeminiCli,+ McpClient::Openclaw,+ McpClient::Pi,+ ] {+ let out = render_for_test(client);+ if matches!(client, McpClient::Pi) {+ assert!(+ out.contains("NOT supported"),+ "pi must explain non-support: {out}"+ );+ } else {+ assert!(+ out.contains("http://127.0.0.1:49374/mcp"),+ "client {client:?} did not include the server URL in output:\n{out}"+ );+ }+ }+ }++ fn render_for_test(client: McpClient) -> String {+ let args = args_for(client);+ match args.client {+ McpClient::ClaudeCode => render_claude_code(&args).unwrap(),+ McpClient::Codex => render_codex(&args),+ McpClient::OpenCode => render_opencode(&args).unwrap(),+ McpClient::Cursor => render_cursor(&args).unwrap(),+ McpClient::ClaudeDesktop => render_claude_desktop(&args).unwrap(),+ McpClient::GeminiCli => render_gemini_cli(&args).unwrap(),+ McpClient::Openclaw => render_openclaw(&args).unwrap(),+ McpClient::Pi => render_pi_explanation(&args),+ }+ }++ /// Specific shape checks — each client has a distinguishing key+ /// in its JSON snippet. This catches accidental cross-pollination+ /// between renderers (e.g. Gemini's `httpUrl` showing up under+ /// Cursor's `mcpServers`).+ #[test]+ fn client_specific_shape_keys() {+ assert!(render_for_test(McpClient::Cursor).contains("\"url\""));+ assert!(render_for_test(McpClient::GeminiCli).contains("\"httpUrl\""));+ assert!(render_for_test(McpClient::ClaudeDesktop).contains("mcp-remote"));+ assert!(render_for_test(McpClient::Openclaw).contains("\"streamable-http\""));+ assert!(render_for_test(McpClient::Codex).contains("[mcp_servers.ai-memory]"));+ }+}diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex bcad8456..70631813 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -6,6 +6,7 @@ pub mod embed;pub mod forget_sweep;pub mod init;pub mod install_hooks;+pub mod install_mcp;pub mod lint;pub mod llm_test;pub mod reset;diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rsindex 5d53107d..c193fa2b 100644--- a/crates/ai-memory-cli/src/main.rs+++ b/crates/ai-memory-cli/src/main.rs@@ -47,6 +47,7 @@ async fn main() -> Result<()> {Command::Backup(args) => commands::backup::run(&config, args).await,Command::Restore(args) => commands::restore::run(&config, args),Command::InstallHooks(args) => commands::install_hooks::run(&config, args),+ Command::InstallMcp(args) => commands::install_mcp::run(&config, args),Command::Commit(args) => commands::commit::run(&config, args),Command::LlmTest(args) => commands::llm_test::run(&config, args).await,Command::ForgetSweep(args) => commands::forget_sweep::run(&config, args).await,diff --git a/docs/mcp-install.md b/docs/mcp-install.mdnew file mode 100644index 00000000..9e1e33e5--- /dev/null+++ b/docs/mcp-install.md@@ -0,0 +1,262 @@+# MCP install guide — additional clients++This page documents how to register ai-memory as an MCP server with+the agent CLIs **that are not covered inline in the README**.++The three flagship clients — Claude Code, OpenAI Codex, OpenCode —+have lifecycle-hook scripts under [`hooks/`](../hooks) and are+covered in the [main README](../README.md#configure-your-agent-cli).++The clients on this page are **MCP-only**: they expose long-term+memory to their LLM via ai-memory's MCP tools (`memory_query`,+`memory_recent`, `memory_handoff_accept`, etc.), but they cannot+auto-capture session events into ai-memory's `/hook` endpoint+without a per-client plugin written upstream. The trade-off:++| | What you get | What you don't get |+|---|---|---|+| **MCP only** | LLM can query the wiki, accept handoffs, run memory_consolidate | No automatic session-end summaries; no auto-handoff at session boundaries |+| **MCP + hooks** | All of the above *plus* every prompt/tool-call captured automatically; handoffs surface at SessionStart with no human prompting | — |++Most of these clients will land hook integration upstream eventually+(Gemini CLI is the closest); for now, you can still cover the+session-boundary gap by asking the LLM to call `memory_handoff_begin`+manually before quitting.++> **One-shot tip:** every snippet below is also reachable from the+> CLI:+> ```bash+> ai-memory install-mcp --client cursor # or claude-desktop / gemini-cli / openclaw / pi+> ```++---++## Cursor++**Status:** ✅ MCP supported. ❌ No lifecycle hooks.++**Config file:**+- Per-project: `.cursor/mcp.json` in the workspace root.+- Global: `~/.cursor/mcp.json`.++```json+{+ "mcpServers": {+ "ai-memory": {+ "url": "http://127.0.0.1:49374/mcp"+ }+ }+}+```++**Gotchas:**+- Cursor uses the `url` key for HTTP/SSE transports. Stdio uses+ `command` + `args` instead.+- After editing `mcp.json`, restart Cursor or toggle the server+ off+on in **Settings → MCP**. Live reload is in newer builds but+ still occasionally requires a manual restart.+- Source: <https://cursor.com/docs/context/mcp>++---++## Claude Desktop++**Status:** ✅ MCP supported (via stdio shim for HTTP). ❌ No lifecycle hooks.++**Config file:**+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`+- Linux: not officially distributed by Anthropic. Use Claude Code+ (terminal) instead.++**Important:** Claude Desktop's JSON config supports stdio MCP+servers only. To talk to ai-memory's HTTP endpoint, bridge through+the community [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)+stdio shim. Requires Node.js installed on the same machine.++```json+{+ "mcpServers": {+ "ai-memory": {+ "command": "npx",+ "args": ["-y", "mcp-remote", "http://127.0.0.1:49374/mcp"]+ }+ }+}+```++**Gotchas:**+- After editing the config, **fully quit and relaunch** Claude+ Desktop. "Check for Updates…" is not enough.+- If the MCP indicator doesn't appear after restart, check the logs:+ `~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\Claude\logs\`+ (Windows).+- Source: <https://modelcontextprotocol.io/quickstart/user>++---++## Gemini CLI++**Status:** ✅ MCP supported. ⚠️ Hooks exist in the source but are+not yet stable enough to recommend (the user-facing docs are sparse+and event names have shifted between versions). Treat this as+MCP-only for now.++**Config file:**+- User: `~/.gemini/settings.json`+- Project: `.gemini/settings.json`++Gemini CLI uses `httpUrl` (not `url`) for streamable-HTTP MCP+endpoints. The `timeout` is in milliseconds.++```json+{+ "mcpServers": {+ "ai-memory": {+ "httpUrl": "http://127.0.0.1:49374/mcp",+ "timeout": 5000+ }+ }+}+```++**Gotchas:**+- Gemini supports stdio too via `command`/`args`, plus SSE via `url`.+ Only `httpUrl` covers streamable HTTP. Don't mix them in one entry.+- If hooks are surfaced and stabilised upstream, ai-memory will ship+ a Gemini hook bundle in `hooks/gemini-cli/`. Track:+ <https://github.com/google-gemini/gemini-cli>.+- Source: <https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md>++---++## OpenClaw++**Status:** ✅ MCP supported. ⚠️ Hooks exist (TypeScript plugins,+not POSIX shell). Hook integration would need a small TS plugin in+`integrations/openclaw/`; not shipped here.++**Config file:** `~/.openclaw/config.json` (the OpenClaw docs reference+this path indirectly; verify with your `openclaw config show`).++OpenClaw distinguishes transports explicitly. Use+`"transport": "streamable-http"` for ai-memory's HTTP endpoint.++```json+{+ "mcp": {+ "servers": {+ "ai-memory": {+ "url": "http://127.0.0.1:49374/mcp",+ "transport": "streamable-http"+ }+ }+ }+}+```++**Gotchas:**+- OpenClaw config keys under `mcp.*` hot-reload without a gateway+ restart. Hook config changes do require restarting the gateway.+- A TypeScript hook plugin that mirrors the Claude Code hook bundle+ would let OpenClaw auto-capture sessions; until that exists, treat+ OpenClaw as MCP-only.+- Sources: <https://docs.openclaw.ai/cli/mcp>,+ <https://docs.openclaw.ai/automation/hooks>++---++## pi (not supported via MCP) {#pi-not-supported}++**Status:** ❌ MCP not supported upstream. Author Mario Zechner has+[explicitly stated](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/)+that MCP is not on pi's roadmap, citing the token-budget overhead of+typical MCP servers.++The upstream [agentmemory](https://github.com/rohitg00/agentmemory)+project wires pi via pi's own extension surface+(`~/.pi/agent/extensions/agentmemory/`), not MCP. Implementing that+for ai-memory is feasible but would require a separate pi-specific+plugin and is out of scope for ai-memory v0.2.++**What you can do today:**++1. **Best:** run ai-memory and use it from one of the MCP-capable+ clients listed above (Cursor, Claude Desktop, Gemini CLI,+ OpenClaw, or any of the flagship three in the README). Keep pi+ for the code-edit sessions that don't need cross-agent+ continuity. ai-memory's wiki dir is plain markdown; you can open+ it in any editor pi has access to.++2. **Unofficial:** there's a community [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter)+ shim that bridges MCP into pi. Not endorsed by pi's author, may+ break on pi updates. If you try it, point it at ai-memory's+ `http://127.0.0.1:49374/mcp` endpoint.++3. **Future:** open an issue on+ <https://github.com/akitaonrails/ai-memory> requesting a native pi+ extension if there's enough demand. The work is straightforward+ (pi extensions are plain JS); just not prioritised today.++---++## After registering MCP — verify it works++Regardless of which client you used, the first sanity check is the+same: ask the model to list its available MCP tools, or to call+`memory_status` explicitly.++```+You: List the MCP tools you can call. Use one of them to check+ ai-memory's status.++Model (any client): I can call: memory_query, memory_recent,+ memory_status, memory_handoff_accept, memory_handoff_begin,+ memory_consolidate, memory_lint, memory_forget_sweep.+ memory_status reports: 0 pages, 0 observations, 0 sessions.+```++If the model doesn't see any of those tools, the MCP registration+isn't being picked up. Check:++1. **Is the server running?** `curl http://127.0.0.1:49374/mcp` should+ return a JSON-RPC error (not a connection refused). If refused,+ start ai-memory: `docker start ai-memory` or+ `ai-memory serve --transport http`.+2. **Did the client reload the config?** Cursor and Claude Desktop+ need a restart. Gemini CLI and OpenClaw usually pick it up on next+ session-start.+3. **Are you on the right port?** ai-memory's default is **49374**+ (`0xC0DE` in hex). If you remapped, update the URL in every+ client's config.++If the model sees the tools but they all error, the server is+probably running in a different data dir than expected. Check+`docker logs ai-memory` or `ai-memory status --json` for the data+dir on disk.++---++## When does the auto-handoff actually work?++The cross-agent handoff feature (the "headline" pitch in the README)+requires both sides — the agent that *ends* a session, and the agent+that *starts* the next one — to play nicely with ai-memory:++| Side | What's needed | Covered by |+|---|---|---|+| **Ending side** | The `SessionEnd` hook must fire ai-memory's `/hook` endpoint. | Built-in for Claude Code / Codex / OpenCode via the scripts in `hooks/`. |+| **Starting side** | Either (a) the `SessionStart` hook auto-injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (a) is built-in for Claude Code / Codex / OpenCode. (b) works for any MCP-capable client if you nudge the model — see [the CLAUDE.md snippet](../README.md#nudging-the-agent-to-use-memory-proactively). |++So a typical mixed workflow looks like:++- **Claude Code → Cursor.** Claude Code's `SessionEnd` creates the+ handoff automatically. Cursor doesn't have a SessionStart hook, so+ in Cursor's first chat you nudge the model: "Call+ memory_handoff_accept to resume prior work." The model fetches the+ handoff via MCP and continues.+- **Claude Desktop → Claude Code.** Claude Desktop doesn't write a+ handoff (no hooks). To resume in Claude Code, you'd have had to+ call `memory_handoff_begin` manually in Claude Desktop before+ quitting. ai-memory's wiki content via `memory_query` is still+ available either way.