claude-mem Deep Dive: The Best Claude Code Memory Plugin — Install and Forget

Introduction

“Yesterday I asked Claude to fix a bug. Today I start a new session, and it remembers nothing.”

This is one of the deepest pain points for Claude Code users. Every new session, Claude acts like it has amnesia — no memory of what was done yesterday, which files were changed, or why a certain decision was made. You have to explain everything from scratch, wasting time and effort.

Recently, an open-source project called claude-mem has gone viral, racking up 60K+ Stars on GitHub and solving this exact problem.

In this article, I’ll walk you through what claude-mem is, how to install it, how to use it, and why it’s so popular.

1. What is claude-mem?

In one sentence: claude-mem is a persistent memory plugin for Claude Code that automatically records every session’s operations, compresses them into searchable semantic memories, and injects context into new sessions.

It solves the core weakness of Claude Code:

Without claude-mem	With claude-mem
Every new session starts from zero	Auto-loads context from last 10 sessions
No memory of yesterday’s changes	Complete record of all tool calls and operations
Need to re-explain project background	AI automatically understands project history
Everything forgotten when terminal closes	Memories permanently saved, searchable anytime

Project: github.com/thedotmack/claude-mem

claude-mem is built on Claude Code’s Hook lifecycle mechanism. For a deep dive into Hooks, check out this article on adding “brakes” and “seatbelts” to Claude Code with Hooks.

Here’s the full architecture diagram for the technically inclined:

2. Core Features

claude-mem does much more than “remember what happened last time.” It includes six core features:

1. Auto-Capture

Every time Claude calls a tool, claude-mem automatically captures:

Read — file reading and content access
Write — new file creation
Edit — file modifications
Bash — command execution
Glob / Grep — file and content search
And all other Claude Code tools

Fully automatic, zero manual intervention.

2. Smart Compression

Instead of simply storing raw logs, it uses AI to compress operations into structured memories:

Title — brief description of what happened
Narrative — detailed explanation
Facts — key findings (bullet points)
Type — classification (decision, bugfix, feature, etc.)
Files — which files were involved

This way, when context is injected next time, it won’t dump massive raw logs — it precisely injects “meaningful memories.”

3. Session Summaries

Each time Claude completes a response, it auto-generates a session summary:

Request — what you asked for
Investigated — what Claude explored
Learned — key findings and insights
Completed — what was accomplished
Next Steps — what to do next

4. Progressive Context Injection

This is claude-mem’s most elegant design, with three layers controlling token consumption:

Layer 1 (automatic): Shows a title index of recent operations at startup, ~50-200 tokens
Layer 2 (on-demand): You ask “How did we fix that bug last time?” and Claude calls the MCP search tool for details
Layer 3 (full recall): Directly reads source files for complete context

Core idea: Give Claude the table of contents first, then flip to detailed content when needed.

5. Semantic Search

Under the hood, it uses a hybrid architecture of ChromaDB vector database + SQLite FTS5 full-text search, supporting:

Natural language queries: “How did we fix that auth bug last time?”
File-based search: “What changed recently in worker-service.ts?”
Type filtering: bugfix, feature, decision, etc.
Timeline traversal: see what happened before and after an operation

6. Web Viewer

Built-in Web UI — visit http://localhost:37777 to see in real time:

Memory stream (all captured operations)
Session history
Search functionality
Settings and configuration

3. Installation — One Command

claude-mem installation is incredibly simple. Choose one of two methods:

Method 1: npx Install (Recommended)

npx claude-mem install

That’s it. Restart Claude Code after installation.

Method 2: Plugin Marketplace

Run in Claude Code:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Then restart Claude Code.

System Requirements

Node.js 18.0.0 or higher
Latest Claude Code (with Plugin support)
Bun runtime (auto-installed)
SQLite 3 (built-in)

Configuring Chinese Mode

After installation, the default language is English. To switch to Chinese, edit the config file:

# Edit configuration
vim ~/.claude-mem/settings.json

Change to:

{
  "CLAUDE_MEM_MODE": "code--zh"
}

Restart Claude Code for changes to take effect. All memory summaries will be generated in Chinese.

Mac Users: MCP Connection Failure Troubleshooting

This is the biggest pitfall for Mac users. After installation, you might find that claude-mem’s MCP server shows a connection failure (red status), and the plugin has no memory functionality at all.

Root cause: claude-mem’s MCP service depends on the Bun runtime, but the PATH environment variable Claude Code uses when starting MCP servers is different from your terminal’s. Even if bun --version works fine in your terminal, Claude Code might not be able to find the bun command.

Troubleshooting steps:

1. Confirm bun is installed and in system PATH

# Check if bun exists
which bun

# If not found, add it to .zshrc
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. Create a symlink for bun in a system directory

This is the most critical step. Even if bun is in your PATH, Claude Code’s MCP process might not find it:

# Link bun to Homebrew's bin directory (common Mac path)
ln -sf $(which bun) /opt/homebrew/bin/bun

# For Intel Macs, the path is different
# ln -sf $(which bun) /usr/local/bin/bun

3. Modify MCP config to use absolute path

Edit Claude Code’s MCP configuration file:

# View current MCP config
cat ~/.claude/settings.json | grep -A 10 "claude-mem"

Find claude-mem’s command field and change bun to an absolute path:

{
  "mcpServers": {
    "claude-mem-mcp": {
      "command": "/opt/homebrew/bin/bun",
      "args": ["run", "/your/path/.claude-mem/mcp-server.js"]
    }
  }
}

4. Verify MCP connection is working

Restart Claude Code, then type /mcp to check MCP server status. If claude-mem-mcp shows a green connected status, the fix was successful.

Quick diagnosis checklist:

Symptom	Cause	Solution
MCP shows red	bun not in PATH	Symlink to `/opt/homebrew/bin/`
Worker port 37777 unreachable	Service not started	Check with `curl http://localhost:37777/health`
No memory records after install	MCP disconnected, Hooks can’t communicate	Fix MCP connection using steps above
`bun: command not found`	bun not installed	`curl -fsSL https://bun.sh/install \| bash`

4. Usage — Install and Forget

claude-mem’s biggest feature is fully automatic operation, zero manual intervention.

Complete workflow:

Start Claude Code → automatically loads context from last 10 sessions
Work normally → every tool call is automatically captured
Claude finishes responding → Stop Hook auto-generates session summary and saves it
Next new session → previous work context appears automatically

The only thing you need to do: search history. Ask Claude directly in natural language:

“What bugs did we fix last time?”
“How was the auth feature implemented?”
“What changed recently in worker-service.ts?”
“Show me the recent work log for this project”

Claude will automatically call claude-mem’s MCP search tool to retrieve relevant information from the memory store.

Privacy? No Worries

All claude-mem data is stored locally (~/.claude-mem/). SQLite database and ChromaDB vector store run entirely on your machine — nothing is sent to any cloud. Zero data leakage risk.

If you don’t want certain content (like API keys, passwords) to appear in the memory store and pollute search results, you can exclude it with the private tag:

<private>
API Key: sk-xxx
Database password: xxxxxx
</private>

Content wrapped in the private tag won’t be recorded. Honestly, most people never need this feature — the data is all on your own machine anyway.

5. How Does It Compare to CLAUDE.md Memory?

You might already be using CLAUDE.md for persistent memory. So what additional value does claude-mem provide?

Dimension	CLAUDE.md	claude-mem
Memory type	Static rules and preferences	Dynamic operation records
Content source	Manually written	Auto-captured
Search capability	None (full-text read only)	Semantic + full-text search
Token consumption	Loads full text every conversation	Progressive loading, on-demand retrieval
Use case	”Tell AI my rules"	"Let AI remember what it did”

They complement each other, not replace. CLAUDE.md manages “rules,” claude-mem manages “experiences.”

Follow FishTech Notes on WeChat to share your experience!