How to Use Claude-Mem with Claude Code: Persistent Memory Guide
By Braincuber Team
Published on April 20, 2026
Claude-Mem is a Claude Code plugin that captures what happens during each coding session, compresses the raw tool outputs into structured observations, and injects relevant context back when you start a new session. It solves the blank-slate problem where every Claude Code session starts with zero memory of previous work.
What You'll Learn:
- What claude-mem is and how it solves the memory problem
- Installation process and common pitfalls to avoid
- How the five lifecycle hooks capture and retrieve observations
- Configuration settings for cost and context optimization
- Security considerations and known limitations
What is Claude-Mem?
claude-mem is a Claude Code plugin that automatically captures session context and makes it available to future sessions. Unlike manual approaches like CLAUDE.md files, it works silently in the background without requiring you to write anything down.
Before claude-mem, every Claude Code session started from scratch. You would spend the first ten minutes re-explaining the project structure, and Claude would have no memory of authentication bugs fixed the day before or files that had already been analyzed.
Automatic Capture
Hooks into session lifecycle events and captures every tool call automatically without manual input.
Local Storage
All data stored locally in SQLite at ~/.claude-mem/claude-mem.db with no external cloud dependencies.
Smart Retrieval
Three-tier retrieval system loads only relevant context, keeping signal rate above 80%.
Structured Observations
Compresses tool outputs into typed schema with type, title, facts, narrative, and concepts.
How to Install Claude-Mem
Getting claude-mem running takes two commands inside a Claude Code session. However, there is a common pitfall that trips up many users.
Add the Plugin from Marketplace
Run this command inside a Claude Code session to add the plugin from the marketplace.
/plugin marketplace add thedotmack/claude-mem
Install the Plugin
Install claude-mem to register the lifecycle hooks and start the background worker.
/plugin install claude-mem
Restart Claude Code
Restart Claude Code to activate the plugin hooks and start the background worker.
Common Mistake to Avoid
Do NOT run npm install -g claude-mem - this only installs the SDK library without registering hooks or starting the worker. The marketplace path is the only method that gives you the full setup.
Verifying the Installation
To verify the installation actually worked, check three things:
| Check | Command/Action | Expected Result |
|---|---|---|
| Worker Health | curl http://localhost:37777/api/health | {"status":"ok"} |
| Hooks Registered | Check ~/.claude/hooks.json | claude-mem under PostToolUse and SessionStart |
| Web Viewer | Open http://localhost:37777 | Dashboard with observations streaming |
How Claude-Mem Works
Once installed, claude-mem runs silently in the background across five lifecycle hooks. Understanding what each one does explains why the tool behaves the way it does.
Capture and Compression
The five hooks map onto a session natural timeline:
| Hook | Purpose |
|---|---|
| SessionStart | Queries database and injects compressed index of recent work into context |
| UserPromptSubmit | Logs the session and stores your prompt |
| PostToolUse | Fires after every tool call, sends output to worker for compression |
| Stop | Generates session-level summary when you pause or idle |
| SessionEnd | Marks the session complete |
Observation Schema
PostToolUse compresses raw tool output into a structured observation with these fields:
| Field | Description |
|---|---|
| type | One of decision, bugfix, feature, refactor, discovery, change |
| title | A concise, searchable string |
| facts | Array of discrete facts (~50 tokens, cheap to load) |
| narrative | Prose explanation (~155-500 tokens, loaded on demand) |
| concepts | Semantic tags like how-it-works, problem-solution, gotcha |
Three-Tier Retrieval System
The naive approach sends 35,000 tokens to context with only 2,000 relevant - a 6% signal rate. Claude-mem pushes that above 80% with progressive disclosure:
| Layer | Function | Cost per Result |
|---|---|---|
| Layer 1 | search - returns compact index of observation IDs, titles, dates, types | 50-100 tokens |
| Layer 2 | timeline - chronological context around specific observation | 100-200 tokens |
| Layer 3 | get_observations - fetches full records by ID in batches | 500-1000 tokens |
Configuring Claude-Mem
All settings are accessible through the web UI at http://localhost:37777 under the Settings tab, or via environment variables and ~/.claude-mem/settings.json.
Compression Model Settings
| Setting | Default | Description |
|---|---|---|
| CLAUDE_MEM_MODEL | haiku | Model for compression (cheapest option) |
| CLAUDE_MEM_PROVIDER | claude | Provider: claude, gemini, or openrouter |
Cost Optimization Tip
Running compression on Gemini Flash Lite or a free OpenRouter model like xiaomi/mimo-v2-flash:free drops the cost to zero beyond your existing Claude Code subscription. Default haiku costs well under a dollar per month.
Context Injection Settings
| Setting | Default | Description |
|---|---|---|
| CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | Total observations injected at SessionStart (range 1-200) |
| CLAUDE_MEM_CONTEXT_FULL_COUNT | 5 | How many show expanded narrative detail (range 0-20) |
Privacy Settings
If you work with API keys or credentials, wrap them in <private> tags inside your prompts to exclude that content from storage. claude-mem strips anything inside those tags before creating an observation.
Wrap Sensitive Data
Use <private>API_KEY</private> tags in prompts to exclude from storage.
Claude-Mem vs Built-in Memory
Claude Code ships with memory features, but none capture context automatically. Here is how they compare:
| Feature | CLAUDE.md | Auto Memory | claude-mem |
|---|---|---|---|
| Capture Timing | Manual | Claude decides | Per tool call |
| Search | None | None | FTS5 keyword |
| Storage | Local markdown | Local markdown | Local SQLite |
| Pricing | Free | Free | Free |
Limitations and Known Issues
Security Warning - HIGH RISK
A community audit in February 2026 rated the risk as HIGH. The HTTP API on port 37777 has zero authentication - any local process can read observations and settings. Default host binding was 0.0.0.0 rather than 127.0.0.1. Run this only on a personal dev machine, not cloud VMs.
| Issue | Description | Solution |
|---|---|---|
| ChromaDB Subprocess Leak | Known to cause orphaned processes (184 in 19 hours, 16GB RAM) | Use FTS5 instead (default) |
| macOS Cold Start Timeout | Worker cold start exceeds 5-second timeout with ChromaDB | Use FTS5-only setup |
| MCP Tool Parameter Bug | search and timeline MCP tools have empty parameter schemas | Use get_observations instead |
Frequently Asked Questions
What is claude-mem and what problem does it solve?
claude-mem is a Claude Code plugin that captures what happens during each coding session, compresses the raw tool outputs into structured observations, and injects relevant context back when you start a new session. It solves the blank-slate problem where every Claude Code session starts with zero memory of previous work.
How do I install claude-mem?
Run two commands inside a Claude Code session: /plugin marketplace add thedotmack/claude-mem followed by /plugin install claude-mem, then restart Claude Code. The common mistake is running npm install -g claude-mem, which only installs the SDK library without registering hooks.
How is claude-mem different from CLAUDE.md and Auto Memory?
CLAUDE.md files are static with no search, capped at 200 lines. Auto Memory lets Claude decide what to save but its unstructured and not searchable. claude-mem captures automatically after every tool call with structured compression and three-tier retrieval.
Does claude-mem cost extra money to run?
claude-mem uses your existing Claude Code authentication for compression. The default haiku model costs well under a dollar per month. You can also switch to Gemini or OpenRouter free models for zero additional cost.
Is claude-mem safe to use?
A February 2026 security audit rated it HIGH risk due to unauthenticated HTTP API on port 37777. Run it only on a personal development machine, not cloud VMs. Use FTS5 instead of ChromaDB to avoid subprocess leaks.
Need Help with Claude Code?
Our experts can help you configure claude-mem and optimize your AI coding workflow.