diff --git a/docs/docs.json b/docs/docs.json index 88e6f821f..177032753 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -368,6 +368,7 @@ "icon": "terminal", "pages": [ "integrations/claude-code", + "integrations/claude-ai", "integrations/cursor", "integrations/codex", "integrations/opencode", diff --git a/docs/integrations/claude-ai.mdx b/docs/integrations/claude-ai.mdx new file mode 100644 index 000000000..e108e2353 --- /dev/null +++ b/docs/integrations/claude-ai.mdx @@ -0,0 +1,85 @@ +--- +title: Claude.ai +description: "Add persistent memory to Claude.ai with the Mem0 remote MCP server: custom connector setup and native-memory troubleshooting." +--- + +Add persistent memory to [**Claude.ai**](https://claude.ai) (the hosted web app, not Claude Code) using Mem0's remote MCP server. Claude.ai connects to MCP servers over the internet as **custom connectors**; there is no local plugin or hook system here, since chats run in Anthropic's cloud, not on your machine. + +## Prerequisites + +1. A Mem0 Platform account: sign up at app.mem0.ai +2. A Claude.ai account on any plan (free, Pro, Max, Team, or Enterprise) + +You don't need an API key up front: the connector uses browser-based sign-in the first time Claude calls a Mem0 tool (see [Signing in](#signing-in)). + +## Installation + +### Individual accounts (Pro, Max, or free) + +1. Go to **Customize > Connectors** +2. Click **+**, then **Add custom connector** +3. Enter the server URL: `https://mcp.mem0.ai/mcp/` +4. Click **Add** + + + Free-tier accounts are limited to one custom connector. Pro, Max, Team, and Enterprise accounts can add multiple. + + +### Team and Enterprise organizations + +An organization owner registers the connector once for everyone: + +1. Go to **Organization Settings > Connectors** +2. Click **Add**, hover **Custom**, then select **Web** +3. Enter the server URL: `https://mcp.mem0.ai/mcp/` +4. Click **Add** + +Members then connect individually: **Customize > Connectors**, find **mem0**, and click **Connect**. + +### Enabling in a chat + +Connectors are opt-in per conversation. Click the **+** button next to the chat prompt, open **Connectors**, and toggle **mem0** on before you start. + +## Signing in + +The first time Claude calls a Mem0 tool, your browser opens a sign-in prompt to authorize the connector against your Mem0 account. Approve it once; Claude.ai stores and refreshes the resulting token for you. There's no API key to paste into the connector UI itself. + +## What's Included + +| Component | Included | +|-----------|:--------:| +| MCP Server (9 memory tools) | Yes | +| Lifecycle Hooks | No (Claude.ai has no local hook system) | +| Mem0 SDK Skill | No (Claude.ai has no local skills directory) | + +## Available MCP Tools + +| Tool | Description | +|------|-------------| +| `add_memory` | Save text or conversation history for a user/agent | +| `search_memories` | Semantic search across memories with filters | +| `get_memories` | List memories with filters and pagination | +| `get_memory` | Retrieve a specific memory by ID | +| `update_memory` | Overwrite a memory's text by ID | +| `delete_memory` | Delete a single memory by ID | +| `delete_all_memories` | Bulk delete all memories in scope | +| `delete_entities` | Delete a user/agent/app/run entity and its memories | +| `list_entities` | List users/agents/apps/runs stored in Mem0 | + +## Troubleshooting + +- **Claude never calls the mem0 tools, even though the connector shows as connected**: Claude.ai ships its own native memory (Settings > Capabilities > Memory, on by default), which synthesizes a running summary from your chat history automatically. When both are active, Claude's system prompt tends to favor its built-in memory and rarely reaches for a third-party memory tool on its own. Ask explicitly ("search my mem0 memories for...", "save this to mem0") to force the tool call, or pause Claude's native memory (Settings > Capabilities > Memory > Pause) if you want Mem0 to be the primary memory store for that account. +- **"Connection failed" or the connector won't add**: Confirm the URL is exactly `https://mcp.mem0.ai/mcp/`. Custom connectors reach your MCP server from Anthropic's cloud, not your device, so a localhost URL will never work here. +- **No tools appearing after adding the connector**: Make sure you toggled **mem0** on for the current conversation under the **+ > Connectors** menu; adding a connector doesn't enable it in every chat automatically. +- **Can't add a second connector**: Free-tier accounts are capped at one custom connector; upgrade to Pro/Max/Team/Enterprise for more. + + + + Detailed MCP configuration for all clients + + + Add Mem0 memory to Claude Code workflows + + + + diff --git a/docs/integrations/codex.mdx b/docs/integrations/codex.mdx index a93447311..15f9f43c2 100644 --- a/docs/integrations/codex.mdx +++ b/docs/integrations/codex.mdx @@ -91,12 +91,23 @@ To update, run `codex plugin marketplace upgrade` to pull the latest from the Me After either option, start a new Codex task and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set. +## Codex Cloud + +[Codex Cloud](https://developers.openai.com/codex/cloud/environments) tasks run setup scripts and the agent in separate phases with different variable scoping: + +- **Environment Variables** persist for the full duration of the task, through both the setup script and the agent phase. +- **Secrets** are only available to the setup script; they are wiped before the agent phase starts, so the agent itself cannot read them. + +Because the `mem0` MCP server authenticates on every tool call the agent makes (not just during setup), set `MEM0_API_KEY` as an **Environment Variable** in your Codex Cloud environment configuration, not as a Secret. A Secret will let a setup script authenticate but the agent will lose access to `MEM0_API_KEY` once the task phase begins, breaking Mem0 MCP calls. + +Lifecycle hooks that shell out to local scripts (Option A) are not applicable in Codex Cloud's ephemeral containers; use Option B (Direct MCP) with `MEM0_API_KEY` set as above. + ## What's Included | Component | Plugin Install | MCP Only | |-----------|:--------------:|:--------:| | MCP Server (9 memory tools) | Yes | Yes | -| Lifecycle Hooks | Yes | No | +| Lifecycle Hooks | Opt-in (see below) | No | | Mem0 SDK Skill | Yes | No | ## Available MCP Tools @@ -117,7 +128,22 @@ Once installed, the following tools are available in every Codex session: ## Lifecycle Hooks -When installed via the plugin marketplace, Mem0 hooks into Codex's lifecycle to automatically manage memory: +Unlike Claude Code, Codex has no plugin-host mechanism for auto-wiring hooks from an installed plugin: it only reads hooks from `~/.codex/hooks.json` (or `/.codex/hooks.json`). Installing the plugin (Option A) does **not** turn hooks on by itself. To enable them, run the bundled installer once against your local clone: + +```bash +python3 /integrations/mem0-plugin/scripts/install_codex_hooks.py +``` + +This merges Mem0's entries into `~/.codex/hooks.json` and is idempotent (safe to re-run after upgrading). It also requires the `codex_hooks` feature flag in `~/.codex/config.toml`: + +```toml +[features] +codex_hooks = true +``` + +The installer prints a reminder if the flag isn't set. Restart Codex after installing hooks or editing the config. To remove: `python3 .../install_codex_hooks.py --uninstall`. + +Once enabled, Mem0 hooks into Codex's lifecycle to automatically manage memory: | Hook | Event | What it does | |------|-------|-------------| @@ -155,7 +181,7 @@ You: Add WebSocket support for real-time notification delivery. - **"Connection failed"**: Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY` - **No tools appearing**: Restart your Codex session after installation - **Duplicate `mem0` MCP / "tool collision" errors**: You combined Option A with Option B. Remove the `[mcp_servers.mem0]` block from `~/.codex/config.toml`; the plugin registers it automatically -- **Hooks not firing**: Ensure the plugin is installed via the marketplace (Option A). MCP-only installs do not include hooks +- **Hooks not firing**: Hooks are opt-in and are not installed by the marketplace install itself. Run `scripts/install_codex_hooks.py` (see [Lifecycle Hooks](#lifecycle-hooks)), confirm `codex_hooks = true` is set under `[features]` in `~/.codex/config.toml`, and restart Codex. MCP-only installs (Option B) never include hooks diff --git a/docs/llms.txt b/docs/llms.txt index eee7abe5a..61f135a5d 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -265,6 +265,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or a Platform call st ### AI Coding Tools - [Claude Code](https://docs.mem0.ai/integrations/claude-code) [Both]: Use when wiring memory into Claude Code. +- [Claude.ai](https://docs.mem0.ai/integrations/claude-ai) [Platform]: Use when connecting Mem0 to Claude.ai (the hosted web app) via a custom remote MCP connector, or when Claude's native memory seems to be crowding out mem0 tool calls. - [Cursor](https://docs.mem0.ai/integrations/cursor) [Platform]: Use when wiring memory into Cursor. - [Codex](https://docs.mem0.ai/integrations/codex) [Platform]: Use when wiring memory into Codex / other editor assistants. - [OpenCode](https://docs.mem0.ai/integrations/opencode) [Platform]: Use when wiring memory into OpenCode. diff --git a/integrations/mem0-plugin/.cursor-plugin/plugin.json b/integrations/mem0-plugin/.cursor-plugin/plugin.json index cdceabb02..550a3c569 100644 --- a/integrations/mem0-plugin/.cursor-plugin/plugin.json +++ b/integrations/mem0-plugin/.cursor-plugin/plugin.json @@ -13,5 +13,5 @@ "keywords": ["mem0", "memory", "mcp", "personalization", "semantic-search"], "skills": "./skills/", "hooks": "./hooks/cursor-hooks.json", - "mcpServers": ".cursor-mcp.json" + "mcpServers": "./.cursor-mcp.json" } diff --git a/integrations/mem0-plugin/README.md b/integrations/mem0-plugin/README.md index 1481597cc..ad30b074b 100644 --- a/integrations/mem0-plugin/README.md +++ b/integrations/mem0-plugin/README.md @@ -100,13 +100,16 @@ This points Codex at the repo's `.agents/plugins/marketplace.json`, which refere python3 ~/codex-plugins/mem0-source/integrations/mem0-plugin/scripts/install_codex_hooks.py ``` -This merges three entries into `~/.codex/hooks.json` with absolute paths pointing into your clone: +This merges six event handlers into `~/.codex/hooks.json` with absolute paths pointing into your clone: | Event | What it does | |-------|--------------| | `SessionStart` | Loads prior memories as bootstrap context | | `UserPromptSubmit` | Injects relevant memories into the prompt | +| `PreToolUse` (3 handlers) | Blocks MEMORY.md writes; enforces `user_id`/`app_id` on mem0 tool calls; scans files being read for relevant memory context | +| `PostToolUse` (2 handlers) | Tracks stats, scans bash errors for related memories | | `Stop` | Reminds the agent to persist learnings at turn end | +| `PreCompact` | Stores a summary before the context is compacted | Re-running the installer is idempotent (replaces the Mem0 entries rather than duplicating) and preserves any other hooks you have. To remove: `python3 .../install_codex_hooks.py --uninstall`. If you move or delete the clone directory, re-run the installer from the new location — the hooks file stores absolute paths. diff --git a/integrations/mem0-plugin/hooks.json b/integrations/mem0-plugin/hooks.json index 9e631e618..c7b9144b1 100644 --- a/integrations/mem0-plugin/hooks.json +++ b/integrations/mem0-plugin/hooks.json @@ -7,13 +7,13 @@ { "name": "mem0-ensure-deps", "type": "command", - "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/ensure_deps.sh 2>/dev/null || true", + "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/ensure_deps.sh || true", "timeout": 60 }, { "name": "mem0-session-start", "type": "command", - "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/on_session_start.sh 2>/dev/null || true" + "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/on_session_start.sh || true" } ] } @@ -24,7 +24,7 @@ { "name": "mem0-user-prompt", "type": "command", - "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/on_user_prompt.sh 2>/dev/null || true", + "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/on_user_prompt.sh || true", "timeout": 8 } ] diff --git a/integrations/mem0-plugin/scripts/install_codex_hooks.py b/integrations/mem0-plugin/scripts/install_codex_hooks.py index ac77c8221..c94ef1561 100755 --- a/integrations/mem0-plugin/scripts/install_codex_hooks.py +++ b/integrations/mem0-plugin/scripts/install_codex_hooks.py @@ -150,7 +150,7 @@ def main() -> int: print(f"Installed Mem0 hooks into {HOOKS_FILE}") print(f"Plugin path: {PLUGIN_ROOT}") - print("Events: PreToolUse, SessionStart, UserPromptSubmit, PostToolUse") + print("Events: PreToolUse, SessionStart, UserPromptSubmit, PostToolUse, Stop, PreCompact") if not feature_flag_enabled(): print_feature_flag_hint()