Skip to content

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.md
index 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 keys
ai-memory works in three intensity tiers. **The default Docker run is
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.md
new file mode 100644
index 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.