Extending Claude Code's Memory: Installing and Using claude-mem

Jason Yang
26 Dec, 2025
Updated 04 Jan, 2026
Views —

When using Claude Code, it’s frustrating that all previous work context disappears when a session ends or after running /clear. Claude can’t answer questions like “How did I fix that bug last time?” or “What did I work on in this project?”

claude-mem is a plugin that solves this problem.

What is claude-mem?

claude-mem is a plugin that automatically saves and restores context across Claude Code sessions. Its core features include:

Automatic Capture: Records all tool usage performed by Claude
AI Compression: Compresses records into meaningful observations using Claude Agent SDK
Context Injection: Automatically injects relevant context when starting a new session
Search Functionality: Search past work history using natural language

Installation

1. Install the Plugin in Claude Code

Enter the following commands in Claude Code:

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

When the scope selection screen appears, choose “Install for you (user scope)”. This allows you to use claude-mem across all projects.

2. Restart Claude Code

After installation, completely exit and restart Claude Code.

3. Resolving First-Run Errors

On first launch, you may encounter this error:

Plugin hook error: /bin/sh: 1: bun: not found
Error: Worker did not become ready within 5 seconds. (port 37777)

This occurs because the Bun runtime isn’t installed or the worker hasn’t started. Fortunately, claude-mem automatically installs Bun:

🔧 Bun not found. Installing Bun runtime...
✅ Bun 1.3.5 installed successfully
✅ Dependencies installed
✅ CLI installed: /home/jason/.local/bin/claude-mem

4. Starting the Worker

If you still get a “worker not ready” error after Bun installation, exit Claude Code and manually start the worker from the terminal:

claude-mem restart

Then restart Claude Code, and it should work properly:

📝 Claude-Mem Context Loaded
[careerscore-user-service] recent context
────────────────────────────────────────────────────────────────
No previous sessions found for this project yet.
💡 New! Wrap all or part of any message with <private> ... </private> 
   to prevent storing sensitive information in your observation history.
📺 Watch live in browser http://localhost:37777/

Fixing “bun: not found” Error (Optional)

After installation, you may see this error message when starting Claude Code:

Plugin hook error: /bin/sh: 1: bun: not found

This occurs because Bun is installed in your home directory (~/.bun/bin/bun), but /bin/sh doesn’t read .bashrc, so it can’t find Bun in the PATH.

The Fix: Create a symbolic link to make Bun globally accessible:

sudo ln -s ~/.bun/bin/bun /usr/local/bin/bun

This creates a shortcut from your user installation to the system-wide bin directory, allowing all shells and scripts to find Bun.

Note: This step is optional. Even with the error message, claude-mem works correctly. Only do this if the error message bothers you.

Auto-Start Configuration

The worker stops when you reboot your computer, requiring manual restart each time. To automate this, add the following line to your .bashrc:

# Add to the end of ~/.bashrc
(claude-mem status > /dev/null 2>&1 || claude-mem start > /dev/null 2>&1 &)

This automatically starts the worker when you open a terminal if it’s not already running.

Apply the changes:

source ~/.bashrc

Data Storage Location

claude-mem data is stored in the ~/.claude-mem/ directory:

~/.claude-mem/
├── claude-mem.db          # SQLite database (sessions, observations)
├── claude-mem.db-shm      # SQLite WAL temp file
├── claude-mem.db-wal      # SQLite WAL temp file
├── logs/                  # Worker logs
├── vector-db/             # ChromaDB for vector search
└── worker.pid             # Running worker PID

Checking Configuration

You can check current settings via the API:

curl http://localhost:37777/api/settings

Key settings:

Setting	Default	Description
`CLAUDE_MEM_MODEL`	`claude-sonnet-4-5`	Model used for observation compression
`CLAUDE_MEM_CONTEXT_OBSERVATIONS`	`50`	Number of observations to inject at session start
`CLAUDE_MEM_WORKER_PORT`	`37777`	Worker service port
`CLAUDE_MEM_LOG_LEVEL`	`INFO`	Log level

For custom settings, create the ~/.claude-mem/settings.json file:

{
  "CLAUDE_MEM_MODEL": "claude-sonnet-4-5",
  "CLAUDE_MEM_WORKER_PORT": "37777",
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "50",
  "CLAUDE_MEM_LOG_LEVEL": "INFO"
}

Usage

After installation, there’s nothing special to do. It works automatically:

Session Start: Previous session context is automatically injected
During Work: Tool usage is automatically captured and compressed
Session End: Summary is automatically generated and saved

Searching Past Work

Ask questions in natural language, and the mem-search skill automatically searches past records:

“What did we do last session?”
“Did we fix this bug before?”
“How did we implement authentication?”
“What changes were made to worker-service.ts?”

Web Viewer

Access http://localhost:37777 in your browser to see memory being accumulated in real-time through the UI.

Protecting Sensitive Information

By default, claude-mem stores conversation context for future sessions.
To prevent sensitive data from being saved, wrap it with <private>...</private> tags.

Content inside these tags is excluded from memory storage and search, but remains usable by Claude during the current session.

⚠️ <private> tags are used directly in the chat input, not in configuration files.

<private>
API_KEY=sk-xxx-secret-key
DB_PASSWORD=mysecretpassword
</private>

Use this when sharing API keys, secrets, or .env contents.

Useful Commands

# Check worker status
claude-mem status

# Restart worker
claude-mem restart

# Stop worker
claude-mem stop

# Start worker
claude-mem start

# View logs
tail -f ~/.claude-mem/logs/worker-*.log

Conclusion

With claude-mem, Claude Code behaves as if it has long-term memory. It’s especially useful when working on projects over extended periods or across multiple sessions.

Installation is simple, and once configured, it operates automatically. If you use Claude Code frequently, I highly recommend installing it.