From c5c8a06fca0f1ad98d33dfc23e6a1ffe4f549bfd Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Mon, 11 May 2026 14:24:33 +0100 Subject: [PATCH] docs: merge guidance + per-host shapes for MCP install snippets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Real-world failure mode: users paste the README's universal mcpServers JSON into an existing config file (e.g. ~/.cursor/mcp.json with firecrawl/linear/drawio already wired) and end up with two top-level objects, breaking the host's MCP loader with "Expected double-quoted property name in JSON at position 386". Plus the README doesn't tell them where each host actually reads its config from, doesn't include the AGENTMEMORY_URL env block that the website snippet ships, and quotes a stale "43 memory tools" count in the OpenClaw and Hermes paste-prompts (the server has been at 51 since the v0.7 essential-set expansion). This commit fixes the install copy on README and website together so the two don't drift again. README: - Replace per-host table with a single canonical agentmemory block that includes the AGENTMEMORY_URL env (matches the website's UNIVERSAL_JSON), plus an explicit "merge into existing mcpServers, do not replace the file" line. - Per-host table now lists exact config file path per host (e.g. ~/.cursor/mcp.json, claude_desktop_config.json, ~/.codeium/windsurf/mcp_config.json, ~/.gemini/settings.json) and flags the non-mcpServers shapes (OpenCode uses mcp + array command; Codex uses TOML). - Adds Roo Code and Windsurf (previously absent), keeps Cline / Goose / Kilo Code / pi / Hermes / OpenClaw / Aider. - Adds sandboxed-client paragraph pointing AGENTMEMORY_FORCE_PROXY=1 + AGENTMEMORY_URL= at the v0.9.7 escape hatch (closes the Flatpak / Snap repro from #234). - Stale "43 memory tools" -> "51 memory tools" in the OpenClaw and Hermes paste-prompt blocks. - OpenClaw paste-prompt JSON now ships the env block too. - The "Standalone MCP" section's universal JSON ships AGENTMEMORY_URL and lists Roo Code + Windsurf + Gemini CLI alongside Cursor / Claude Desktop / Cline. Website (AgentInstall.tsx): - "WORKS FOR CLAUDE DESKTOP · CURSOR · CLINE · WINDSURF · GEMINI CLI · OPENCODE" -> "CLAUDE DESKTOP · CURSOR · CLINE · ROO CODE · WINDSURF · GEMINI CLI — MERGE INTO EXISTING mcpServers". OpenCode does NOT use mcpServers (top-level `mcp` key, command-as-array, `environment` rather than `env`), so removing it from the universal label. - Adds an OPENCODE snippet with the correct `mcp` shape and `environment.AGENTMEMORY_URL`. - Adds a VS CODE (mcp.json) snippet — VS Code's .vscode/mcp.json uses `servers` (not `mcpServers`), `type: "stdio"`, and the standard `env`. The vscode:mcp/install deeplink already worked via its own flat config shape; this snippet covers the copy-JSON path for VS Code users editing mcp.json by hand. - "+ HERMES · OPENCLAW · MORE" toggle relabeled to "+ OPENCODE · VS CODE · CODEX · HERMES · OPENCLAW" so the catalog is visible before opening it. No new dependencies. Website typechecks and builds clean (Next 16 App Router, static export). Repo tests 859/859. --- README.md | 62 ++++++++++++++++++++--------- website/components/AgentInstall.tsx | 50 +++++++++++++++++++---- website/lib/generated-meta.json | 8 ++-- 3 files changed, 90 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 1ee96e11..6693b7cf 100644 --- a/README.md +++ b/README.md @@ -345,13 +345,16 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t OpenClaw (paste this prompt) ``` -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/) Hermes Agent (paste this prompt) ``` -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 { diff --git a/website/components/AgentInstall.tsx b/website/components/AgentInstall.tsx index 293db2c9..35c33ad4 100644 --- a/website/components/AgentInstall.tsx +++ b/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() {
@@ -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"} {showMore && (
+ + + -
)} diff --git a/website/lib/generated-meta.json b/website/lib/generated-meta.json index 10ccfb93..6a2af48a 100644 --- a/website/lib/generated-meta.json +++ b/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" }