docs: merge guidance + per-host shapes for MCP install snippets

README.md

@@ -345,13 +345,16 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
 <summary><b>OpenClaw (paste this prompt)</b></summary>
 
 ```
-Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 43 memory tools:
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 51 memory tools:
 
 {
   "mcpServers": {
     "agentmemory": {
       "command": "npx",
-      "args": ["-y", "@agentmemory/mcp"]
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
     }
   }
 }
@@ -367,7 +370,7 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/)
 <summary><b>Hermes Agent (paste this prompt)</b></summary>
 
 ```
-Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 43 memory tools:
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 51 memory tools:
 
 mcp_servers:
   agentmemory:
@@ -388,21 +391,37 @@ Full guide: [`integrations/hermes/`](integrations/hermes/)
 
 Start the memory server: `npx @agentmemory/agentmemory`
 
-Then add the MCP config for your agent:
+The agentmemory entry is the **same MCP server block** across every host that uses the `mcpServers` shape (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
 
-| Agent | Setup |
-|---|---|
-| **Cursor** | Add to `~/.cursor/mcp.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` |
-| **OpenClaw** | Add to MCP config: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` or use the [memory plugin](integrations/openclaw/) |
-| **Gemini CLI** | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` |
-| **Codex CLI** | `codex mcp add agentmemory -- npx -y @agentmemory/mcp` or add `[mcp_servers.agentmemory]` to `.codex/config.toml` |
-| **pi** | Copy [`integrations/pi`](integrations/pi/) to `~/.pi/agent/extensions/agentmemory` and restart pi |
-| **OpenCode** | Add to `opencode.json`: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}` |
-| **Hermes Agent** | Add to `~/.hermes/config.yaml` with `memory.provider: agentmemory` or use the [memory provider plugin](integrations/hermes/) |
-| **Cline / Goose / Kilo Code** | Add MCP server in settings |
-| **Claude Desktop** | Add to `claude_desktop_config.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` |
-| **Aider** | REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'` |
-| **Any agent (32+)** | `npx skillkit install agentmemory` |
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "http://localhost:3111"
+  }
+}
+```
+
+**Merge this entry into the existing `mcpServers` object** in the host's config file — don't replace the file. If the file already has other servers, add `agentmemory` next to them as another key inside `mcpServers`. If `mcpServers` is missing entirely, paste the block inside `{ "mcpServers": { ... } }`.
+
+| Agent | Config file | Notes |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | Merge into `mcpServers`. One-click deeplink also available on the website. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Merge into `mcpServers`. Restart Claude Desktop after editing. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Same `mcpServers` block. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Same `mcpServers` block. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges). |
+| **OpenClaw** | OpenClaw MCP config | Same `mcpServers` block, or use the deeper [memory plugin](integrations/openclaw/). |
+| **Codex CLI** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually. |
+| **OpenCode** | `opencode.json` | Different shape — top-level `mcp` key, command as array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Copy [`integrations/pi`](integrations/pi/) and restart pi. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Use the deeper [memory provider plugin](integrations/hermes/) with `memory.provider: agentmemory`. |
+| **Goose** | Goose MCP settings UI | Same `mcpServers` block. |
+| **Aider** | n/a | Talk to the REST API directly: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Any agent (32+)** | n/a | `npx skillkit install agentmemory` auto-detects the host and merges. |
+
+**Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP). See [#234](https://github.com/rohitg00/agentmemory/issues/234) for the diagnostic walkthrough.
 
 ### From source
 
@@ -701,18 +720,23 @@ npx -y @agentmemory/mcp                # shim package alias
 
 Or add to your agent's MCP config:
 
-Most agents (Cursor, Claude Desktop, Cline, etc.):
+Most agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
 ```json
 {
   "mcpServers": {
     "agentmemory": {
       "command": "npx",
-      "args": ["-y", "@agentmemory/mcp"]
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
     }
   }
 }
 ```
 
+Merge the `agentmemory` entry into your host's existing `mcpServers` object rather than replacing the file. For sandboxed clients that can't reach the host's `localhost`, add `"AGENTMEMORY_FORCE_PROXY": "1"` to the env block and set `AGENTMEMORY_URL` to a route the sandbox can reach.
+
 OpenCode (`opencode.json`):
 ```json
 {

website/components/AgentInstall.tsx

@@ -22,6 +22,32 @@ args    = ["-y", "@agentmemory/mcp"]
 [mcp_servers.agentmemory.env]
 AGENTMEMORY_URL = "http://localhost:3111"`;
 
+const OPENCODE_JSON = `{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true,
+      "environment": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}`;
+
+const VSCODE_MCP_JSON = `{
+  "servers": {
+    "agentmemory": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}`;
+
 const CLAUDE_CODE_CMD = `claude mcp add agentmemory -- npx -y @agentmemory/mcp`;
 
 const HERMES_YAML = `plugins:
@@ -243,7 +269,7 @@ export function AgentInstall() {
         <div className={styles.snippetCol}>
           <Snippet
             title="UNIVERSAL MCP JSON"
-            hint="WORKS FOR CLAUDE DESKTOP · CURSOR · CLINE · WINDSURF · GEMINI CLI · OPENCODE"
+            hint="WORKS FOR CLAUDE DESKTOP · CURSOR · CLINE · ROO CODE · WINDSURF · GEMINI CLI — MERGE INTO EXISTING mcpServers"
             body={UNIVERSAL_JSON}
           />
         </div>
@@ -254,11 +280,26 @@ export function AgentInstall() {
         aria-expanded={showMore}
         onClick={() => setShowMore((v) => !v)}
       >
-        {showMore ? "— HIDE OTHER SHAPES" : "+ HERMES · OPENCLAW · MORE"}
+        {showMore ? "— HIDE OTHER SHAPES" : "+ OPENCODE · VS CODE · CODEX · HERMES · OPENCLAW"}
       </button>
 
       {showMore && (
         <div className={styles.moreGrid}>
+          <Snippet
+            title="OPENCODE"
+            hint="opencode.json — different shape (mcp key, command as array)"
+            body={OPENCODE_JSON}
+          />
+          <Snippet
+            title="VS CODE (mcp.json)"
+            hint=".vscode/mcp.json — uses servers key, not mcpServers"
+            body={VSCODE_MCP_JSON}
+          />
+          <Snippet
+            title="CODEX CLI (TOML)"
+            hint="~/.codex/config.toml"
+            body={CODEX_TOML}
+          />
           <Snippet
             title="HERMES"
             hint="integrations/hermes — plugin.yaml"
@@ -269,11 +310,6 @@ export function AgentInstall() {
             hint="integrations/openclaw — plugin.yaml"
             body={OPENCLAW_YAML}
           />
-          <Snippet
-            title="CODEX CLI (TOML)"
-            hint="~/.codex/config.toml"
-            body={CODEX_TOML}
-          />
         </div>
       )}
     </div>

website/lib/generated-meta.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.9.3",
+  "version": "0.9.7",
   "mcpTools": 51,
   "hooks": 12,
-  "restEndpoints": 120,
-  "testsPassing": 848,
-  "generatedAt": "2026-04-24T16:10:22.169Z"
+  "restEndpoints": 121,
+  "testsPassing": 880,
+  "generatedAt": "2026-05-11T13:23:24.696Z"
 }