Skip to main content
Claude Code forgets everything between sessions. This plugin fixes that. Install it, work normally, and Claude remembers what happened across sessions.
Current plugin version: 0.3.1.

​
Prerequisites

  1. A Mem0 Platform account and 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 on your machine.

​
Quick start

Restart Claude Code (or run /reload-plugins), open a Git repository, and work normally. That’s it.

​
Managing the plugin

​
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. 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.

​
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). 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.

​
Sidekick agent

Sidekick is available only in Claude Code. 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.
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. 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.

​
How it works

The plugin follows a simple cycle: capture during a session, extract memories in the background, recall in the next session.
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.
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.
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.

​
Search scope

Every memory carries identifiers showing where it came from: 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: 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

​
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.

​
Troubleshooting

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.