Claude Code

Claude Code forgets everything between sessions. This plugin fixes that. Install it, work normally, and Claude remembers what happened across sessions.

Prerequisites

1. A Mem0 Platform account and API key (starts with m0-):

   • Sign up at app.mem0.ai
   • Get your API key

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 on your machine.

Quick start

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 (or run /reload-plugins), open a Git repository, and work normally. That's it.

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)

What you can do

Automatic memory

Once installed, memory works without any action from you:

• Capture happens in the background as you work. Hooks save user messages, Claude's answers, changed files, and test/build results locally. Nothing calls a model or slows your session.
• Recall happens automatically before Claude's first response in a new session. The plugin searches your memories with your prompt and injects up to five relevant ones.

Commands

Categories for --category: project_knowledge, decisions_and_constraints, workflows, problems_and_fixes, results. Without it, all categories are searched.

Search tool

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). All results are capped at 4,000 characters.

Sidekick agent

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.

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.

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.

How it works

The plugin follows a simple cycle: capture during a session, extract memories in the background, recall in the next session.

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. Subagent (sidekick) output is excluded. No model calls, no blocking.

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 a single add call with agent_id (the project identity), user_id (you), app_id (the repository), and run_id (the session). 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.

Search scope

Every memory carries identifiers showing where it came from:

A search returns the union of shared project memory and your personal preferences. The scope narrows the project part:

The dir scope is hierarchical: a parent directory sees everything in its children, but a child never sees the parent's memories.

Pass --run-id <session-id> to see only what one specific session recorded. Set the default scope with the search_scope setting or MEM0_CODE_SEARCH_SCOPE env var.

Settings

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 searchable, not by category. Normal search finds pre-upgrade memories, but category filters do not.

claude plugin marketplace update mem0-plugins
claude plugin update mem0@mem0-plugins --scope user

Troubleshooting