Claude-Mem is a third-party persistent-memory plugin for AI coding tools, including Claude Code. It captures work through hooks, processes observations and session summaries, and makes relevant history available to later sessions. The project is maintained in thedotmack/claude-mem; it is separate from Anthropic's built-in memory features.
For a Claude Code setup using your existing Anthropic plan, the current official installation guide documents npx claude-mem install --provider claude. This skips the Claude-Mem account sign-in step, but memory processing still uses your plan. The steps below are documentation-based; we have not installed the plugin or tested recall quality.
Decide whether you need the plugin
Claude Code already supports persistent instructions in CLAUDE.md and auto memory. Anthropic's memory documentation distinguishes instructions you maintain from notes Claude writes about preferences and project learnings. You do not need Claude-Mem just to give Claude recurring project rules.
Claude-Mem adds a separate capture, storage and retrieval pipeline. Its documented use case is finding earlier development work: what was changed, why a decision was made, or how a bug was investigated. It uses a worker service, a local database and search tools. Retrieved history remains context to review, rather than a guarantee that every stored conclusion is correct or current.
This guide focuses on desktop Claude Code. The project also documents other hosts, but their installers and capture mechanisms differ; do not apply these hook instructions to a web chat or assume every integration behaves identically.
Check the platform and prerequisites
The official installation guide, checked October 23, 2026, lists:
| Requirement | What to check |
|---|---|
| Operating system | The installer documents Windows, macOS and Linux support |
| Node.js | Version 20.0.0 or later, with npm/npx available in the terminal |
| Claude Code | Version 2.1.139 or later for the documented exec-form hook arguments |
| Bun | Version 1.0 or later; the installer can install it if missing |
| uv | Used for the Chroma embedding dependency; the installer can install it if missing |
| SQLite | Bundled through Bun; a separate database server is not required |
Check your existing runtime before installing:
node --version
npm --version
claude --version
The repository's latest release was v15.0.1 when checked. The linked installation documentation can evolve after a release, so compare its requirements with your installed version when troubleshooting. These commands and version requirements were reviewed in official sources, not run as an installation test for this article.
Install for Claude Code
Choose one installation route. In your terminal, the documented option using your Anthropic plan is:
npx claude-mem install --provider claude
Review the installer selections and choose the host you intend to configure. The installer sets up runtime dependencies, plugin registration and a hook launcher. Restart your terminal or IDE after a PATH change, then start a new Claude Code session so it inherits the updated environment.
The explicit provider matters. The current interactive installer also offers a Claude-Mem hosted observer, OpenRouter and Gemini choices. Those choices have their own authentication and usage arrangements. An open-source plugin does not make model inference unlimited or free. Read the selected provider's terms rather than assuming the installer always uses your existing Claude session.
Alternatively, the project documents these commands inside Claude Code, not in your system shell:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
Then restart Claude Code. The documentation notes that a marketplace-only installation may spend its first session preparing the launcher, so that session can lack injected memory. Missing dependencies can require the documented installer or repair path.
npm install -g claude-mem is not equivalent. The project's README says it installs the SDK/library without registering plugin hooks or setting up the worker. Do not use a successful global npm install as proof that memory capture is active.
Understand what is remembered
The usage guide describes a cycle of capturing tool activity, processing observations, saving summaries and injecting relevant project history at a later session start. Tool activity can include file reads, edits and shell commands. Filters and configuration affect what is retained.
The default local data directory is ~/.claude-mem/. The installation documentation identifies claude-mem.db for the database, settings.json for configuration and logs/worker-YYYY-MM-DD.log for worker logs. A custom data-directory setting changes those locations.
Search uses progressive retrieval: search returns a compact index, timeline provides surrounding context, and get_observations retrieves selected details. This is a retrieval workflow, not a promise that an entire prior conversation is automatically placed into every new prompt. When old context matters, check the underlying observation against the current project.
Configure context and data handling
The configuration reference places settings in ~/.claude-mem/settings.json, created with defaults on first run. Merge changes into that file; do not overwrite existing provider settings or credentials with a small example.
For example, the documented context limit can be changed with this entry:
{
"CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25"
}
That setting limits observations injected into context. It does not delete older database records or cap all provider usage. The configuration reference also provides exclusions, tool filters and optional redaction settings; review them before capturing sensitive work. Automatic secret redaction is documented as opt-in, so do not assume every credential will be removed by default.
A local SQLite database does not establish that all processing stays on the device. The chosen observer provider may process content externally. Separately, Claude-Mem cloud sync can replicate observations, summaries and user prompts under your cmem.ai account. Review provider selection and sync settings independently if the project must remain local.
Troubleshoot the failing stage
Start with the documented diagnostic command:
npx claude-mem doctor
Use the official troubleshooting guide to match the result to the symptom:
| Symptom | First useful check |
|---|---|
claude-mem executable not found in hooks |
Check the diagnostic's Hook launcher row, then restart the terminal or IDE after fixing PATH |
| Hooks print usage but capture nothing | Check the Claude Code version; the documented hook format requires 2.1.139 or later |
| Global package exists but no memory appears | Confirm plugin registration; a global SDK install alone is insufficient |
| Viewer does not open | Use the worker URL printed at startup or the configured port, rather than assuming a port copied from an older tutorial |
| Worker runs but observations are not processed | Inspect worker logs and the chosen provider's authentication or quota error |
| Recent work is absent from a new session | Check capture filters, project scope and whether observations were actually processed before investigating retrieval |
The current documented default port is per user, 37700 + (uid % 100), with CLAUDE_MEM_WORKER_PORT available as an override. Read your own configuration instead of treating 37777 as universal.
Worker health, an opening viewer and successful memory recall are different checks. A healthy service does not prove that provider processing succeeded. If diagnostics identify an authentication or quota failure, resolve that condition rather than repeatedly reinstalling. Preserve the data directory before destructive recovery; this guide does not recommend deleting the database as a first step.
Documentation reviewed: the repository at commit dcb28a7, its installation/configuration/usage/troubleshooting sources, and Anthropic's built-in memory documentation. No installation, paid account, model execution or end-to-end recall test was performed.