What is Claude Mem?
Claude Mem is a persistent-context plugin for Claude Code. It watches the work Claude performs, turns that activity into structured observations and session summaries, stores them by project, and makes useful history available in later sessions.
The problem
A new Claude Code session normally starts without the full working context from yesterday, so you may need to repeat decisions, discoveries, and unfinished work.
The practical benefit
Claude Mem can bring back relevant project history and provide search tools, reducing repeated explanations and unnecessary rediscovery.
It is not unlimited memory. Claude Mem stores selected project activity and injects or retrieves a limited, relevant portion. It does not make Claude remember every word, every file, or every event automatically.
How it works
Claude Code hooks observe prompts and tool activity such as reading files, editing code, and running commands.
A local worker sends captured activity to the memory provider you selected so it can be compressed into structured observations and summaries.
The resulting memory, search index, settings, and logs are stored under ~/.claude-mem/ on your computer and associated with the project.
On a later start, Claude Mem injects recent relevant context. Claude can also use its search tools when you ask about older project history.
Before you start
- Claude Code installed and able to open a project.
- Node.js 20 or newer. Check with
node --version. - A terminal with internet access for the interactive installer.
- Permission to install Bun and uv if they are missing. The recommended installer checks and installs them.
- A memory-provider choice. The current installer can guide you through Claude, Gemini, OpenRouter, or Claude Mem's hosted observer. Provider pricing, trials, quotas, and terms can change.
node --version
Install Claude Mem
Close any Claude Code sessions you do not need, open a normal terminal, and run the official interactive installer:
npx claude-mem install
The installer checks the runtime, detects Claude Code, registers the plugin and hooks, lets you choose a memory provider, installs dependencies, and starts the worker service. Follow the prompts until it reports that installation is complete.
Do not use npm install -g claude-mem for this setup. The official documentation says that installs only the SDK/library; it does not register the Claude Code hooks or start the worker.
Alternative: install inside Claude Code
If you prefer Claude Code's plugin marketplace, enter these slash commands inside Claude Code—not in your operating-system terminal:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
Restart Claude Code after the marketplace installation so the new hooks load.
Connect and configure it with Claude Code
- Select Claude Code in the installer. The current installer can detect several tools; make sure Claude Code is selected when it asks which IDEs to wire up.
- Complete or skip the optional sign-in. The installer explains when sign-in applies. You can also choose an explicit provider without the hosted sign-in flow.
- Choose the memory provider. This provider processes captured activity into observations. If you choose Claude, select the compression model when prompted; other providers require their own credentials.
- Let the installer write the hooks. Do not hand-edit the installed marketplace copy. The official installer creates the Claude Code hook and MCP configuration.
- Restart Claude Code. Open a fresh session in the project you want Claude Mem to learn.
Later, use the web viewer's settings panel to control how many observations and sessions are injected. More history uses more context and can make startup slower.
Start using it
Use Claude Code normally. You do not need to write special memory prompts.
Describe a real project task, such as fixing a bug or adding a feature.
Claude reads files, edits code, searches the project, and runs commands. Claude Mem's hooks capture eligible activity.
The local worker asynchronously turns activity into observations with titles, facts, concepts, file references, and classifications.
The Stop hook queues a session summary covering the request, investigation, learning, completed work, and possible next steps.
Your first session seeds memory. Automatic project-memory injection begins when you return for a second session in that project.
Start a new session
Exit Claude Code, return to the same project folder, and start Claude Code again:
cd YOUR_PROJECT claude
The SessionStart hook queries recent observations and summaries for that project and adds a formatted memory index to Claude's initial context. You can continue naturally:
Continue the work from our last session. What was completed, and what should we do next?
If you ask about older work—such as a past bug, decision, or file—Claude can use Claude Mem's search, timeline, and observation tools to retrieve more detail.
How to check that memory is working
~/.claude-mem/claude-mem.db exists. This is the local SQLite memory database.npx claude-mem doctor
npx claude-mem status
What Claude Mem should and shouldn't remember
It can preserve
Eligible user prompts, tool inputs and outputs, files read or changed, structured observations, project discoveries, decisions, bug fixes, and session summaries.
It does not guarantee
A perfect verbatim record, automatic recall of every stored item, awareness of work from another machine, or correct interpretation of every observation.
Claude Mem uses progressive disclosure: a compact recent-memory index is injected first, then fuller details are retrieved when relevant. The available context is bounded by your settings and the quality of the stored observations and search query.
Stored does not mean currently visible to Claude. An item may exist in the local database but not be included in the next session's initial context. Ask a specific question so the search tools can retrieve older details.
Privacy & security
- Local storage: the SQLite database, vector index, settings, and logs live under
~/.claude-mem/by default. Treat that directory as sensitive project data. - Provider processing: captured activity is sent to the memory provider you configure so it can create compressed observations. Review that provider's privacy, retention, and billing terms before using private repositories.
- What may be captured: official architecture documentation lists raw user prompts, tool inputs and outputs, file paths, and session summaries. Do not paste passwords, API keys, customer data, private tokens, or production secrets into routine prompts or commands.
- Local network boundary: the worker binds to
127.0.0.1by default. Do not expose its port publicly without understanding and securing the service. - Keep it updated: only the latest release receives security updates according to the project's security policy.
Exclude a sensitive prompt from memory
The official privacy control is to wrap the entire sensitive prompt in <private> tags. Claude Mem strips private content before it reaches the memory worker and database.
<private> Do not store this prompt in Claude Mem. </private>
Check optional telemetry
The current CLI includes controls for anonymous telemetry. Review its status and disable it if that matches your privacy requirements:
npx claude-mem telemetry status
npx claude-mem telemetry disable
Troubleshooting
The installer finishes but Claude Code has no memory
Restart Claude Code, work through one real session, and return in a second session from the same project folder. The first session seeds memory; injection starts on the second session.
Claude Mem reports missing or stale dependencies
Run npx claude-mem repair. The official repair flow reruns Bun and uv setup, installs plugin dependencies, and refreshes the install-version marker.
The worker is not running
Run npx claude-mem doctor, then npx claude-mem start. If it still fails, inspect the worker logs under ~/.claude-mem/logs/ and check whether another process is using the configured port.
The plugin marketplace cannot find Claude Mem
Inside Claude Code, add the marketplace first with /plugin marketplace add thedotmack/claude-mem, then run /plugin install claude-mem. Restart Claude Code afterward.
No observations appear in the viewer
Confirm the worker is healthy, then ask Claude to perform a task that uses tools such as reading or editing a file. Processing is asynchronous, so allow a moment for observations to appear. Check that your selected memory provider is authenticated and available.
Previous context is not relevant
Make sure you reopened the same project path. Ask a more specific question about the file, decision, bug, or date so Claude can use the search tools. You can also adjust observation and session limits in the viewer's Context Settings panel.
Search returns no results
First confirm that the database contains observations in the viewer. Use simple keywords without special characters, and search for a known file or decision from the completed session.
Windows hooks say Bun is not recognized
Update Claude Mem to the latest release, run npx claude-mem repair, and restart Claude Code. The current launcher resolves the Bun executable directly; an unusually long Windows PATH can still cause command failures.
I installed with npm globally and nothing happens
Remove that assumption from the setup and run npx claude-mem install. A global npm library install does not register the Claude Code plugin hooks.
npx claude-mem repair
npx claude-mem update
Official sources checked for this guide
- Claude Mem 13.21.2 release ↗
- Official installation guide ↗
- Official getting-started and session workflow guide ↗
- Official configuration and context-injection guide ↗
- Official hooks, stored data, and privacy architecture ↗
- Official troubleshooting guide ↗
- Official security policy ↗
- Current official CLI command reference ↗
Last verified September 1, 2026. Claude Mem changes quickly; recheck the official installer and release notes if you are reading this later.