JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: merge origin/main into mintlify/af82bda4 and resolve conflicts

Browse Source
This commit is contained in:
mintlify[bot]
2026-09-16 11:46:52 +00:00
committed by GitHub
parent b5ae772eae
commit 08d9636491
693 changed files with 55668 additions and 22676 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integrations/agentops.mdx
+2 -2
View File
@@ -22,9 +22,9 @@ pip install mem0ai agentops python-dotenv
```
2. Valid API keys:
- [AgentOps API Key](https://app.agentops.ai/dashboard/api-keys)
- [AgentOps API Key](https://app.agentops.ai/projects)
- OpenAI API Key (for LLM operations)
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-agentops" rel="nofollow">Mem0 API Key</a> (optional, for cloud operations)
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-agentops">Mem0 API Key</a> (optional, for cloud operations)
## Basic Integration Example
docs/integrations/agno.mdx
+1 -1
View File
@@ -23,7 +23,7 @@ pip install agno mem0ai python-dotenv
```
2. Valid API keys:
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-agno" rel="nofollow">Mem0 API Key</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-agno">Mem0 API Key</a>
- OpenAI API Key (for the agent model)
## Quick Integration (Using `Mem0Tools`)
docs/integrations/antigravity.mdx
+63 -18
View File
@@ -1,16 +1,22 @@
---
title: Antigravity
description: "Add persistent memory to Google Antigravity with the Mem0 plugin, featuring an MCP server, lifecycle hooks, and slash commands for the agy CLI and IDE."
description: "Add persistent memory to Google Antigravity with the Mem0 plugin: a search tool, lifecycle hooks, and memory skills."
---
Add persistent memory to [**Google Antigravity**](https://antigravity.google) (`agy` CLI and Desktop IDE) with the Mem0 plugin. Your agent forgets everything between sessions. Mem0 fixes that by storing decisions, preferences, and learnings so they carry over automatically.
Add persistent memory to [**Google Antigravity**](https://antigravity.google) (`agy` CLI and Desktop IDE) with the Mem0 plugin. The plugin captures completed work, and Antigravity can search those memories in later sessions.
<Info>Current plugin version: `0.3.1`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent).
## Prerequisites
1. A Mem0 API key (starts with `m0-`):
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-antigravity" rel="nofollow">Get your API key</a> (free sign-up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-antigravity" rel="nofollow">app.mem0.ai</a>)
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-antigravity">Get your API key</a> (free sign-up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-antigravity">app.mem0.ai</a>)
2. Add it to your shell profile so it persists across sessions:
2. Python 3.10 or newer available as `python3`
3. Add the key to your shell profile so it persists across sessions:
<CodeGroup>
```bash zsh
@@ -26,22 +32,32 @@ echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc && source ~/.bashrc
**Option A: degit** (recommended):
<Warning>
When upgrading an existing installation, move `~/.gemini/config/plugins/mem0` aside first. Installing over that directory can leave obsolete files from older plugin versions.
</Warning>
```bash
# Install the plugin (MCP server, hooks, scripts)
npx degit mem0ai/mem0/integrations/mem0-plugin ~/.gemini/config/plugins/mem0
npx degit mem0ai/mem0/integrations/antigravity-plugin ~/.gemini/config/plugins/mem0
```
This installs the MCP server, lifecycle hooks, and shared scripts.
This installs the generated Antigravity bundle with the Mem0 server, lifecycle hooks, and six memory skills.
## What's Included
| Component | Included |
|-----------|:--------:|
| MCP Server (9 memory tools) | Yes |
| Local MCP Server (`search_memories`) | Yes |
| Lifecycle Hooks | Yes |
| 16 Slash Commands | Yes |
| 6 Memory Skills | Yes |
## Available MCP Tools
## Memory tools and skills
The full plugin exposes a focused `search_memories` tool and captures completed work through lifecycle hooks. Six skills provide search, status, remember, forget, pause, and resume workflows.
If you need the full set of direct CRUD tools, connect the [hosted Mem0 MCP server](/platform/mem0-mcp) separately instead of installing both configurations under the same server name.
## Hosted MCP tools
| Tool | Description |
|------|-------------|
@@ -57,23 +73,52 @@ This installs the MCP server, lifecycle hooks, and shared scripts.
## Lifecycle Hooks
The plugin uses the same shell scripts as Claude Code, Cursor, and Codex: hooks bridge environment variables using `${extensionPath}` (Antigravity's plugin-root token).
The plugin translates Antigravity events into the shared Mem0 capture lifecycle.
| Hook | Event | What it does |
|------|-------|-------------|
| **Session start** | `SessionStart` | Loads prior memories and displays status banner |
| **User prompt** | `UserPromptSubmit` | Searches relevant memories before each message |
| **Pre-tool** | `PreToolUse` | Blocks MEMORY.md writes, enforces `user_id`/`app_id` on mem0 tools |
| **Post-tool** | `PostToolUse` | Tracks stats, scans bash errors for related memories |
| **Stop** | `Stop` | Stores a session summary at the end of every assistant turn (not just at session end) |
| **Invocation** | `PreInvocation` | Initializes the first invocation and recovers pending capture |
| **Post-tool** | `PostToolUse` | Records useful tool results and failures |
| **Stop** | `Stop` | Reads completed transcript messages and starts a background flush |
What you type is stored as yours. What the agent produces (session summaries and compaction summaries) is stored as the assistant's, so its suggestions never become your stated preferences.
Recall is explicit through `search_memories` and the search skill. The current Antigravity adapter does not inject query-specific memory during `PreInvocation` because that event does not include the user's prompt.
What you type is stored as yours. Captured agent summaries are stored as the assistant's, so its suggestions never become your stated preferences.
## Antigravity 1.1.25 workarounds
Antigravity 1.1.25 can validate a plugin's `mcp_config.json` without loading the server. Check whether Mem0 is registered:
```bash
agy mcp list
```
If `mem0` is absent, register the plugin's bundled server with Antigravity's supported global MCP command, then start a new session:
```bash
agy mcp add mem0 python3 ~/.gemini/config/plugins/mem0/core/mcp_server.py
```
The same release can send hooks with an empty `workspacePaths` array. For the `agy` CLI, pass the current repository explicitly:
```bash
MEM0_CWD="$PWD" agy
```
The adapter uses `MEM0_CWD` only when Antigravity omits the workspace. If neither value is available, it skips recall and capture instead of writing memories under an incorrect repository scope.
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
- **No tools appearing**: Restart your Antigravity session after installation
- **"Connection failed"**: Verify your key is set: `echo $MEM0_API_KEY`
- **MCP 401 Unauthorized**: If `${MEM0_API_KEY}` interpolation doesn't work in your `agy` version, replace with your literal key in `mcp_config.json`
- **No `mem0` entry in `agy mcp list`**: Use the Antigravity 1.1.25 global MCP registration command above
- **Hooks do not capture in the CLI**: Launch `agy` with `MEM0_CWD="$PWD"`
- **"Connection failed"**: Verify your key is set without printing it: `test -n "$MEM0_API_KEY" && echo configured`
<CardGroup cols={2}>
<Card title="Mem0 MCP Setup" icon="puzzle-piece" href="/platform/mem0-mcp">
docs/integrations/autogen.mdx
+1 -1
View File
@@ -19,7 +19,7 @@ pip install autogen mem0ai openai python-dotenv
First, we'll import the necessary libraries and set up our configurations.
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-autogen" rel="nofollow">Mem0 Platform</a>.</Note>
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-autogen">Mem0 Platform</a>.</Note>
```python
import os
docs/integrations/aws-bedrock.mdx
+3 -2
View File
@@ -1,6 +1,7 @@
---
title: AWS Bedrock
description: "Use Mem0 with AWS Bedrock and Amazon OpenSearch Service to enable cloud-native semantic memory storage, embeddings, and LLM calls for intelligent agents."
title: "AWS Bedrock Integration"
sidebarTitle: "AWS Bedrock"
description: "Use Mem0 with AWS Bedrock and OpenSearch Service for cloud-native persistent semantic memory storage."
---
This integration demonstrates how to use **Mem0** with **AWS Bedrock** and **Amazon OpenSearch Service (AOSS)** to enable persistent, semantic memory in intelligent agents.
docs/integrations/chatdev.mdx
+5 -5
View File
@@ -18,7 +18,7 @@ In this guide, you'll:
- **Python 3.12+**
- **[uv](https://docs.astral.sh/uv/)**: Python package manager
- **Node.js 18+** and **npm**: only needed if using the web console
- A **Mem0 API key** from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev" rel="nofollow">app.mem0.ai</a>
- A **Mem0 API key** from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev">app.mem0.ai</a>
- An **OpenAI API key** (or another LLM provider supported by ChatDev)
## Setup and Configuration
@@ -39,7 +39,7 @@ cd frontend && npm install && cd ..
Set up your environment variables in a `.env` file:
<Note>Get your Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev" rel="nofollow">Mem0 Platform</a>.</Note>
<Note>Get your Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev">Mem0 Platform</a>.</Note>
```bash
MEM0_API_KEY=your-mem0-api-key
@@ -194,7 +194,7 @@ This means retrieval returns memories from **both** the user's scope and the age
| Field | Required | Description |
|-------|----------|-------------|
| `api_key` | Yes | Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev" rel="nofollow">app.mem0.ai</a> |
| `api_key` | Yes | Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev">app.mem0.ai</a> |
| `user_id` | No | Scope memories to a specific user |
| `agent_id` | No | Scope memories to a specific agent |
@@ -216,9 +216,9 @@ This means retrieval returns memories from **both** the user's scope and the age
- **No memories returned on first run**: This is expected. Memories are stored *after* the agent responds, so the first interaction has no prior context. Memories appear starting from the second interaction onward.
- **`mem0ai` not installed**: If you see `ImportError: mem0ai is required for Mem0Memory`, run `uv add mem0ai` or `pip install mem0ai` to add the dependency.
- **Invalid API key**: A wrong or expired `MEM0_API_KEY` will log errors like `Mem0 search failed` or `Mem0 add failed` but won't crash the agent. Check your key at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev" rel="nofollow">app.mem0.ai</a>.
- **Invalid API key**: A wrong or expired `MEM0_API_KEY` will log errors like `Mem0 search failed` or `Mem0 add failed` but won't crash the agent. Check your key at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev">app.mem0.ai</a>.
- **Pipeline headers in memories**: ChatDev automatically strips internal pipeline headers (e.g., `=== INPUT FROM TASK (user) ===`) before sending text to Mem0, so your memories stay clean.
- **Clearing test memories**: To delete memories created during testing, use the Mem0 dashboard at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev" rel="nofollow">app.mem0.ai</a> or the Python SDK: `MemoryClient().delete_all(user_id="your-test-user")`.
- **Clearing test memories**: To delete memories created during testing, use the Mem0 dashboard at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-chatdev">app.mem0.ai</a> or the Python SDK: `MemoryClient().delete_all(user_id="your-test-user")`.
## Key Features
docs/integrations/claude-ai.mdx
+85
View File
@@ -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: <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-claude-ai">sign up at app.mem0.ai</a>
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**
<Note>
Free-tier accounts are limited to one custom connector. Pro, Max, Team, and Enterprise accounts can add multiple.
</Note>
### 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.
<CardGroup cols={2}>
<Card title="Mem0 MCP Setup" icon="puzzle-piece" href="/platform/mem0-mcp">
Detailed MCP configuration for all clients
</Card>
<Card title="Claude Code Integration" icon="/images/provider-icons/anthropic.svg" href="/integrations/claude-code">
Add Mem0 memory to Claude Code workflows
</Card>
</CardGroup>
<Snippet file="star-on-github.mdx" />
docs/integrations/claude-code.mdx
+132 -145
View File
@@ -1,189 +1,176 @@
---
title: Claude Code
description: "Add persistent memory to Claude Code CLI and Claude Cowork desktop app with the Mem0 plugin: MCP server, lifecycle hooks, and an SDK skill for recall."
description: "Persistent cross-session memory for Claude Code. Install once, memories are captured automatically and recalled in every future session."
---
Add persistent memory to [**Claude Code**](https://docs.anthropic.com/en/docs/claude-code) (CLI) and **Claude Cowork** (desktop app) with the Mem0 plugin. Your agent forgets everything between sessions. This plugin fixes that by connecting to Mem0's cloud memory layer via MCP, automatically capturing learnings at key lifecycle points, and retrieving relevant context before every response.
Claude Code forgets everything between sessions. This plugin fixes that. Install it, work normally, and Claude remembers what happened across sessions.
<Info>Current plugin version: `0.3.1`.</Info>
## Prerequisites
Before setting up Mem0 with Claude Code, ensure you have:
1. A Mem0 Platform account and API key (starts with `m0-`):
- [Sign up at app.mem0.ai](https://app.mem0.ai?utm_source=oss&utm_medium=integration-claude-code)
- [Get your API key](https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-claude-code)
1. A Mem0 Platform account and API key:
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-claude-code" rel="nofollow">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-claude-code" rel="nofollow">Get your API key</a> (starts with `m0-`)
2. A Claude Code version that supports plugin agents, worktree isolation for agents, and the `SubagentStart`, `SubagentStop`, and `PostToolUseFailure` hook events.
2. Claude Code CLI or Claude Cowork desktop app installed
3. Python 3.10+ and Git on your machine.
3. Your API key added to your shell profile (persists across sessions):
<CodeGroup>
```bash zsh
echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
source ~/.zshrc
```
```bash bash
echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
source ~/.bashrc
```
</CodeGroup>
Confirm it's set:
## Quick start
```bash
echo $MEM0_API_KEY
# Should print: m0-your-api-key
export MEM0_API_KEY='your-mem0-api-key'
claude plugin marketplace add mem0ai/mem0
claude plugin install mem0@mem0-plugins --scope user --config api_key="$MEM0_API_KEY"
unset MEM0_API_KEY
```
## Installation
Restart Claude Code (or run `/reload-plugins`), open a Git repository, and work normally. That's it.
### Option A: Plugin Marketplace (Recommended)
Install the full plugin including MCP server, lifecycle hooks, and SDK skill.
1. Add the Mem0 marketplace:
```bash
claude plugin marketplace add mem0ai/mem0
```
2. Install the plugin:
```bash
claude plugin install mem0@mem0-plugins
```
**Claude Cowork desktop app:** Open the Cowork tab, click **Customize** in the sidebar, click **Browse plugins**, and install Mem0.
### Option B: MCP Only
Add the Mem0 MCP server directly with a single command:
### Managing the plugin
```bash
npx mcp-add \
--name mem0-mcp \
--type http \
--url "https://mcp.mem0.ai/mcp/" \
--clients "claude code"
```
This gives you the MCP tools but not the lifecycle hooks or SDK skill.
### Option C: Manual MCP Configuration
Add to your Claude Code MCP config (`.mcp.json`):
```json
{
"mcpServers": {
"mem0": {
"type": "http",
"url": "https://mcp.mem0.ai/mcp/",
"headers": {
"Authorization": "Token ${MEM0_API_KEY}"
}
}
}
}
```
### Managing the Plugin
```bash
claude plugin update mem0@mem0-plugins # update the plugin to the latest version (restart to apply)
claude plugin marketplace update mem0-plugins # refresh the marketplace catalog
claude plugin update mem0@mem0-plugins --scope user # update the plugin (restart to apply)
claude plugin uninstall mem0@mem0-plugins # uninstall the plugin (keeps the marketplace)
claude plugin marketplace remove mem0-plugins # unregister the marketplace entirely
```
<Info icon="check">
Start a new session and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set.
</Info>
## What you can do
## Post-Installation: Run `/mem0:onboard`
### Automatic memory
After installing the plugin, start a new Claude Code session and run:
Once installed, memory works without any action from you:
```
/mem0:onboard
```
- **Capture** happens in the background as you work. Hooks save user messages, Claude's answers, changed files, and test/build results locally. Capture records evidence locally; memory extraction runs through Mem0 in a background worker.
- **Recall** happens automatically before Claude's first response in a new session. If the first prompt has at least 20 characters, the plugin searches with that prompt and injects up to five relevant memories. For shorter prompts or later questions, use explicit search.
This runs the setup wizard which:
1. Verifies your API key and MCP connection
2. Detects and imports project files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`)
3. Installs coding-optimized memory categories
4. Shows your identity (user ID, project scope, branch)
### Commands
The onboarding is idempotent and safe to re-run anytime. It auto-triggers on first session in a new project, but you can always invoke it manually.
| Command | What it does |
| --- | --- |
| `/mem0:search` | Search memories from earlier sessions. Supports `--top-k <n>`, `--category <name>`, `--scope <repo\|dir\|mine>`, and `--run-id <session-id>`. |
| `/mem0:status` | Check if memory is working: config, capture state, pending flushes, API key validity. |
| `/mem0:forget` | Delete your memories for this repo (shared project memory stays unless you pass `--include-project-memory`). |
| `/mem0:pause` | Pause memory capture. |
| `/mem0:resume` | Resume capture after a pause. |
| `/mem0:remember` | Tell Claude to capture something specific in its reply. |
## What's Included
Categories for `--category`: `project_knowledge`, `decisions_and_constraints`, `workflows`, `problems_and_fixes`, `results`. Without it, all categories are searched.
| Component | Plugin Install | MCP Only |
|-----------|:--------------:|:--------:|
| MCP Server (9 memory tools) | Yes | Yes |
| Lifecycle Hooks | Yes | No |
| Mem0 SDK Skill | Yes | No |
### Search tool
## Available MCP Tools
After the automatic first-prompt search, Claude can also call `search_memories` with a specific question, and you can run `/mem0:search` yourself. Explicit searches return up to 3 results by default (configurable to 20). The combined search output is capped at 4,000 characters by default, configurable with `max_context_chars`. This recall limit does not truncate captured messages sent for extraction.
Once installed, the following tools are available in every Claude Code session:
### Sidekick agent
| 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 |
Sidekick is available only in Claude Code.
## Lifecycle Hooks
When installed via the plugin marketplace, Mem0 hooks into Claude Code's lifecycle to automatically manage memory:
| Hook | Event | What it does |
|------|-------|-------------|
| **Setup** | `Setup` | Installs the mem0 SDK and dependencies (runs on init and maintenance) |
| **Session start** | `SessionStart` | Loads prior memories and displays status banner |
| **User prompt** | `UserPromptSubmit` | Searches relevant memories before each message; skips short prompts |
| **Pre-tool (3 handlers)** | `PreToolUse` | Blocks MEMORY.md writes; enforces `user_id`/`app_id` on mem0 tool calls; scans files being read for relevant memory context |
| **Post-tool** | `PostToolUse` | Tracks stats, scans bash errors for related memories |
| **Stop** | `Stop` | Stores a session summary at the end of every assistant turn (not just at session end) |
| **Pre-compact** | `PreCompact` | Stores a summary before the context is compacted |
What you type is stored as yours. What Claude produces (session summaries and compaction summaries) is stored as the assistant's, so its suggestions never become your stated preferences.
## Example Workflow
`mem0:sidekick` is a Sonnet coding agent that runs in a separate Git worktree. Use it to offload investigation, implementation, testing, or review without burning main-session context.
```text
# Session 1: Working on a feature
You: Let's refactor the auth module to use JWT tokens instead of sessions.
Ask Mem0's sidekick to investigate and implement this in its separate worktree.
Review its result and send any corrections back to the same sidekick.
```
# Claude searches memories, finds nothing relevant, proceeds with the work.
# Mem0 stores what you said as yours:
# - Your preference: "Prefers TypeScript, uses ESLint"
# ...and what Claude did as the assistant's, in the session summary:
# - Decision: "Migrated auth from sessions to JWT tokens"
# - Files modified: auth/middleware.ts, auth/token.ts
Changes stay in the sidekick's worktree until the main agent reviews and copies them over. By default the worktree branches from the repo's default branch. Set `worktree.baseRef` to `"head"` in your Claude settings to branch from the current commit instead. Uncommitted changes are not copied into the sidekick's worktree.
# Session 2 (days later): Related work
You: Add refresh token rotation to the auth system.
At startup, Sidekick receives the memories already recalled for its parent session. It can also call the Mem0 search tool for its assigned task. Start and completion hooks track its work locally; completing a Sidekick task does not independently send a memory-extraction request. Sidekick returns its result, validation, and a local commit when it changes files, so the main agent can review the work before incorporating it.
# Claude searches memories, retrieves the JWT migration context.
# Knows the file structure, decisions made, and your stated preferences.
# Continues seamlessly without re-explaining the codebase.
## How it works
The plugin follows a simple cycle: capture during a session, extract memories in the background, recall in the next session.
<Frame>
<img src="/images/plugin-sequence.svg" alt="Sequence diagram: the first user prompt triggers search, hooks capture activity during the session, a background worker extracts memories after every five exchanges or on idle/exit, and the next session recalls them." />
</Frame>
**Step by step:**
1. **Capture.** Hooks save the main agent's activity locally: user messages, Claude's answers, changed files, and short test/build results. Direct Sidekick lifecycle records stay local. Subagent results included in the main transcript can provide supporting evidence for extraction; the main agent's final response establishes the outcome. Capture does not call a model.
2. **Flush.** After every five completed exchanges, a detached background worker sends that batch to Mem0. Large exchanges flush sooner. Ending or compacting the session flushes anything remaining. If the session sits idle, an auto-flush runs after five minutes (configurable with `MEM0_CODE_IDLE_FLUSH_SECONDS`). The timer resets on each new exchange. The worker survives Claude Code exiting.
3. **Extract.** Each flush sends `add` calls with `agent_id` (the project identity), `user_id` (you), `app_id` (the repository), and `run_id` (the session). Prompts and responses are redacted without a character cutoff. Large conversations are split across requests without dropping message text. Mem0 classifies each extracted memory as shared project knowledge or a personal preference.
4. **Recall.** On the next session's first prompt, the plugin searches automatically and supplies up to five relevant memories. No model is called to write the query.
## Memory scoping
Each `add` call carries separate extraction instructions for project facts and personal facts. Mem0 sorts each memory into one of two buckets:
- **Shared project memory** (keyed by `agent_id`, scoped by `app_id`): one namespace per repository. Stores conventions, decisions, constraints, commands that work, and commands that failed with what fixed them. Everyone on the repo reads and writes the same pool. Project memory never carries a `user_id`, so teammates' searches never mix in your preferences. Directory information is stored in metadata for directory-scoped searches.
- **Personal memory** (keyed by `user_id`, scoped by `app_id`): your preferred tools, style, habits, and anything you asked to be remembered. Scoped to the repository by `app_id`, private to you.
Credentials are redacted before anything leaves your machine.
<Frame>
<img src="/images/memory-scoping-venn.svg" alt="Venn diagram showing one add call producing shared project memory (agent_id, visible to team) and personal memory (user_id, private to you). Search returns the union of both." />
</Frame>
## Search scope
Every memory carries identifiers showing where it came from:
| Identifier | What it is | Example |
| --- | --- | --- |
| `user_id` | You (personal memory only) | Your Mem0 user ID |
| `agent_id` | The project identity (shared memory only) | `acme-payments-api-<hash>` |
| `app_id` | The repository (scopes both lanes) | `acme-payments-api` |
| `run_id` | The Claude Code session | The session ID |
New Git repository memories use an `agent_id` with a hash of the Git remote identity so matching owner/repository names on different hosts stay separate. Searches also include the previous unhashed `agent_id`, scoped by the repository's `app_id`, so existing shared memories remain available after upgrading. Those older memories retain their original namespace, which did not distinguish Git hosts. Local folders continue using a hash of their path.
Explicitly forgetting shared project memory with `--include-project-memory` covers both repository IDs. Without that option, shared memories are preserved.
A search returns the union of shared project memory and your personal preferences. The scope narrows the project part:
| Scope | What you get |
| --- | --- |
| `repo` (default) | All project memory across every subdirectory, plus your preferences |
| `dir` | Project memory from the directory you're in (and its children), plus your preferences |
| `mine` | Your personal preferences only |
The `dir` scope is hierarchical: a parent directory sees everything in its children, but a child never sees the parent's memories.
The search tool accepts an optional `run_id` with every scope (`repo`, `dir`, and `mine`); `/mem0:search` exposes it as `--run-id session-id`. It restricts both shared and personal results to memories saved in that coding-agent session. Omit it to search across sessions. This is a memory filter, not a label for the session making the request; automatically filtering by the current session would hide earlier-session memories. Each memory update still records the session's `run_id`. Set the default scope with the `search_scope` setting or `MEM0_CODE_SEARCH_SCOPE` env var.
## Settings
| Setting | Default | What it controls |
| --- | --- | --- |
| `api_key` | required | Mem0 Platform API key. |
| `user_id` | local account name | User ID for memory storage. Resolved from: setting, `MEM0_CODE_USER_ID`, `MEM0_USER_ID`, `MEM0_RESOLVED_USER_ID`, `$USER`, `%USERNAME%`, then `default`. Set explicitly to share memories across machines. |
| `top_k` | `3` | Max memories per explicit search (1 to 20). |
| `max_context_chars` | `4000` | Max characters returned per search (1,000 to 10,000). |
| `search_scope` | `repo` | Default scope: `repo`, `dir`, or `mine`. Also read from `MEM0_CODE_SEARCH_SCOPE`. |
## Upgrading from 0.2.x
Breaking update. Your memories carry over, most local config does not.
- **Memories carry over.** Same user and repository scoping, including `~/.mem0/project_map.json`.
- **Env vars still work.** `MEM0_API_KEY`, `MEM0_USER_ID`, `MEM0_PROJECT_ID`.
- **Commands replaced.** Old commands replaced by `/mem0:search`, `/mem0:status`, `/mem0:forget`, `/mem0:pause`, `/mem0:resume`, `/mem0:remember`.
- **MCP server replaced.** Nine read/write tools replaced by the single read-only `search_memories` tool.
- **Local config ignored.** `~/.mem0/settings.json` and per-project `mem0.md` files are no longer read.
- **Old memories remain searchable.** Pre-upgrade memories may use different categories. Omit category filters if an older memory is missing from the results.
```bash
claude plugin marketplace update mem0-plugins
claude plugin update mem0@mem0-plugins --scope user
```
## Troubleshooting
- **"Connection failed"**: Verify `MEM0_API_KEY` is set in your shell: `echo $MEM0_API_KEY`. If empty, add it to your shell profile (see Prerequisites)
- **No tools appearing**: Restart your Claude Code session after installation
- **Memories not being captured**: Ensure you installed via the plugin marketplace (Option A) for lifecycle hooks. MCP-only installs require manual memory operations
- **"Mem0 Inactive" banner every session**: Your API key isn't persisting. Add `export MEM0_API_KEY="m0-..."` to your `~/.zshrc` (or `~/.bashrc`) and run `source ~/.zshrc`
| Problem | Fix |
| --- | --- |
| Missing key | Reinstall with `--config api_key="$MEM0_API_KEY"` while the var is set. |
| `401 Unauthorized` | API key is invalid or expired. Run `/mem0:status` to confirm. |
| No memory after ending a session | Extraction runs in the background. Wait a moment, then search again. |
| Sidekick won't start | Must be in a Git repo. Check that your Claude Code version supports plugin agents and worktrees. |
| Remove the plugin | `claude plugin uninstall mem0@mem0-plugins` |
<CardGroup cols={2}>
<Card title="Mem0 MCP Setup" icon="puzzle-piece" href="/platform/mem0-mcp">
docs/integrations/codex.mdx
+53 -25
View File
@@ -1,21 +1,27 @@
---
title: Codex
description: "Add persistent memory to OpenAI Codex with the Mem0 plugin featuring an MCP server, lifecycle hooks, and SDK skill so Codex remembers tasks and context."
description: "Add persistent memory to OpenAI Codex with automatic capture, automatic recall, a search tool, and six memory skills."
---
Add persistent memory to [**OpenAI Codex**](https://openai.com/index/codex/) with the Mem0 plugin. Codex forgets everything between tasks. This plugin fixes that by connecting to Mem0's cloud memory layer via MCP, automatically capturing learnings at key lifecycle points, and retrieving relevant context before every response.
Add persistent memory to [**OpenAI Codex**](https://openai.com/codex/) with the Mem0 plugin. Codex forgets everything between tasks. This plugin fixes that by connecting to Mem0's cloud memory layer via MCP, automatically capturing learnings at key lifecycle points, and retrieving relevant context on the first prompt of a session. Codex can use the search tool for recall later in the session.
<Info>Current plugin version: `0.3.1`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent).
## Prerequisites
Before setting up Mem0 with Codex, ensure you have:
1. A Mem0 Platform account and API key:
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-codex" rel="nofollow">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-codex" rel="nofollow">Get your API key</a> (starts with `m0-`)
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-codex">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-codex">Get your API key</a> (starts with `m0-`)
2. OpenAI Codex access
3. Your API key added to your shell profile (persists across sessions):
3. Python 3.10 or newer available as `python3`
4. Your API key added to your shell profile (persists across sessions):
<CodeGroup>
```bash zsh
@@ -33,7 +39,7 @@ source ~/.bashrc
### Option A: Plugin Marketplace (Recommended)
Install the full plugin including MCP server, lifecycle hooks, and SDK skill.
Install the full plugin, including automatic capture and recall, the `search_memories` tool, and six memory skills.
1. Add the Mem0 marketplace:
@@ -75,7 +81,7 @@ bearer_token_env_var = "MEM0_API_KEY"
Make sure `MEM0_API_KEY` is exported in the shell you launch Codex from, then restart Codex.
This gives you the MCP tools but not the lifecycle hooks or SDK skill.
This gives you the hosted MCP tools but not the plugin's lifecycle hooks or six memory skills.
### Managing the Plugin
@@ -88,20 +94,34 @@ codex plugin marketplace remove mem0-plugins # unregister the marketplace enti
To update, run `codex plugin marketplace upgrade` to pull the latest from the Mem0 repo.
<Info icon="check">
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.
After Option A, ask Codex to search memory for a recent project decision. After Option B, ask it to list your Mem0 entities. If the matching tool responds, the connection is ready.
</Info>
## 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 |
| Mem0 SDK Skill | Yes | No |
| Memory tools | `search_memories` | 9 CRUD tools |
| Lifecycle hooks | Yes | No |
| Native subagent memory lifecycle | Yes | No |
| Memory skills | 6 | No |
## Available MCP Tools
Mem0's Codex package does not bundle a named custom agent. If you define project or user agents under `.codex/agents/` or `~/.codex/agents/`, the full Mem0 plugin gives every native subagent the parent turn's retrieved memory context and records its completed result.
Once installed, the following tools are available in every Codex session:
## Direct MCP tools
Option B exposes the following hosted tools. The full plugin in Option A uses the focused `search_memories` tool and captures writes through lifecycle hooks.
| Tool | Description |
|------|-------------|
@@ -115,31 +135,33 @@ Once installed, the following tools are available in every Codex session:
| `delete_entities` | Delete a user/agent/app/run entity and its memories |
| `list_entities` | List users/agents/apps/runs stored in Mem0 |
## Lifecycle Hooks
## Lifecycle hooks
When installed via the plugin marketplace, Mem0 hooks into Codex's lifecycle to automatically manage memory:
Option A registers the hooks with the plugin. No separate hook installer or global `hooks.json` edit is required.
| Hook | Event | What it does |
|------|-------|-------------|
| **Session start** | `SessionStart` | Loads prior memories and displays status banner |
| **User prompt** | `UserPromptSubmit` | Searches relevant memories before each message |
| **Pre-tool (3 handlers)** | `PreToolUse` | Blocks MEMORY.md writes; enforces `user_id`/`app_id` on mem0 tool calls; scans files being read for relevant memory context |
| **Post-tool** | `PostToolUse` | Tracks stats, scans bash errors for related memories |
| **Stop** | `Stop` | Stores a session summary at the end of every assistant turn (not just at session end) |
| **Pre-compact** | `PreCompact` | Stores a summary before the context is compacted |
| **Session start** | `SessionStart` | Initializes the project session and recovers pending capture |
| **User prompt** | `UserPromptSubmit` | Records each prompt; searches on the first prompt when it has at least 20 characters |
| **Post-tool** | `PostToolUse` | Records useful tool outcomes for the completed exchange |
| **Subagent start** | `SubagentStart` | Reuses the parent turn's retrieved memory context in the child |
| **Subagent stop** | `SubagentStop` | Records the child transcript path and completed result |
| **Stop** | `Stop` | Captures completed work and starts a background flush when needed |
| **Pre-compact** | `PreCompact` | Flushes pending capture before context compaction |
| **Session end** | `SessionEnd` | Flushes any remaining capture in the background |
What you type is stored as yours. What Codex produces (session summaries and compaction summaries) is stored as the assistant's, so its suggestions never become your stated preferences.
What you type is stored as yours. Codex's captured responses are stored as the assistant's, so its suggestions never become your stated preferences.
## Example Workflow
```text
# Task 1: Setting up a new service
You: Create a REST API for the notifications service using Express and TypeScript.
You: Create a REST API for the notifications service using Express and TypeScript. Prefer explicit error types over generic catch-all handlers.
# Codex searches memories, finds your preferences from prior tasks.
# Mem0 stores what you said as yours:
# - Your preference: "Prefers explicit error types over generic catch-all"
# ...and what Codex did as the assistant's, in the session summary:
# ...and completed work reported by Codex as the assistant's:
# - Decision: "Notifications service uses Express + TypeScript + Zod validation"
# - Convention: "All API routes follow /api/v1/{resource} pattern"
@@ -150,12 +172,18 @@ You: Add WebSocket support for real-time notification delivery.
# Follows the same patterns established in the first task.
```
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
- **"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**: Confirm you installed Option A and restart Codex. MCP-only installs (Option B) do not include hooks.
<CardGroup cols={2}>
<Card title="Mem0 MCP Setup" icon="puzzle-piece" href="/platform/mem0-mcp">
docs/integrations/crewai.mdx
+39 -24
View File
@@ -22,7 +22,7 @@ pip install crewai crewai-tools mem0ai
Import required modules and set up configurations:
<Note>Remember to get your API keys from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-crewai" rel="nofollow">Mem0 Platform</a>, [OpenAI](https://platform.openai.com) and [Serper Dev](https://serper.dev) for search capabilities.</Note>
<Note>Remember to get your API keys from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-crewai">Mem0 Platform</a>, [OpenAI](https://platform.openai.com) and [Serper Dev](https://serper.dev) for search capabilities.</Note>
```python
import os
@@ -39,6 +39,10 @@ os.environ["SERPER_API_KEY"] = "your-serper-api-key"
client = MemoryClient()
```
<Note>
Newer versions of CrewAI removed the `memory_config={"provider": "mem0"}` shortcut on `Crew(...)` that older guides referenced. CrewAI still offers a native Mem0 path through its `ExternalMemory` API, so that option remains open; check [CrewAI's memory documentation](https://docs.crewai.com/en/concepts/memory) for the shape your version expects. This guide wires Mem0 in explicitly through `MemoryClient` instead, which keeps retrieval under your control and stays valid as CrewAI's memory API changes.
</Note>
## Store User Preferences
Set up initial conversation and preferences storage:
@@ -69,9 +73,21 @@ messages = [
store_user_preferences("crew_user_1", messages)
```
## Retrieve Relevant Memories
Look up what Mem0 already knows about the user before planning a trip, so the crew's output reflects their actual preferences:
```python
def get_user_context(user_id: str, query: str) -> str:
"""Fetch relevant memories and format them for a task description"""
relevant_memories = client.search(query, filters={"user_id": user_id})
memories = [m["memory"] for m in relevant_memories.get("results", [])]
return "\n".join(f"- {memory}" for memory in memories)
```
## Create CrewAI Agent
Define an agent with memory capabilities:
Define an agent with search capabilities:
```python
def create_travel_agent():
@@ -83,61 +99,60 @@ def create_travel_agent():
goal="Plan personalized travel itineraries",
backstory="""You are a seasoned travel planner, known for your meticulous attention to detail.""",
allow_delegation=False,
memory=True,
tools=[search_tool],
)
```
## Define Tasks
Create tasks for your agent:
Create a task that folds the retrieved memories into its description, so the agent plans around the user's known preferences:
```python
def create_planning_task(agent, destination: str):
"""Create a travel planning task"""
def create_planning_task(agent, destination: str, user_context: str):
"""Create a travel planning task personalized with the user's stored preferences"""
return Task(
description=f"""Find places to live, eat, and visit in {destination}.""",
expected_output=f"A detailed list of places to live, eat, and visit in {destination}.",
description=f"""Find places to live, eat, and visit in {destination}.
Known preferences for this user:
{user_context or "No stored preferences yet."}
""",
expected_output=f"A detailed list of places to live, eat, and visit in {destination}, tailored to the user's preferences.",
agent=agent,
)
```
## Set Up Crew
Configure the crew with memory integration:
Configure the crew. Mem0 handles persistence outside of CrewAI, so the crew itself does not need `memory=True` or a `memory_config`:
```python
def setup_crew(agents: list, tasks: list):
"""Set up a crew with Mem0 memory integration"""
"""Set up a crew; memory is managed through Mem0, not CrewAI's memory_config"""
return Crew(
agents=agents,
tasks=tasks,
process=Process.sequential,
memory=True,
memory_config={
"provider": "mem0",
"config": {"user_id": "crew_user_1"},
}
)
```
## Main Execution Function
Implement the main function to run the travel planning system:
Implement the main function to run the travel planning system: retrieve context from Mem0, run the crew, then store the new conversation back:
```python
def plan_trip(destination: str, user_id: str):
# Create agent
travel_agent = create_travel_agent()
# Create task
planning_task = create_planning_task(travel_agent, destination)
# Setup crew
user_context = get_user_context(user_id, f"travel preferences for {destination}")
planning_task = create_planning_task(travel_agent, destination, user_context)
crew = setup_crew([travel_agent], [planning_task])
result = crew.kickoff()
# Execute and return results
return crew.kickoff()
client.add(
[{"role": "user", "content": f"Planned a trip to {destination}."}],
user_id=user_id,
)
return result
# Example usage
if __name__ == "__main__":
docs/integrations/cursor.mdx
+64 -12
View File
@@ -1,21 +1,27 @@
---
title: Cursor
description: "Add persistent memory to Cursor with the Mem0 MCP server so your AI coding assistant remembers project context, decisions, and preferences across sessions."
description: "Add persistent memory to Cursor with automatic capture, explicit recall, a search tool, and six memory skills."
---
Add persistent memory to [**Cursor**](https://cursor.com) with the Mem0 MCP server. Your AI assistant forgets everything between sessions. Mem0 fixes that by connecting Cursor to Mem0's cloud memory layer via MCP so you can save and retrieve relevant context during coding sessions.
Add persistent memory to [**Cursor**](https://cursor.com) with the Mem0 plugin. Cursor captures completed work in the background, and its agent can search relevant project context in later sessions. You can also connect only the hosted MCP server when you do not need lifecycle capture.
<Info>Current plugin version: `0.3.1`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent).
## Prerequisites
Before setting up Mem0 with Cursor, ensure you have:
1. A Mem0 Platform account and API key:
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-cursor" rel="nofollow">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-cursor" rel="nofollow">Get your API key</a> (starts with `m0-`)
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-cursor">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-cursor">Get your API key</a> (starts with `m0-`)
2. Cursor installed ([cursor.com](https://cursor.com))
3. Your API key added to your shell profile (persists across sessions):
3. Python 3.10 or newer available as `python3`
4. Your API key added to your shell profile (persists across sessions):
<CodeGroup>
```bash zsh
@@ -35,13 +41,25 @@ source ~/.bashrc
## Installation
### Option A: One-Click Deeplink (MCP Only)
### Option A: Full Plugin (Recommended)
Add the Mem0 marketplace:
```bash
cursor-agent plugin marketplace add https://github.com/mem0ai/mem0
```
Open Cursor's **Customize** page or run `/plugins`, select the **Mem0 Plugins** marketplace, and install **Mem0** at user or project scope. Enter your Mem0 API key when Cursor asks for the plugin configuration, then restart Cursor.
The full plugin includes automatic capture, the `search_memories` recall tool, lifecycle hooks, and six memory skills.
### Option B: One-Click Deeplink (MCP Only)
The fastest way to get started. Click the link below to install the Mem0 MCP server directly in Cursor:
[Install Mem0 MCP in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=mem0&config=eyJtY3BTZXJ2ZXJzIjp7Im1lbTAiOnsidXJsIjoiaHR0cHM6Ly9tY3AubWVtMC5haS9tY3AvIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiVG9rZW4gJHtlbnY6TUVNMF9BUElfS0VZfSJ9fX19)
### Option B: npx (MCP Only)
### Option C: npx (MCP Only)
```bash
npx mcp-add \
@@ -51,7 +69,7 @@ npx mcp-add \
--clients "cursor"
```
### Option C: Manual Configuration (MCP Only)
### Option D: Manual Configuration (MCP Only)
Add the following to your `.cursor/mcp.json`:
@@ -73,9 +91,19 @@ Add the following to your `.cursor/mcp.json`:
</Info>
## Available MCP Tools
## What's included
Once installed, the following tools are available in every Cursor session:
| Component | Full plugin | MCP only |
| --- | :---: | :---: |
| Memory tools | `search_memories` | 9 CRUD tools |
| Automatic capture | Yes | No |
| Recall | `search_memories` | MCP search tools |
| Lifecycle hooks | Yes | No |
| Memory skills | 6 | No |
## MCP-only tools
Options B, C, and D expose the following hosted tools. The full plugin uses the focused `search_memories` tool and captures writes through lifecycle hooks.
| Tool | Description |
|------|-------------|
@@ -89,11 +117,29 @@ Once installed, the following tools are available in every Cursor session:
| `delete_entities` | Delete a user/agent/app/run entity and its memories |
| `list_entities` | List users/agents/apps/runs stored in Mem0 |
## Lifecycle hooks
The full plugin translates Cursor's native events into the shared Mem0 memory lifecycle:
| Cursor event | What Mem0 does |
| --- | --- |
| `sessionStart` | Initializes the project session and recovers pending capture |
| `beforeSubmitPrompt` | Observes the submitted prompt; recall stays tool-driven because this event cannot inject context |
| `postToolUse` / `postToolUseFailure` | Records useful tool results and failures |
| `afterAgentResponse` / `stop` | Captures the completed exchange |
| `preCompact` / `sessionEnd` | Flushes pending capture in the background |
<Note>
Cursor's `beforeSubmitPrompt` hook cannot add context to a prompt. Use `search_memories` to recall memories.
</Note>
The plugin does not register subagent start or stop hooks.
## Example Workflow
```text
# Session 1: Debugging a performance issue
You: The API endpoint /users is taking 3 seconds. Help me optimize it.
You: The API endpoint /users is taking 3 seconds. Help me optimize it. Prefer query-level fixes over caching.
# Cursor agent searches memories, proceeds with investigation.
# Mem0 stores what you said as yours:
@@ -109,10 +155,16 @@ You: The /orders endpoint is also slow, same pattern as before.
# Immediately checks for N+1 queries and missing indexes.
```
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
- **"Connection failed"**: Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY`
- **Duplicate tools**: If you had a previous MCP config for `mem0`, remove it before installing the plugin
- **Duplicate tools**: Do not combine the full plugin with an MCP-only option. Remove the standalone `mem0` MCP entry before installing the plugin.
- **No tools appearing**: Go to Cursor Settings > MCP and verify the `mem0` server shows as connected
<CardGroup cols={2}>
docs/integrations/deepseek-plugin.mdx
+129
View File
@@ -0,0 +1,129 @@
---
title: DeepSeek Harness
description: "Add persistent memory to DeepSeek Harness with automatic recall, automatic capture, and two native Mem0 tools."
---
Add persistent memory to the [**DeepSeek Harness**](https://github.com/deepseek-ai/deepseek-harness) with `@mem0/deepseek-plugin`. The plugin recalls relevant context before a model request, captures completed turns, and provides explicit Mem0 tools when the agent needs them.
<Info>Current package version: `0.3.0`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent).
## Overview
The plugin provides automatic memory plus two agent-callable tools:
| Capability | What it does |
|---|---|
| Automatic recall | Searches with the latest human prompt and adds unseen results to the model context |
| Automatic capture | Stores the human and assistant messages from each completed turn |
| `search_memory` | Recall facts from Mem0 relevant to a query |
| `add_memory` | Store a fact in Mem0 for future sessions |
Unlike file-based memory plugins, Mem0 is a managed backend: server-side extraction, semantic dedup, and conflict resolution, with memories reusable by integrations that use compatible user identities and search filters.
## How it works
A Cordis plugin is a module exporting `apply(ctx, config)`. This plugin waits for the Harness tool and system-prompt services, then uses their native extension points:
- `system-prompt/assemble` recalls memory before a model request.
- `session/event` captures only completed turns from the durable event stream.
- `ctx.tools.register(...)` exposes explicit search and add tools.
Cordis removes the listeners and tools when the plugin unmounts. Memory failures are fail-open, so a Mem0 outage does not stop the agent from completing its normal work.
DeepSeek Harness provides subagents through separate host-composition packages. This Mem0 package does not register a named Sidekick or claim child filesystem isolation. A Harness child uses Mem0 only when its own agent preset includes the Mem0 plugin.
## Prerequisites
1. A Mem0 Platform account and API key:
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-deepseek-plugin">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-deepseek-plugin">Get your API key</a> (starts with `m0-`)
2. The DeepSeek Harness installed.
3. Your API key exported in your shell:
<CodeGroup>
```bash zsh
echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
source ~/.zshrc
```
```bash bash
echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
source ~/.bashrc
```
</CodeGroup>
## Try it locally
1. Build and pack the plugin:
```sh
cd integrations/deepseek-plugin
pnpm install --frozen-lockfile
pnpm build
mkdir -p /tmp/mem0-deepseek-plugin
pnpm pack --pack-destination /tmp/mem0-deepseek-plugin
```
2. Install it into a disposable Harness profile so Harness supplies its peer dependencies:
```sh
DSH_HOME=/tmp/mem0-dsh-dev pnpm dlx @deepseek-ai/dsh@0.1.1-rc.2 \
plugin --profile headless add /tmp/mem0-deepseek-plugin/mem0-deepseek-plugin-0.3.0.tgz
```
3. Copy `cordis.example.yml`, set its installed package path and your `userId`, then load it with the same profile:
```sh
DSH_HOME=/tmp/mem0-dsh-dev pnpm dlx @deepseek-ai/dsh@0.1.1-rc.2 \
web --patch ./integrations/deepseek-plugin/cordis.example.yml
```
4. Open the web UI and ask the agent to remember something, then recall it in a later turn.
The `cordis.yml` entry looks like this:
```yaml
- name: "@deepseek-ai/dsh-system-prompt"
- name: "@deepseek-ai/dsh-tools"
- insert:
- id: mem0
name: "/tmp/mem0-dsh-dev/profiles/headless/node_modules/@mem0/deepseek-plugin/dist/index.js"
config:
# apiKey is read from MEM0_API_KEY when omitted here.
userId: "your-user-id"
autoRecall: true
autoCapture: true
# host: "https://your-onprem.mem0.ai" # optional: Platform on-prem / dedicated base URL
```
For a Mem0 Platform on-prem or dedicated deployment, point `config.host` at that base URL (defaults to `api.mem0.ai`). `host` is a Platform base-URL override, not a switch to self-hosted Mem0 OSS.
## Configuration
| Field | Required | Default | Notes |
|---|---|---|---|
| `apiKey` | no | `$MEM0_API_KEY` | Mem0 platform API key |
| `userId` | yes | | Default entity that owns the memories |
| `allowUserOverride` | no | `false` | Permit model-selected access to a different user only in a trusted multi-user deployment |
| `host` | no | `api.mem0.ai` | Platform base URL (on-prem / dedicated) |
| `autoRecall` | no | `true` | Recall relevant memory before model requests |
| `autoCapture` | no | `true` | Store completed human and assistant turns |
Both tools also accept optional per-call `userId`, `agentId`, and `runId` params so a single install can partition memory by entity, agent, or session; `userId` defaults to the configured user, while `agentId` and `runId` are omitted unless supplied. Automatic recall and capture use the configured user without an agent, repository, or session filter. Automatic capture preserves full redacted user and assistant message text without a per-message character cutoff.
## Telemetry
Writes are tagged `source="DEEPSEEK_HARNESS"` so Mem0 can attribute usage to this integration. Anonymous usage events include operation names, durations, result counts, and coarse failure kinds. Queries, memory text, entity IDs, and API keys are never included. Set `MEM0_TELEMETRY=false` to opt out.
<Note>
This plugin is a developer preview and tracks the evolving DeepSeek Harness plugin API.
</Note>
## Troubleshooting
- **`MISSING_CREDENTIAL` for `deepseek-official`**: Configure `DEEPSEEK_API_KEY` through Harness's Models page or export it in the shell that launches Harness.
- **`EMFILE: too many open files, watch` on macOS**: Launch Harness with `CHOKIDAR_USEPOLLING=1`.
- **Mem0 tools do not appear**: Run Harness with `--dump-config` and confirm the final composition contains the `mem0` row and the installed `dist/index.js` path.
Per-call `userId` overrides are rejected unless the operator enables `allowUserOverride: true`. Automatic recall and capture always use the configured user.
docs/integrations/flowise.mdx
+4 -21
View File
@@ -23,7 +23,7 @@ npm install -g flowise
npx flowise start
```
2. Access to the Flowise UI at http://localhost:3000
2. Access to the Flowise UI at `http://localhost:3000`
3. Basic familiarity with [Flowise's LLM orchestration](https://flowiseai.com/#features) concepts
## Setup and Configuration
@@ -34,15 +34,11 @@ npx flowise start
2. In this example, we use the **Conversation Chain** template.
3. Replace the default **Buffer Memory** with **Mem0 Memory**.
![Flowise Memory Integration](https://raw.githubusercontent.com/FlowiseAI/FlowiseDocs/main/en/.gitbook/assets/mem0/flowise-flow.png)
### 2. Obtain Your Mem0 API Key
1. Navigate to the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-flowise" rel="nofollow">Mem0 API Key dashboard</a>.
1. Navigate to the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-flowise">Mem0 API Key dashboard</a>.
2. Generate or copy your existing Mem0 API Key.
![Mem0 API Key](https://raw.githubusercontent.com/FlowiseAI/FlowiseDocs/main/en/.gitbook/assets/mem0/api-key.png)
### 3. Configure Mem0 Credentials
1. Enter the **Mem0 API Key** in the Mem0 Credentials section.
@@ -57,11 +53,6 @@ npx flowise start
}
```
<figure>
<img src="https://raw.githubusercontent.com/FlowiseAI/FlowiseDocs/main/en/.gitbook/assets/mem0/creds.png" alt="Mem0 Credentials" />
<figcaption>Configure API Credentials</figcaption>
</figure>
## Memory Features
### 1. Basic Memory Storage
@@ -70,9 +61,7 @@ Test your memory configuration:
1. Save your Flowise configuration
2. Run a test chat and store some information
3. Verify the stored memories in the <a href="https://app.mem0.ai/dashboard/requests?utm_source=oss&utm_medium=integration-flowise" rel="nofollow">Mem0 Dashboard</a>
![Flowise Test Chat](https://raw.githubusercontent.com/FlowiseAI/FlowiseDocs/main/en/.gitbook/assets/mem0/flowise-chat-1.png)
3. Verify the stored memories in the <a href="https://app.mem0.ai/dashboard/requests?utm_source=oss&utm_medium=integration-flowise">Mem0 Dashboard</a>
### 2. Memory Retention
@@ -82,14 +71,10 @@ Validate memory persistence:
2. Ask a question about previously stored information
3. Confirm that the AI remembers the context
![Testing Memory Retention](https://raw.githubusercontent.com/FlowiseAI/FlowiseDocs/main/en/.gitbook/assets/mem0/flowise-chat-2.png)
## Advanced Configuration
### Memory Settings
![Mem0 Settings](https://raw.githubusercontent.com/FlowiseAI/FlowiseDocs/main/en/.gitbook/assets/mem0/settings.png)
Available settings include:
1. **Search Only Mode**: Enable memory retrieval without creating new memories
@@ -103,13 +88,11 @@ Available settings include:
### Platform Configuration
Additional settings available in <a href="https://app.mem0.ai/dashboard/project-settings?utm_source=oss&utm_medium=integration-flowise" rel="nofollow">Mem0 Project Settings</a>:
Additional settings available in <a href="https://app.mem0.ai/dashboard/project-settings?utm_source=oss&utm_medium=integration-flowise">Mem0 Project Settings</a>:
1. **Custom Instructions**: Define memory extraction rules
2. **Expiration Date**: Set automatic memory cleanup periods
![Mem0 Project Settings](https://raw.githubusercontent.com/FlowiseAI/FlowiseDocs/main/en/.gitbook/assets/mem0/mem0-settings.png)
## Best Practices
1. **User Identification**: Use consistent `user_id` values for reliable memory retrieval
docs/integrations/google-ai-adk.mdx
+2 -2
View File
@@ -22,10 +22,10 @@ pip install google-adk mem0ai python-dotenv
```
Set up your API keys:
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-google-ai-adk" rel="nofollow">Mem0 API Key</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-google-ai-adk">Mem0 API Key</a>
- Google AI Studio API Key
<Note>Remember to get your API key from <a href="https://app.mem0.ai" rel="nofollow">Mem0 Platform</a> and set up a [Google AI Studio API Key](https://aistudio.google.com/apikey).</Note>
<Note>Remember to get your API key from <a href="https://app.mem0.ai">Mem0 Platform</a> and set up a [Google AI Studio API Key](https://aistudio.google.com/apikey).</Note>
```python
import os
docs/integrations/hermes.mdx
+62 -27
View File
@@ -1,39 +1,35 @@
---
title: Hermes Agent
description: "Add long-term memory to Hermes agents with Mem0, on managed Mem0 Cloud or fully self-hosted (OSS), with automatic background sync and zero-latency prefetch."
description: "Add long-term memory to Hermes agents with Mem0: managed Platform, a self-hosted server, or fully local OSS — with current-turn recall and background fact extraction."
---
Add long-term memory to [Hermes Agent](https://github.com/NousResearch/hermes-agent), a self-improving AI agent CLI by Nous Research. Hermes has a pluggable memory system, and Mem0 is one of the supported providers. Once enabled, Mem0 learns facts from your conversations and surfaces relevant ones before each turn, without slowing down the chat.
Add long-term memory to [Hermes Agent](https://github.com/NousResearch/hermes-agent), a self-improving AI agent CLI by Nous Research. Hermes has a pluggable memory system, and Mem0 is one of the supported providers. Once enabled, Mem0 learns facts from your conversations and surfaces relevant ones for the current question, without slowing down the chat.
You can run Mem0 in two ways:
You can run Mem0 in three ways:
- **Platform mode** (default): managed Mem0 Cloud. Add your API key and you are ready.
- **OSS mode**: fully self-hosted with your own LLM, embedder, and vector store. No data leaves your machine.
- **Self-hosted server mode**: point the plugin at a Mem0 server you run yourself (the Docker-shipped server). The plugin only talks HTTP to your server.
- **OSS mode**: run Mem0 in-process with your own LLM, embedder, and vector store. No Mem0 server required.
## How It Works
Hermes runs a built-in memory system (file-based `MEMORY.md` and `USER.md`) alongside one external provider. When Mem0 is active, it works additively with the built-in system at three points in every conversation turn.
Hermes runs a built-in memory system (file-based `MEMORY.md` and `USER.md`) alongside one external provider. When Mem0 is active, it works additively with the built-in system at two points in every conversation turn.
### 1. Before the agent responds (prefetch)
### 1. Current-turn recall (bounded wait)
When you send a message, Hermes checks for cached Mem0 search results from the previous turn. If they exist, those memories are injected into the system prompt so the model can see them. This is zero-latency, with no waiting on an API call.
When you send a message, Hermes searches your stored memories for the current question and waits up to 3 seconds for results. If they arrive in time, they are injected into the system prompt so the model can see them. If the backend is slower, Hermes skips the injection and the model can still call `mem0_search` itself — so a slow backend never blocks a turn.
### 2. After the agent responds (sync)
### 2. Background fact extraction (sync)
Once the model finishes, Hermes sends the `(user message, assistant response)` pair to Mem0 in a background thread. Mem0 extracts facts automatically (for example, "user prefers Python" or "user works at Acme Corp"), so you never have to tell it what to remember. Each write is tagged with the gateway channel it came from.
### 3. Background prefetch for the next turn
At the same time, Hermes runs a background search to pre-load relevant memories for your next message. By the time you type, the results are already cached.
## Agent Tools
When Mem0 is active, the model gets five tools it can call during a conversation:
When Mem0 is active, the model gets four tools it can call during a conversation:
| Tool | Description | Parameters |
|------|-------------|------------|
| `mem0_list` | List all stored memories, for a full overview | `page`, `page_size` (default 100, max 200) |
| `mem0_search` | Semantic search by meaning, ranked by relevance | `query` (required), `top_k` (default 10, max 50), `rerank` (default `true`, Platform mode only) |
| `mem0_search` | Semantic search by meaning, ranked by relevance | `query` (required), `top_k` (default 10, max 50), `rerank` (default `false`, Platform mode only) |
| `mem0_add` | Store a fact verbatim, with no LLM extraction | `content` (required) |
| `mem0_update` | Update a memory's text by ID | `memory_id`, `text` (both required) |
| `mem0_delete` | Delete a memory by ID | `memory_id` (required) |
@@ -61,7 +57,7 @@ hermes memory setup
Select **mem0**, choose **Platform**, and paste your API key when prompted. The wizard writes the non-secret settings to `~/.hermes/mem0.json` and keeps the key in `~/.hermes/.env`.
<Note>Get your API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-hermes" rel="nofollow">app.mem0.ai</a>.</Note>
<Note>Get your API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-hermes">app.mem0.ai</a>.</Note>
### Option 2: Manual Configuration
@@ -79,6 +75,36 @@ memory:
That's it. Mem0 runs automatically from here.
## Self-Hosted Server Setup
Run the [Mem0 server](https://github.com/mem0ai/mem0/tree/main/server) (FastAPI + pgvector) from its Docker image and point the plugin at it. Unlike OSS mode, the plugin just talks HTTP to your server.
### Interactive
```bash
hermes memory setup
# Select "mem0", then "Self-hosted server", and enter the server URL
```
### With flags
```bash
hermes memory setup mem0 --mode selfhosted \
--host http://localhost:8888 \
--api-key your-admin-api-key
```
### With environment variables
```bash
echo "MEM0_HOST=http://localhost:8888" >> ~/.hermes/.env
echo "MEM0_API_KEY=your-admin-api-key" >> ~/.hermes/.env
```
Then start a fresh Hermes session and call `mem0_search` — it connects to your server. The plugin authenticates with `X-API-Key` and uses the server's `/search` and `/memories` routes. The API key is optional only for servers running with `AUTH_DISABLED`.
<Note>Setting `host` routes to the self-hosted server automatically. Don't combine it with `mode: oss` — OSS takes precedence and ignores `host`.</Note>
## OSS (Self-Hosted) Setup
OSS mode runs Mem0 entirely on your own infrastructure: your LLM, your embedder, and your vector store. No data is sent to Mem0 Cloud, and no Mem0 API key is required.
@@ -111,15 +137,20 @@ hermes memory setup mem0 --mode oss \
| Flag | Description |
|------|-------------|
| `--mode` | `platform` or `oss` |
| `--mode` | `platform`, `selfhosted`, or `oss` |
| `--api-key` | Platform API key, or the admin key of a self-hosted server |
| `--host` | Self-hosted server URL (with `--mode selfhosted`) |
| `--oss-llm` | LLM provider (`openai` or `ollama`, default `openai`) |
| `--oss-llm-key` | LLM API key (for `openai`) |
| `--oss-llm-model` | Override the LLM model |
| `--oss-llm-url` | LLM base URL (for `ollama` or a custom endpoint) |
| `--oss-embedder` | Embedder provider (default `openai`) |
| `--oss-embedder-key` | Embedder API key |
| `--oss-embedder-model` | Override the embedder model |
| `--oss-embedder-url` | Embedder base URL (for `ollama` or a custom endpoint) |
| `--oss-vector` | Vector store (`qdrant` or `pgvector`, default `qdrant`) |
| `--oss-vector-path` | Local Qdrant storage path |
| `--oss-vector-url` | Qdrant server URL |
| `--oss-vector-host`, `--oss-vector-port` | PGVector or remote Qdrant host and port |
| `--oss-vector-user`, `--oss-vector-password`, `--oss-vector-dbname` | PGVector connection details |
| `--user-id` | Canonical user identifier |
@@ -127,7 +158,7 @@ hermes memory setup mem0 --mode oss \
## Switching Modes
You can move between Platform and OSS at any time. Run the setup command again, or edit `~/.hermes/mem0.json` directly.
You can move between the three modes at any time. Run the setup command again, or edit `~/.hermes/mem0.json` directly.
```bash
# Platform to OSS
@@ -136,6 +167,9 @@ hermes memory setup mem0 --mode oss --oss-llm-key sk-...
# OSS to Platform
hermes memory setup mem0 --mode platform --api-key sk-...
# Platform to a self-hosted server
hermes memory setup mem0 --mode selfhosted --host http://localhost:8888
# Preview without writing anything
hermes memory setup mem0 --mode oss --oss-llm-key sk-... --dry-run
```
@@ -146,7 +180,7 @@ A self-hosted `~/.hermes/mem0.json` looks like this:
{
"mode": "oss",
"oss": {
"llm": {"provider": "openai", "config": {"model": "gpt-5-mini"}},
"llm": {"provider": "openai", "config": {"model": "gpt-5-mini", "is_reasoning_model": true}},
"embedder": {"provider": "openai", "config": {"model": "text-embedding-3-small"}},
"vector_store": {"provider": "qdrant", "config": {"path": "~/.hermes/mem0_qdrant"}}
}
@@ -159,11 +193,12 @@ Behavioral settings live in `~/.hermes/mem0.json` and are written for you by `he
| Key | Default | Description |
|-----|---------|-------------|
| `mode` | `platform` | `platform` (Mem0 Cloud) or `oss` (self-hosted) |
| `api_key` | none | Mem0 Platform API key, required in Platform mode. Stored in `.env` as `MEM0_API_KEY` |
| `mode` | `platform` | `platform` (Mem0 Cloud) or `oss` (self-managed, in-process). Self-hosted server routing is set via `host` |
| `host` | none | Self-hosted Mem0 server URL. When set, the plugin talks HTTP to your server instead of the cloud |
| `api_key` | none | Mem0 Platform API key, or the admin key of a self-hosted server. Stored in `.env` as `MEM0_API_KEY` |
| `user_id` | `hermes-user` | Identifier that scopes memories. See cross-channel behavior below |
| `agent_id` | `hermes` | Agent identifier attached to writes |
| `rerank` | `true` | Rerank search results for relevance (Platform mode only) |
| `rerank` | `false` | Rerank search results for relevance (Platform mode only) |
### Cross-channel memories
@@ -174,12 +209,11 @@ Hermes can run from the CLI and from gateways like Telegram, Slack, and Discord.
Either way, every write is tagged with `metadata.channel` (for example `telegram` or `cli`), so per-channel views are still possible at query time.
## Reliability
- **Circuit breaker**: if Mem0 fails five times in a row, Hermes pauses calls for two minutes, then retries. The agent keeps working without memory during that window. Expected client errors, like a 404 on a missing memory id, do not count toward tripping the breaker.
- **Non-blocking**: every Mem0 call runs in a background daemon thread, so a slow or failed call never blocks your conversation.
- **Thread-safe**: the client uses lazy initialization with locking, and the background sync and prefetch threads are guarded so concurrent gateway messages cannot produce duplicate memories.
- **Non-blocking**: fact extraction runs in a background daemon thread, and current-turn recall waits at most 3 seconds, so a slow or failed call never blocks your conversation.
- **Thread-safe**: the client uses lazy initialization with locking, and the background sync and recall threads are guarded so concurrent gateway messages cannot produce duplicate memories.
## Troubleshooting
@@ -188,6 +222,7 @@ Either way, every write is tagged with `metadata.channel` (for example `telegram
The circuit breaker tripped after five consecutive failures and resets after two minutes.
- **Platform mode**: check your API key and internet connection.
- **Self-hosted server mode**: check that the server is running and reachable at the configured `host` URL.
- **OSS mode**: make sure your vector store (Qdrant or PGVector) is running and reachable.
### OSS: vector store connection refused
@@ -217,8 +252,8 @@ curl http://localhost:11434/api/tags
## Key Features
1. **Two ways to run**: managed Platform or fully self-hosted OSS, switchable at any time.
2. **Zero-latency recall**: memories are prefetched in the background and cached before you type.
1. **Three ways to run**: managed Platform, a self-hosted server, or fully local OSS, switchable at any time.
2. **Current-turn recall**: memories for the current question are injected within a 3-second window, with `mem0_search` as the model's own backstop.
3. **Automatic extraction**: Mem0 extracts and deduplicates facts from each exchange for you.
4. **Non-blocking and fault tolerant**: background threads plus a circuit breaker keep the agent responsive even when Mem0 is unreachable.
5. **Additive memory**: works alongside Hermes' built-in file memory (`MEMORY.md`, `USER.md`).
docs/integrations/kimi.mdx
+117
View File
@@ -0,0 +1,117 @@
---
title: Kimi Code
description: "Add persistent project memory to Kimi Code with automatic capture, automatic recall, Mem0 skills, and tools."
---
Kimi Code forgets project decisions between sessions. The Mem0 plugin captures completed work, recalls relevant context before a response, and gives Kimi explicit memory tools and skills.
<Info>Current plugin version: `0.3.1`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent).
## Prerequisites
1. A Mem0 Platform account and API key:
- [Sign up at app.mem0.ai](https://app.mem0.ai?utm_source=oss&utm_medium=integration-kimi)
- [Get your API key](https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-kimi) (starts with `m0-`)
2. [Kimi Code](https://www.kimi.com/code) with plugin support.
3. Python 3.10+ and Git on your machine.
## Quick start
Export the key in the shell where you start Kimi Code:
```bash
export MEM0_API_KEY='your-mem0-api-key'
kimi
```
Inside Kimi Code, install the native plugin bundle and reload the session:
```text
/plugins install https://github.com/mem0ai/mem0/tree/main/integrations/kimi-plugin
/reload
```
Run `/plugins info mem0` to confirm that the plugin, MCP server, skills, and hooks loaded.
## What you get
- **Automatic capture:** Kimi records completed exchanges locally and flushes durable project knowledge to Mem0 in the background.
- **Automatic recall:** Relevant memories are added before Kimi answers the first prompt in a session, if that prompt has at least 20 characters.
- **Explicit search:** Kimi can call `search_memories` when it needs a more specific answer.
- **Six memory skills:** Search, status, remember, forget, pause, and resume use the same memory behavior as the other Mem0 coding-agent plugins.
- **Project scoping:** Memories stay attached to the repository, with separate personal and shared project lanes.
Credentials are redacted before memory capture. If Mem0 is unavailable, hooks fail open so Kimi can continue its normal work.
## How it works
Kimi's native lifecycle events are translated into the shared Mem0 memory lifecycle:
| Kimi event | What Mem0 does |
| --- | --- |
| `SessionStart` | Initializes the project session and recovers pending capture |
| `UserPromptSubmit` | Records each prompt; searches on the first prompt when it has at least 20 characters |
| `PostToolUse` / `PostToolUseFailure` | Records useful tool results and failures |
| `Stop` | Captures the completed exchange |
| `PreCompact` / `SessionEnd` | Flushes pending capture in the background |
The plugin does not register subagent start or stop hooks or supply parent memories to child agents.
## Verify the plugin
In one session, say:
```text
Remember exactly: the release codename for this repository is ORCHID-9274.
```
Start a new Kimi session in the same repository and ask:
```text
What is the release codename for this repository? Do not infer it from repository files.
```
Kimi should return `ORCHID-9274` from memory.
## Managing the plugin
```text
/plugins list
/plugins info mem0
/plugins disable mem0
/plugins enable mem0
/plugins remove mem0
```
Run `/reload` or start a new session after enabling, disabling, or reinstalling the plugin.
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
| Problem | Fix |
| --- | --- |
| Missing API key | Start Kimi from a shell where `MEM0_API_KEY` is exported. |
| Plugin changes do not appear | Run `/plugins reload`, then `/reload` or `/new`. |
| MCP server is disabled | Run `/plugins mcp enable mem0 mem0`, then `/reload`. |
| No memory in a later session | Wait a moment for the background flush, then ask Kimi to search memory explicitly. |
| Remove the plugin | Run `/plugins remove mem0`. |
<CardGroup cols={2}>
<Card title="Cursor" icon="arrow-pointer" href="/integrations/cursor">
Add the same persistent project memory to Cursor
</Card>
<Card title="Claude Code" icon="/images/provider-icons/anthropic.svg" href="/integrations/claude-code">
Use Mem0 with Claude Code and its isolated sidekick
</Card>
</CardGroup>
<Snippet file="star-on-github.mdx" />
docs/integrations/langchain.mdx
+4 -3
View File
@@ -1,6 +1,7 @@
---
title: Langchain
description: "Build personalized AI agents using LangChain for conversation flow and Mem0 for long-term memory retention, ideal for travel planners and smart assistants."
title: "LangChain Integration"
sidebarTitle: "Langchain"
description: "Build personalized AI agents using LangChain for conversation flow and Mem0 for long-term memory retention."
---
Build a personalized Travel Agent AI using LangChain for conversation flow and Mem0 for memory retention. This integration enables context-aware and efficient travel planning experiences.
@@ -22,7 +23,7 @@ pip install langchain langchain_openai mem0ai python-dotenv
Import required modules and set up configurations:
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-langchain" rel="nofollow">Mem0 Platform</a>.</Note>
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-langchain">Mem0 Platform</a>.</Note>
```python
import os
docs/integrations/langgraph.mdx
+1 -1
View File
@@ -23,7 +23,7 @@ pip install langgraph langchain-openai mem0ai python-dotenv
Import required modules and set up configurations:
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-langgraph" rel="nofollow">Mem0 Platform</a>.</Note>
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-langgraph">Mem0 Platform</a>.</Note>
```python
from typing import Annotated, TypedDict, List
docs/integrations/llama-index.mdx
+2 -2
View File
@@ -6,7 +6,7 @@ description: "Use Mem0 as a memory store in LlamaIndex with support for ReAct an
LlamaIndex supports Mem0 as a [memory store](https://llamahub.ai/l/memory/llama-index-memory-mem0). In this guide, we'll show you how to use it.
<Note type="info">
[**Mem0Memory**](https://docs.llamaindex.ai/en/stable/examples/memory/Mem0Memory/) now supports **ReAct** and **FunctionCalling** agents.
[**Mem0Memory**](https://developers.llamaindex.ai/python/examples/memory/mem0memory/) now supports **ReAct** and **FunctionCalling** agents.
</Note>
### Installation
@@ -22,7 +22,7 @@ pip install llama-index-core llama-index-memory-mem0 python-dotenv
Set your Mem0 Platform API key as an environment variable. You can replace `<your-mem0-api-key>` with your actual API key:
<Note type="info">
You can obtain your Mem0 Platform API key from the <a href="https://app.mem0.ai/login?utm_source=oss&utm_medium=integration-llama-index" rel="nofollow">Mem0 Platform</a>.
You can obtain your Mem0 Platform API key from the <a href="https://app.mem0.ai/login?utm_source=oss&utm_medium=integration-llama-index">Mem0 Platform</a>.
</Note>
```python
docs/integrations/mastra.mdx
+1 -1
View File
@@ -23,7 +23,7 @@ npm install @mastra/core @mastra/mem0 @ai-sdk/openai zod
Set up your environment variables:
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-mastra" rel="nofollow">Mem0 Platform</a>.</Note>
<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-mastra">Mem0 Platform</a>.</Note>
```bash
MEM0_API_KEY=your-mem0-api-key
docs/integrations/n8n.mdx
+5 -4
View File
@@ -1,6 +1,7 @@
---
title: n8n
description: "Add long-term memory to n8n workflows and AI Agents with the Mem0 community node to store, search, and recall durable facts across runs, no code required."
title: "n8n Integration"
sidebarTitle: "n8n"
description: "Add long-term memory to n8n workflows and AI Agents with the Mem0 community node, no code required."
---
Your n8n workflows start from zero on every run. The [`@mem0/n8n-nodes-mem0`](https://www.npmjs.com/package/@mem0/n8n-nodes-mem0) community node fixes that: store durable facts as memories, recall them in any later run, and hand the node to an [n8n AI Agent](https://docs.n8n.io/advanced-ai/) as a tool so it can remember and recall on its own.
@@ -14,7 +15,7 @@ Your n8n workflows start from zero on every run. The [`@mem0/n8n-nodes-mem0`](ht
## Prerequisites
1. A Mem0 API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-n8n" rel="nofollow">API Keys dashboard</a> (sign up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-n8n" rel="nofollow">app.mem0.ai</a> if you do not have an account).
1. A Mem0 API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-n8n">API Keys dashboard</a> (sign up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-n8n">app.mem0.ai</a> if you do not have an account).
2. A **self-hosted** n8n instance. Installing community nodes from npm is a self-hosted feature; n8n Cloud only offers nodes that n8n has verified.
3. Owner access to that instance, since only instance owners can install community nodes.
@@ -139,7 +140,7 @@ The **User ID** is a stable string you pick to identify whose memories these are
## Troubleshooting
- **The node does not appear in the panel**: community nodes install on self-hosted n8n only, and only instance owners can install them. On n8n Cloud, this node is not yet available.
- **`401 Unauthorized`**: the API key is wrong or was revoked. Regenerate it in the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-n8n" rel="nofollow">API Keys dashboard</a> and update the credential.
- **`401 Unauthorized`**: the API key is wrong or was revoked. Regenerate it in the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-n8n">API Keys dashboard</a> and update the credential.
- **"Provide at least one of User ID, Agent ID, App ID, or Run ID"**: every Add, Search, and Get Many needs an entity scope. Fill in at least one.
- **Search returns nothing right after an Add**: extraction is asynchronous. Leave **Wait for Completion** on, or add a short Wait node before searching.
- **Searching two entity ids returns more than expected**: multiple ids are combined with OR by design. Run one operation per id to narrow.
docs/integrations/openai-agents-sdk.mdx
+1 -1
View File
@@ -22,7 +22,7 @@ pip install openai-agents mem0ai
```
2. Valid API keys:
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-openai-agents-sdk" rel="nofollow">Mem0 API Key</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-openai-agents-sdk">Mem0 API Key</a>
- [OpenAI API Key](https://platform.openai.com/api-keys)
## Basic Integration Example
docs/integrations/openclaw.mdx
+16 -13
View File
@@ -5,6 +5,10 @@ description: "Add long-term memory to OpenClaw agents using the Mem0 plugin with
Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw) agents with the `@mem0/openclaw-mem0` plugin. Your agent forgets everything between sessions. This plugin fixes that by automatically watching conversations, extracting what matters, and bringing it back when relevant.
<Info>Current package version: `1.1.0`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent). OpenClaw subagents can recall parent memories. Mem0 does not capture their sessions.
## Overview
<Frame>
@@ -14,11 +18,12 @@ Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw) agents
The plugin provides:
1. **Triage**: The agent extracts durable facts from conversations using a structured protocol with importance gates and domain overlays
2. **Recall**: Before each turn, relevant memories are retrieved with reranking and injected into context
3. **Dream**: Periodic memory consolidation merges duplicates, resolves conflicts, prunes stale entries
4. **Agent Tools**: Eight tools for explicit memory operations during conversations
3. **Agent Tools**: Eight tools for explicit memory operations during conversations
Skills mode, `autoRecall`, and `autoCapture` are all enabled by default during `openclaw mem0 init`.
Automatic capture preserves the full text of selected user and assistant messages after noise filtering and secret redaction, without a per-message character cutoff. It selects recent messages and earlier work summaries; it does not capture every message in the conversation.
## Requirements
Check your OpenClaw version:
@@ -101,7 +106,7 @@ You no longer need manual config editing to get started. Everything happens insi
</Step>
</Steps>
That's it. No API key, no config file editing, no environment variables. The plugin is now active with skills-based memory (triage, recall, and dream) running automatically.
That's it. No API key, no config file editing, no environment variables. The plugin is now active with skills-based memory (triage and recall) running automatically.
<Note>The chat flow uses the same underlying config as manual setup: it writes `apiKey`, `userId`, and `skills` config into `openclaw.json` for you. You can still open the file to inspect or override values afterward.</Note>
@@ -115,7 +120,7 @@ That's it. No API key, no config file editing, no environment variables. The plu
</Step>
<Step title="Get your API key">
Get your API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-openclaw" rel="nofollow">app.mem0.ai</a>.
Get your API key from <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-openclaw">app.mem0.ai</a>.
</Step>
<Step title="Select the plugin as your memory backend in `openclaw.json`">
@@ -142,7 +147,6 @@ That's it. No API key, no config file editing, no environment variables. The plu
"keywordSearch": true,
"identityAlwaysInclude": true
},
"dream": { "enabled": true },
"domain": "companion"
}
}
@@ -341,8 +345,8 @@ openclaw mem0 status --json
|-----|------|---------|-------------|
| `mode` | `"platform"` \| `"open-source"` | `"platform"` | Which backend to use |
| `userId` | `string` | OS username | Scope memories per user |
| `autoRecall` | `boolean` | `true` | Inject memories before each turn. Ignored when `skills` is configured. |
| `autoCapture` | `boolean` | `true` | Store facts after each turn. Ignored when `skills` is configured. |
| `autoRecall` | `boolean` | `true` | Inject memories before each turn, including when skills mode is configured. |
| `autoCapture` | `boolean` | `true` | Store facts after each turn, including when skills mode is configured. |
| `topK` | `number` | `5` | Max memories per recall |
| `searchThreshold` | `number` | `0.3` | Min similarity (0–1) |
@@ -441,7 +445,7 @@ If `openclaw plugins update` fails:
### Auto-Capture and Auto-Recall
Auto-capture and auto-recall are **enabled by default**. When skills mode is configured (the default after `openclaw mem0 init`), these are ignored in favor of the skills-based triage/recall/dream protocol.
Auto-capture and auto-recall are **enabled by default**. They also run when skills mode is configured (the default after `openclaw mem0 init`). Set `autoRecall` or `autoCapture` to `false` to disable the corresponding automatic hook while using skills.
To disable either:
@@ -464,13 +468,12 @@ The agent can always use memory tools (`memory_add`, `memory_search`, etc.) expl
### Credential Protection
The plugin never stores API keys, tokens, or secrets as memories. Five independent layers enforce this:
The plugin never stores API keys, tokens, or secrets as memories. Four independent layers enforce this:
1. **Triage gate**: The extraction prompt rejects values matching known credential patterns (`sk-`, `m0-`, `ghp_`, `AKIA`, `Bearer`, `password=`, `token=`, `secret=`)
2. **Dream cleanup**: Periodic memory consolidation deletes any memories that slipped through containing credential patterns
3. **Extraction instructions**: Default extraction rules explicitly instruct the model to store only that a credential was configured, never the value
4. **Configurable patterns**: Add custom credential patterns via `skills.triage.credentialPatterns`
5. **CLI redaction**: `openclaw mem0 config show` redacts sensitive fields (`apiKey`, `oss.*.config.apiKey`)
2. **Extraction instructions**: Default extraction rules explicitly instruct the model to store only that a credential was configured, never the value
3. **Configurable patterns**: Add custom credential patterns via `skills.triage.credentialPatterns`
4. **CLI redaction**: `openclaw mem0 config show` redacts sensitive fields (`apiKey`, `oss.*.config.apiKey`)
### API Key Storage
docs/integrations/opencode.mdx
+14 -26
View File
@@ -5,10 +5,14 @@ description: "Add persistent memory to OpenCode with the Mem0 plugin featuring n
Add persistent memory to [**OpenCode**](https://opencode.ai) with the Mem0 plugin. Your agent forgets everything between sessions. Mem0 fixes that by storing decisions, preferences, and learnings so they carry over automatically.
<Info>Current package version: `0.3.0`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent).
## Prerequisites
1. A Mem0 API key (starts with `m0-`):
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-opencode" rel="nofollow">Get your API key</a> (free sign-up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-opencode" rel="nofollow">app.mem0.ai</a>)
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-opencode">Get your API key</a> (free sign-up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-opencode">app.mem0.ai</a>)
2. Add it to your shell profile so it persists across sessions:
@@ -33,7 +37,7 @@ opencode plugin @mem0/opencode-plugin
**Or let your agent do it**: paste this into OpenCode:
```
Install @mem0/opencode-plugin by following https://raw.githubusercontent.com/mem0ai/mem0/main/integrations/mem0-plugin/.opencode-plugin/README.md
Install @mem0/opencode-plugin by following https://raw.githubusercontent.com/mem0ai/mem0/main/integrations/opencode-plugin/README.md
```
This adds the plugin to your `~/.config/opencode/opencode.json`. Restart OpenCode. You get the native memory tools, lifecycle hooks, and all `/mem0-*` slash commands. The memory tools are registered by the plugin itself via the `mem0ai` SDK. No MCP server to configure.
@@ -61,9 +65,9 @@ If you only need the memory tools without the plugin's hooks or skills, point Op
| Component | Plugin (A) | Standalone MCP (B) |
|-----------|:----------:|:------------------:|
| 9 memory tools | Native (SDK) | Remote MCP server |
| 10 memory tools | Native (SDK) | 9 remote MCP tools |
| Lifecycle Hooks | Yes | No |
| 9 Skills | Yes | No |
| 7 Skills | Yes | No |
## Available Memory Tools
@@ -78,6 +82,7 @@ If you only need the memory tools without the plugin's hooks or skills, point Op
| `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 |
| `get_event_status` | Check the processing status of an asynchronous memory event |
## Memory scope
@@ -87,9 +92,9 @@ If you only need the memory tools without the plugin's hooks or skills, point Op
|-------|-------|--------|
| `project` *(default)* | this repo (`user_id` + `app_id`) | this repo |
| `session` | this run only (`+ run_id`) | this run |
| `global` | **all your projects in the workspace** (`app_id: "*"`) | user-wide |
| `global` | **all your projects in the workspace** (filtered by your user ID) | user-wide |
Ask naturally, for example, *"search my memories across all my projects"*. The agent passes `scope: "global"`. For normal questions it stays scoped to the current project automatically.
Select `/mem0-scope global` before requesting a cross-project tool operation. A tool cannot enable global scope by supplying an argument alone. Switch back with `/mem0-scope project` when finished.
To change the **default** scope (used when no scope is passed), run the `/mem0-scope` skill:
@@ -110,30 +115,14 @@ The plugin uses the [mem0ai](https://www.npmjs.com/package/mem0ai) TypeScript SD
| OpenCode Event | Hook | What happens |
|----------------|------|-------------|
| `config` | **Config** | Registers the `/mem0-*` slash commands (`config.command`) and adds the plugin's own `opencode-skills/` dir to OpenCode's `skills.paths` for in-place skill discovery (no copying) |
| `chat.message` | **Chat message** | Searches prior memories on session start, searches relevant memories before each prompt, auto-captures learnings periodically |
| `chat.message` | **Chat message** | Searches prior memories on session start, searches relevant memories before each prompt, sends every third qualifying user prompt for extraction |
| `tool.execute.before` | **Pre-tool** | Blocks MEMORY.md writes, steering them to the `add_memory` tool |
| `tool.execute.after` | **Post-tool** | Scans Bash errors and pre-fetches related error memories |
| `experimental.chat.messages.transform` | **Messages transform** | Injects memory context (session memories, search results, error lookups) into the prompt |
| `experimental.session.compacting` | **Compaction** | Stores session state memory, then injects prior memories into compaction context so nothing is lost |
| `experimental.session.compacting` | **Compaction** | Stores session state memory, then injects prior memories into compaction context |
| `shell.env` | **Shell env** | Exports `MEM0_USER_ID`, `MEM0_APP_ID`, `MEM0_SESSION_ID`, and `MEM0_BRANCH` to all shell executions |
## Auto-dream (memory consolidation)
The plugin can automatically consolidate stored memories by merging duplicates, dropping stale/sensitive entries, and rewriting vague ones. This keeps your memory set clean over time. It runs at most once per session, and only when **all** gates pass:
- **Time**: at least `minHours` (default 24) since the last consolidation
- **Sessions**: at least `minSessions` (default 5) sessions since then
- **Memories**: at least `minMemories` (default 20) stored for the project
A filesystem lock (`~/.mem0/mem0-dream.lock`) keeps two sessions from consolidating at once. Tune the thresholds with a `dream` block in `~/.mem0/settings.json`, or disable entirely with `MEM0_DREAM=false`:
```json
{
"dream": { "enabled": true, "auto": true, "minHours": 24, "minSessions": 5, "minMemories": 20 }
}
```
If auto-dream hasn't run yet, it's almost always because a gate hasn't been met (most often too few memories). Run `/mem0-status` to see the exact gate progress (e.g. `sessions 2/5, memories 3/20`), `/mem0-dream` to consolidate **now** regardless of the gates, or lower the thresholds above.
Automatic capture sends the selected user prompt with its full redacted text, without a per-message character cutoff. It does not capture every prompt or the full assistant transcript. These automatic writes use user and project scope, with the session ID in `metadata.session_id`; session-scoped tools use top-level `run_id`. A session-scoped search therefore does not include automatic writes that lack `run_id`.
## Troubleshooting
@@ -141,7 +130,6 @@ If auto-dream hasn't run yet, it's almost always because a gate hasn't been met
- **"Connection failed"**: Verify your key is set: `echo $MEM0_API_KEY`
- **Plugin not loading**: Run `opencode plugin @mem0/opencode-plugin` again, then restart
- **Hooks not firing**: Hooks require the plugin install (Option A). MCP-only installs don't include hooks.
- **Auto-dream never runs**: It's gated (time + sessions + memories). Run `/mem0-status` to see which gate is blocking, or `/mem0-dream` to consolidate now.
- **Wrong project name / memories not found**: The project id comes from your git remote; launch OpenCode from inside the repo (not your home directory). Check the resolved id with `/mem0-status`.
<CardGroup cols={2}>
docs/integrations/pi-agent.mdx
+21 -43
View File
@@ -1,25 +1,28 @@
---
title: Pi Agent
description: "Add persistent memory to Pi Agent with the Mem0 plugin featuring semantic search, automatic capture, and dream consolidation for smarter agent recall."
description: "Add persistent memory to Pi Agent with the Mem0 plugin, semantic search, and automatic capture."
---
Add persistent memory to [**Pi Agent**](https://pi.dev) with `@mem0/pi-agent-plugin`. Your agent forgets everything between sessions. This plugin fixes that by automatically capturing knowledge from conversations, storing it in Mem0's cloud memory layer, and retrieving relevant context before every response.
<Info>Current package version: `0.3.0`.</Info>
Sidekick is available only in the [Claude Code plugin](/integrations/claude-code#sidekick-agent).
## Overview
The plugin provides:
1. **Auto-capture**: Extracts durable facts from both user and assistant messages automatically
2. **Semantic recall**: Retrieves relevant memories via the `mem0_memory` tool before each response
3. **Dream consolidation**: Periodic maintenance: merges duplicates, resolves contradictions, prunes stale entries
4. **Monorepo-aware scoping**: Uses git root for project detection, consistent across subdirectories
5. **Confirmation dialogs**: Destructive commands ask before acting via Pi's built-in UI
6. **8 skills + 8 commands**: Essential memory management from slash commands and agent-guided workflows
2. **Semantic recall**: Automatically searches project memories before each agent turn; `mem0_memory` supports additional explicit searches
3. **Monorepo-aware scoping**: Uses git root for project detection, consistent across subdirectories
4. **Confirmation dialogs**: Destructive commands ask before acting via Pi's built-in UI
5. **6 skills + 6 commands**: Essential memory management from slash commands and agent-guided workflows
## Prerequisites
1. A Mem0 Platform account and API key:
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-pi-agent" rel="nofollow">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-pi-agent" rel="nofollow">Get your API key</a> (starts with `m0-`)
- <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-pi-agent">Sign up at app.mem0.ai</a>
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-pi-agent">Get your API key</a> (starts with `m0-`)
2. Pi Agent installed ([pi.dev](https://pi.dev))
@@ -59,14 +62,7 @@ For advanced settings, create `~/.pi/agent/mem0-config.json`:
"userId": "your-username",
"autoCapture": true,
"defaultScope": "project",
"searchThreshold": 0.3,
"dream": {
"enabled": true,
"auto": true,
"minHours": 24,
"minSessions": 5,
"minMemories": 20
}
"searchThreshold": 0.3
}
```
@@ -76,12 +72,7 @@ For advanced settings, create `~/.pi/agent/mem0-config.json`:
| `userId` | `string` | `$MEM0_USER_ID` or `"default"` | User identity for memory scoping |
| `autoCapture` | `boolean` | `true` | Store facts from conversations automatically |
| `defaultScope` | `string` | `"project"` | Default memory scope: `project`, `session`, or `global` |
| `searchThreshold` | `number` | `0.3` | Minimum similarity score (0–1) a memory must reach to count as a match for `/mem0-search`, `/mem0-forget`, and `/mem0-pin`, enforced on each result's relevance score. Raise it to be stricter; lower it if relevant results are missed. |
| `dream.enabled` | `boolean` | `true` | Enable dream consolidation |
| `dream.auto` | `boolean` | `true` | Auto-trigger dreams when thresholds are met |
| `dream.minHours` | `number` | `24` | Minimum hours between auto-dreams |
| `dream.minSessions` | `number` | `5` | Minimum sessions before first auto-dream |
| `dream.minMemories` | `number` | `20` | Minimum memories before auto-dream triggers |
| `searchThreshold` | `number` | `0.3` | Minimum similarity score (0–1) a memory must reach to count as a match for `/mem0-search` and `/mem0-forget`, enforced on each result's relevance score. Raise it to be stricter; lower it if relevant results are missed. |
## What's Included
@@ -89,11 +80,10 @@ For advanced settings, create `~/.pi/agent/mem0-config.json`:
| Component | Description |
|-----------|-------------|
| `mem0_memory` tool | Agent-callable tool for search, add, get_all, delete, delete_all |
| 8 slash commands | Essential memory management from the command line |
| 8 skills | Guide the agent on how to use each capability |
| 6 slash commands | Essential memory management from the command line |
| 6 skills | Guide the agent on how to use each capability |
| Auto-capture | Extracts and stores facts on every `agent_end` event |
| System prompt | Appends memory policy to every agent turn |
| Dream consolidation | Automated memory maintenance with session/time/count gates |
## Agent Tool
@@ -119,8 +109,6 @@ Tool output is truncated to 200 lines / 50KB to prevent context overflow.
| `/mem0-forget <query>` | Search and delete memories (with confirmation dialog) |
| `/mem0-search <query>` | Semantic search across memories |
| `/mem0-tour [scope]` | Browse all memories grouped by category |
| `/mem0-dream` | Consolidate: merge duplicates, prune stale, resolve contradictions |
| `/mem0-pin <query>` | Pin a memory to protect from dream pruning (preserves memory ID) |
| `/mem0-scope <scope>` | Change default scope for this session (project, session, global) |
| `/mem0-status` | Connection health, identity, and memory count |
@@ -131,28 +119,19 @@ Memories are scoped using Mem0's `user_id`, `app_id`, and `run_id` parameters:
| Scope | Filters | Use Case |
|-------|---------|----------|
| `project` | user_id + app_id (git root) | **Default.** Project-specific knowledge: decisions, architecture, config |
| `session` | user_id + app_id + run_id | Ephemeral context for the current session only |
| `session` | user_id + app_id + run_id | Memories saved with the current session ID (no automatic expiration) |
| `global` | user_id only | All memories across all your projects |
The `app_id` is auto-detected from the git repository root (`git rev-parse --show-toplevel`), so all subdirectories within a monorepo share the same memory pool. Falls back to the working directory name for non-git directories. The `run_id` is derived from Pi's session file path.
The `app_id` is auto-detected from the git repository root (`git rev-parse --show-toplevel`), so all subdirectories within a monorepo share the same memory pool. Falls back to the working directory name for non-git directories. The `run_id` is derived from Pi's session file path. Automatic recall and capture use project scope, regardless of `defaultScope`; automatic writes do not include `run_id`. Use session-scoped tools or commands to save and recall session-specific memories. Captured user and assistant message text is redacted without a per-message character cutoff.
## Dream Consolidation
Global tool operations require `/mem0-scope global` or `defaultScope: "global"` in plugin configuration. A model-supplied `scope` argument cannot enable cross-project access on its own. Empty or wildcard user, project, and session identities are rejected.
### Confirmation Dialogs
## Confirmation Dialogs
Destructive and mutating commands use Pi's built-in `ctx.ui.confirm()` dialog before acting:
- `/mem0-forget` asks "Delete this memory?" before deleting a single match
- `/mem0-pin` asks "Pin this memory?" before modifying it
- Cancelling either operation is always safe. No changes are made
### Pin
`/mem0-pin` uses Mem0's `update()` API to prepend `[PINNED]` to the memory text. This preserves the original memory ID. There is no add+delete cycle that would lose history or change the UUID.
### Dream Consolidation
The plugin includes automated memory maintenance ("dream") that merges duplicates, resolves contradictions, and prunes stale entries. When enabled, dreams auto-trigger after enough sessions, time, and memories accumulate (configurable via `dream.*` settings). Run `/mem0-dream` to trigger consolidation manually at any time. Pinned memories (via `/mem0-pin`) are protected from pruning.
- Cancelling the operation is always safe. No changes are made.
## Example Workflow
@@ -169,10 +148,9 @@ You: What do you know about my preferences?
## Troubleshooting
- **"No API key found"**: Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY`. If empty, add it to your shell profile (see Prerequisites)
- **Extension not loading**: Check Pi startup output for errors. Run `pi -e ./src/entry.ts` from the plugin directory for verbose output
- **Extension not loading**: Check Pi startup output for errors. For a source checkout, run `pnpm build`, then `pi -e ./dist/entry.js` from the plugin directory
- **Memories not capturing**: Verify `autoCapture` is `true` (default). Check `/mem0-status` for connection health
- **Wrong project detected**: The plugin uses the git repository root as `app_id`. If not in a git repo, it falls back to the working directory name. Run `/mem0-status` to see the detected project
- **Dream not triggering**: All three gates must pass (time, sessions, memories). Use `/mem0-dream` to force it manually
<CardGroup cols={2}>
<Card title="Claude Code Integration" icon="/images/provider-icons/anthropic.svg" href="/integrations/claude-code">
docs/integrations/raycast.mdx
+1 -1
View File
@@ -9,7 +9,7 @@ Mem0 is a self-improving memory layer for LLM applications, enabling personalize
**Get your API Key**: You'll need a Mem0 API key to use this extension:
a. Sign up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-raycast" rel="nofollow">app.mem0.ai</a>
a. Sign up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-raycast">app.mem0.ai</a>
b. Navigate to your API Keys page
docs/integrations/respan.mdx
+1 -1
View File
@@ -16,7 +16,7 @@ Combining Mem0 with Respan allows you to:
4. Optimize token usage and reduce costs
<Note>
You can get your Mem0 API key from the <a href="https://app.mem0.ai/?utm_source=oss&utm_medium=integration-respan" rel="nofollow">Mem0 dashboard</a>.
You can get your Mem0 API key from the <a href="https://app.mem0.ai/?utm_source=oss&utm_medium=integration-respan">Mem0 dashboard</a>.
</Note>
## Setup and Configuration
docs/integrations/strands.mdx
+69
View File
@@ -0,0 +1,69 @@
---
title: Strands Agents
description: "Add persistent long-term memory to AWS Strands agents with Mem0, as a native MemoryStore that plugs into the agent loop."
---
Integrate [**Mem0**](https://github.com/mem0ai/mem0) with [Strands Agents](https://github.com/strands-agents/sdk-python), AWS's open-source SDK for building AI agents. The [`mem0-strands`](https://github.com/mem0ai/mem0/tree/main/integrations/mem0-strands) package ships a native `MemoryStore`, so recall and writes happen automatically inside the agent loop, not as tool calls the model has to remember.
## Overview
1. A `MemoryStore` the `MemoryManager` drives on every turn: it searches Mem0 and injects the results into the prompt, and writes memory back when extraction is enabled.
2. Server-side extraction: because the store implements `add_messages`, enabling `extraction` routes raw conversation turns to Mem0's own extraction pipeline, with no extra client-side model call.
3. Works with the hosted Mem0 Platform (an API key) or self-hosted Mem0 OSS (a config dict).
## Prerequisites
Before setting up Mem0 with Strands, ensure you have:
1. Installed the required packages:
```bash
pip install mem0-strands
```
2. A valid API key:
- <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-strands">Mem0 API Key</a> (set as `MEM0_API_KEY`)
## Basic Integration Example
Hand a `Mem0MemoryStore` to a `MemoryManager`, and the agent gets automatic recall and memory writes:
```python
import os
from strands import Agent
from strands.memory import MemoryManager
from mem0_strands import Mem0MemoryStore
os.environ["MEM0_API_KEY"] = "your-mem0-api-key"
# extraction=True routes conversation turns to Mem0's server-side extraction.
store = Mem0MemoryStore(user_id="alex", extraction=True)
agent = Agent(memory_manager=MemoryManager(stores=[store]))
agent("Remember I use Neovim and deploy on Fridays.") # writes memory
print(agent("What editor do I use?")) # recalls it, injected automatically
```
Scope memories with any of `user_id`, `agent_id`, `run_id`, or `app_id` (`app_id` is platform-only). Pass `max_search_results` to bound how many memories are injected per turn.
## Self-hosted Mem0 (OSS)
To run against self-hosted Mem0 instead of the platform, pass a `config` dict:
```python
store = Mem0MemoryStore(
user_id="alex",
extraction=True,
config={
"vector_store": {"provider": "qdrant", "config": {"host": "localhost", "port": 6333}},
},
)
```
## Explicit memory tool
If you want the model to call memory explicitly instead of (or alongside) the automatic store, use the `mem0_memory` tool from `strands-agents-tools`. A store and the tool can share the same Mem0 backend and namespace.
## Learn more
- [mem0-strands on GitHub](https://github.com/mem0ai/mem0/tree/main/integrations/mem0-strands)
- [Strands Agents documentation](https://strandsagents.com)
docs/integrations/vercel-ai-sdk.mdx
+1 -1
View File
@@ -37,7 +37,7 @@ The only true peer dependency is `zod` (optional):
### Setting Up Mem0
1. Get your **Mem0 API Key** from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-vercel-ai-sdk" rel="nofollow">Mem0 Dashboard</a>.
1. Get your **Mem0 API Key** from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-vercel-ai-sdk">Mem0 Dashboard</a>.
2. Initialize the Mem0 Client in your application:
docs/integrations/vercel.mdx
+130
View File
@@ -0,0 +1,130 @@
---
title: Vercel
description: "Add persistent memory to your Vercel apps with the Mem0 Vercel Marketplace integration. Install from the Marketplace, get an API key, and start building."
---
The **Mem0 Vercel integration** provisions managed Mem0 access directly from the [Vercel Marketplace](https://vercel.com/marketplace). Installing it creates a Mem0 account for you and injects a `MEM0_API_KEY` into your Vercel project, so you can add long-term memory to your AI apps and agents in minutes, with no separate signup and billing handled through Vercel.
<Note type="info">
This is the managed Marketplace integration. If you instead want to use Mem0 with the Vercel AI SDK in code, see [Vercel AI SDK](/integrations/vercel-ai-sdk).
</Note>
## Overview
When you install Mem0 from the Vercel Marketplace:
- A Mem0 account and project are created for you (Vercel Native).
- Mem0 environment variables (`MEM0_API_KEY`, `MEM0_ORG_ID`, `MEM0_PROJECT_ID`, `MEM0_BASE_URL`) are added to your connected Vercel project.
- Billing is handled through your Vercel account, with no separate Mem0 subscription.
You call Mem0 from your app with the injected key. There is nothing else to wire up.
## Install
<Steps>
<Step title="Add the integration">
From the [Vercel Marketplace](https://vercel.com/marketplace), find **Mem0** and click **Install**. Choose **Create New Mem0 Account** (Vercel Native).
</Step>
<Step title="Pick a plan">
Select **Hobby** (free) or **Starter** ($20/month). You can change this anytime from the installation settings in your Vercel dashboard.
</Step>
<Step title="Connect a project">
Connect the Mem0 resource to a Vercel project. Mem0 injects its environment variables into that project.
</Step>
<Step title="Redeploy">
Redeploy so the variables are available at runtime, or run `vercel env pull` to use them locally.
</Step>
</Steps>
## Environment variables
The integration sets the following on your connected project:
| Variable | Description |
| --- | --- |
| `MEM0_API_KEY` | Your Mem0 API key, scoped to the org and project created for this installation. This is what you authenticate with. |
| `MEM0_ORG_ID` | The Mem0 organization id for this installation. |
| `MEM0_PROJECT_ID` | The Mem0 project id for this installation. |
| `MEM0_BASE_URL` | The Mem0 API base URL (`https://api.mem0.ai`). |
The API key is scoped to your org and project, so the SDK needs only `MEM0_API_KEY` to get started.
## Quickstart
Install the SDK:
<CodeGroup>
```bash npm
npm install mem0ai
```
```bash pip
pip install mem0ai
```
</CodeGroup>
Add and search memories using the injected key:
<CodeGroup>
```typescript JavaScript
import MemoryClient from "mem0ai";
const memory = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
// Store a memory
await memory.add(
[{ role: "user", content: "I'm a vegetarian and allergic to nuts." }],
{ userId: "user123" },
);
// Retrieve relevant memories
const results = await memory.search("What are my dietary restrictions?", {
filters: { user_id: "user123" },
});
console.log(results);
```
```python Python
import os
from mem0 import MemoryClient
memory = MemoryClient(api_key=os.environ["MEM0_API_KEY"])
# Store a memory
memory.add(
[{"role": "user", "content": "I'm a vegetarian and allergic to nuts."}],
user_id="user123",
)
# Retrieve relevant memories
results = memory.search("What are my dietary restrictions?", filters={"user_id": "user123"})
print(results)
```
</CodeGroup>
See the [platform quickstart](/platform/quickstart) for the full API.
## Plans and billing
| Plan | Price | Memories | Retrieval calls | Projects | Support |
| --- | --- | --- | --- | --- | --- |
| Hobby | Free | 10,000 | 1,000 / month | 1 | Community |
| Starter | $20 / month | 50,000 | 5,000 / month | 1 | Community |
Billing runs through your Vercel account; Mem0 never charges your card directly. You can upgrade or downgrade anytime from the installation's settings in the Vercel dashboard.
## Managing the integration
- **Change plan:** open the installation in your Vercel dashboard and update the billing plan.
- **Open in Mem0:** use the **Open in Mem0** link to sign in to the Mem0 dashboard for this installation.
- **Uninstall:** removing the integration deactivates the API key and tears down the resource. Any usage for the current period is invoiced before removal.
## Notes
- The integration creates a **new** Mem0 account for the installation. Linking an existing Mem0 account is not supported yet.
- The injected `MEM0_API_KEY` is scoped to the org and project created for this installation, so you do not manage keys by hand.
## Related
- [Platform quickstart](/platform/quickstart)
- [Vercel AI SDK integration](/integrations/vercel-ai-sdk)
docs/integrations/zapier.mdx
+2 -2
View File
@@ -14,7 +14,7 @@ Zaps fire and forget. The [Mem0](https://mem0.ai) app gives them memory: store d
## Prerequisites
1. A Mem0 API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-zapier" rel="nofollow">API Keys dashboard</a> (sign up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-zapier" rel="nofollow">app.mem0.ai</a> if you do not have an account).
1. A Mem0 API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-zapier">API Keys dashboard</a> (sign up at <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-zapier">app.mem0.ai</a> if you do not have an account).
2. A Zapier account on any plan.
<Note>
@@ -126,7 +126,7 @@ The **User ID** is a stable string you pick to identify whose memories these are
## Troubleshooting
- **Mem0 does not appear in the Zap editor**: the app is not yet in the public App Directory. Email [support@mem0.ai](mailto:support@mem0.ai) for an invite link.
- **The connection fails when you paste the key**: check that it starts with `m0-` and has not been revoked in the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-zapier" rel="nofollow">API Keys dashboard</a>.
- **The connection fails when you paste the key**: check that it starts with `m0-` and has not been revoked in the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-zapier">API Keys dashboard</a>.
- **Search returns nothing right after an Add**: extraction is asynchronous. Turn on **Wait for Completion**, or put a Zapier **Delay** step before the Search.
- **"Metadata must be valid JSON" or "Custom Categories must be valid JSON"**: those fields take raw JSON. Check for smart quotes and trailing commas.
- **The Add step times out**: the memory was still accepted and is likely finishing server-side. Confirm with **Get Memories** before re-running.