docs/integrations/claude-code.mdx
Add persistent memory to 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.
Before setting up Mem0 with Claude Code, ensure you have:
A Mem0 Platform account and API key:
m0-)Claude Code CLI or Claude Cowork desktop app installed
Your API key added to your shell profile (persists across sessions):
echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
source ~/.bashrc
Confirm it's set:
echo $MEM0_API_KEY
# Should print: m0-your-api-key
Install the full plugin including MCP server, lifecycle hooks, and SDK skill.
Add the Mem0 marketplace:
claude plugin marketplace add mem0ai/mem0
Install the plugin:
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.
Add the Mem0 MCP server directly with a single command:
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.
Add to your Claude Code MCP config (.mcp.json):
{
"mcpServers": {
"mem0": {
"type": "http",
"url": "https://mcp.mem0.ai/mcp/",
"headers": {
"Authorization": "Token ${MEM0_API_KEY}"
}
}
}
}
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 uninstall mem0@mem0-plugins # uninstall the plugin (keeps the marketplace)
claude plugin marketplace remove mem0-plugins # unregister the marketplace entirely
/mem0:onboardAfter installing the plugin, start a new Claude Code session and run:
/mem0:onboard
This runs the setup wizard which:
CLAUDE.md, AGENTS.md, .cursorrules)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.
| Component | Plugin Install | MCP Only |
|---|---|---|
| MCP Server (9 memory tools) | Yes | Yes |
| Lifecycle Hooks | Yes | No |
| Mem0 SDK Skill | Yes | No |
Once installed, the following tools are available in every Claude Code session:
| 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 |
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.
# Session 1: Working on a feature
You: Let's refactor the auth module to use JWT tokens instead of sessions.
# 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
# Session 2 (days later): Related work
You: Add refresh token rotation to the auth system.
# 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.
MEM0_API_KEY is set in your shell: echo $MEM0_API_KEY. If empty, add it to your shell profile (see Prerequisites)export MEM0_API_KEY="m0-..." to your ~/.zshrc (or ~/.bashrc) and run source ~/.zshrc