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 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:

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

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 <n>, --category <name>, and --scope <repo|team|mine|all>.
/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.

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:

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.

Mem0 MCP Setup

Detailed MCP configuration for all clients

Codex Integration

Add Mem0 memory to OpenAI Codex workflows

Using Mem0? Star us on GitHub to help more developers discover memory for AI apps.