> ## Documentation Index
> Fetch the complete documentation index at: https://mem0-feature-memo-claude-plugin-v1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Claude Code
> Cross-session memory for Claude Code: automatic local-first capture, first-prompt recall, a read-only search tool, and a Sonnet sidekick agent in an isolated worktree.
Add persistent, cross-session memory to [**Claude Code**](https://docs.anthropic.com/en/docs/claude-code) with the Mem0 plugin. Claude Code forgets everything between sessions. This plugin fixes that: hooks capture small session details locally, a background worker turns them into Mem0 memories after the session, and Claude searches those memories automatically before its first response in a later session.
## Prerequisites
Before setting up Mem0 with Claude Code, ensure you have:
1. A Mem0 Platform account and API key:
* Sign up at app.mem0.ai
* Get your API key (starts with `m0-`)
2. A Claude Code version that supports plugin agents, worktree isolation for agents, and the `SubagentStart`, `SubagentStop`, and `PostToolUseFailure` hook events.
3. Python 3.10+ and Git available on your machine.
## Installation
Add the Mem0 marketplace and install the plugin:
```bash theme={null}
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
```
Restart Claude Code after installing (or run `/reload-plugins` in an existing session to refresh plugins without restarting), then open a Git repository and work normally.
### Managing the plugin
```bash theme={null}
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)
```
## How memory works
1. During a session, hooks save small details on your computer: user messages, Claude's final answers, changed file paths, and short test/build results. No hook calls a model or blocks the session.
2. After every five completed exchanges, a detached background worker sends that part of the session to Mem0. A large exchange is sent sooner, and compacting or ending the session sends anything that remains. The worker survives Claude Code exiting. Test and build command details stay on your computer unless Claude mentions a conclusion in its visible response.
3. Mem0 turns the submitted conversation and changed paths into memories that may help with later work in the same repository.
4. Before Claude's first response in a later session, the plugin automatically searches with your prompt and supplies up to five memories, without calling another model to write the query.
After that first automatic search, Claude can call the `search_memories` tool with one specific question, and you can run the same search yourself with `/mem0:search`. Those explicit searches return at most three memories by default (configurable up to 20). Each one runs fresh, so asking the same question again can return the same memory; only the automatic first search avoids repeating a memory it already supplied in that session. All returned memory context is capped at 4,000 characters, and results are not reranked or filtered by another score cutoff.
### Operating notes
Alongside what the repository *is*, Mem0 records what it takes to *work* in it. When a command fails during a session, the background worker sends that session's commands to Mem0 under the repository's `claude-code` agent, and Mem0 writes short operating notes: the invocation that failed, the error it returned, and the invocation that worked afterwards.
A session in which nothing failed sends no operating evidence at all, because a session that met no friction teaches an agent nothing about working there. Operating notes come back from the same searches as everything else, marked `[operating note]`, and hold a minority of the slots in any result: at most one of three for an explicit search, two of five for the automatic one, so they never crowd out repository knowledge. Set `agent_memory` to `false` to switch them off.
Operating notes are the only path by which command details leave your computer without Claude repeating them in its visible response. Values that look like credentials are redacted first, as they are from everything else the plugin sends.
## Commands
| Command | What it does |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/mem0:search` | Search memories from earlier Claude Code sessions in this repository. Accepts `--top-k `, `--category `, and `--scope `. |
| `/mem0:status` | Show whether Mem0 memory is working in this repository: configuration, capture state, pending flushes, and whether the Mem0 API key is valid. |
| `/mem0:forget` | Delete the Mem0 memories stored for this repository and user, plus the repository's operating notes, after confirming with you. |
| `/mem0:pause` | Pause Mem0 memory capture on this machine. |
| `/mem0:resume` | Resume Mem0 memory capture after it was paused with `/mem0:pause`. |
| `/mem0:remember` | Acknowledge a "remember this" request and make sure it is captured well in Claude's reply. |
`/mem0:search` can filter to one memory category: `project_knowledge`, `decisions_and_constraints`, `workflows`, `problems_and_fixes`, or `results`. Without `--category`, it searches all of them.
## Search scope
Every memory is written with the repository it came from (`app_id`) and one owner label: the person who wrote it (`user_id`), or, for an operating note, the agent that learned it (`agent_id`, always `claude-code`). A search combines the repository with the owner using `AND`, so by default you get back what you recorded in the repository you are working in, plus that repository's operating notes. The scope chooses which label is relaxed to a `*` wildcard.
| Scope | What you get back |
| ---------------- | --------------------------------------------------------------- |
| `repo` (default) | Your memories in this repository, and its operating notes |
| `team` | Everyone's memories in this repository, and its operating notes |
| `mine` | Your memories in every repository |
| `all` | Both `team` and `mine`, combined |
`team` is the team search: your colleagues' decisions, fixes, and conventions for the repository you share. `mine` is for your own preferences, which follow you between repositories. Operating notes belong to a repository rather than to a person, so they appear in the two repository-scoped searches and not in `mine`.
Every scope keeps at least one label pinned to something you already have, so no scope returns memories from a repository you are not in that were also written by somebody else. Set the default for every search with the `search_scope` setting or the `MEM0_CODE_SEARCH_SCOPE` environment variable; `--scope` on a single search overrides it.
## Sonnet sidekick agent
`mem0:sidekick` is a Sonnet coding agent with normal file, search, shell, editing, testing, and web tools. Claude Code runs it in a separate Git worktree with its own conversation, so it can investigate, implement, test, debug, or review something instead of the main session doing the same work, which reduces cost when the main agent doesn't need to repeat the work itself.
```text theme={null}
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.
```
The main agent reviews the sidekick's result, and corrections go back to the same agent so it keeps what it already learned. Changes stay in the sidekick's worktree until the main agent reviews and copies them into the main checkout. By default the worktree is created from the repository's default branch; set `worktree.baseRef` to `"head"` in the repository's Claude settings to create it from the main session's current commit instead. Uncommitted changes are not copied into the sidekick's worktree.
## Settings
| Setting | Default | What it controls |
| ------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `api_key` | required | Mem0 Platform API key used to create and search memories. |
| `user_id` | your local account name | Optional stable ID shared across machines, matching the earlier Mem0 Claude Code plugin's scoping. |
| `top_k` | `3` | Maximum memories returned when Claude runs another search after the automatic first search (1 to 20). |
| `max_context_chars` | `4000` | Maximum memory characters returned for one search (1,000 to 10,000). |
| `search_scope` | `repo` | Default breadth for every search: `repo`, `team`, `mine`, or `all`. Also read from `MEM0_CODE_SEARCH_SCOPE`. |
| `agent_memory` | `true` | Whether to record operating notes: what it took to run, test, and build in this repository. Also read from `MEM0_CODE_AGENT_MEMORY`. |
## Upgrading from 0.2.x
This is a breaking major update to the Claude Code plugin. It replaces the 0.2.x architecture and command set. Your memories carry over untouched; most local configuration does not:
* **Memories carry over automatically.** The plugin keeps the same user and repository scoping the 0.2.x plugin used, including `~/.mem0/project_map.json`, so existing memories for a repository stay available after upgrading.
* **Environment variables keep working.** `MEM0_API_KEY`, `MEM0_USER_ID`, and `MEM0_PROJECT_ID` are still honored.
* **Commands are replaced.** The 0.2.x command set is replaced by `/mem0:search`, `/mem0:status`, `/mem0:forget`, `/mem0:pause`, `/mem0:resume`, and `/mem0:remember`.
* **The hosted MCP server is replaced.** Its nine read/write tools (`add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, `delete_all_memories`, `delete_entities`, `list_entities`) are replaced by the single, read-only `search_memories` tool described above.
* **Local config files are no longer read.** `~/.mem0/settings.json` and per-project `mem0.md` files are ignored.
* **Old memories are still searchable, but not by category.** Normal search finds memories created before the upgrade, but the new category filters do not find them.
Update with the same commands used for any other update:
```bash theme={null}
claude plugin marketplace update mem0-plugins
claude plugin update mem0@mem0-plugins --scope user
```
## Troubleshooting
* **Missing key**: reinstall with `--config api_key="$MEM0_API_KEY"` while `MEM0_API_KEY` is set to a non-empty value.
* **`401 Unauthorized`**: the configured Mem0 key is invalid or expired. `/mem0:status` reports this clearly.
* **No memory immediately after ending a session**: memory creation runs in the background after the session ends. Wait briefly, then search again.
* **Sidekick agent does not start**: make sure the current folder is a Git repository and your Claude Code version supports plugin agents and worktrees.
* **Remove the plugin**: `claude plugin uninstall mem0@mem0-plugins`.
Detailed MCP configuration for all clients
Add Mem0 memory to OpenAI Codex workflows