Installation

Install the Claude-Mem plugin in two commands and get persistent memory across all sessions

Installation

Quick Install

Claude-Mem installs directly from the Claude Code plugin marketplace. Start a new Claude Code session and run:

1. Add the marketplace source

   /plugin marketplace add thedotmack/claude-mem
   
2. Install the plugin

   /plugin install claude-mem
   
3. Restart Claude Code

   Restart Claude Code. Context from previous sessions will automatically appear when you start your next session.

The plugin installer automatically handles everything:

• Downloads prebuilt binaries (no compilation needed)
• Installs all dependencies including SQLite binaries
• Configures hooks for session lifecycle management
• Auto-starts the worker service on your first session

Claude-Mem is also published on npm, but running npm install -g claude-mem installs the SDK/library only. It does not register plugin hooks or start the worker service. To use Claude-Mem as a persistent memory plugin, always install via the /plugin commands above.

System Requirements

Requirement	Details
Node.js	18.0.0 or higher
Claude Code	Latest version with plugin support
Bun	JavaScript runtime and process manager — auto-installed if missing
uv	Python package manager for Chroma vector search — auto-installed if missing
SQLite 3	For persistent storage — bundled

On Windows, if you see npm : The term 'npm' is not recognized, ensure Node.js is installed and added to your PATH. Download the latest installer from nodejs.org and restart your terminal after installation.

Advanced Installation (From Source)

For development or testing, you can clone the repository and build from source:

1. Clone the repository

   git clone https://github.com/thedotmack/claude-mem.git
   cd claude-mem
   
2. Install dependencies

   npm install
   
3. Build hooks and worker service

   npm run build
   
4. Start the worker service

   The worker auto-starts on your first Claude Code session. To start it manually:

   npm run worker:start
   
5. Verify the worker is running

   npm run worker:status
   

Post-Installation Verification

After installing, run through these checks to confirm everything is working:

1. Automatic Dependency Installation

Dependencies are installed automatically during plugin installation. The SessionStart hook also verifies dependencies are up-to-date on each session start — this check is fast and idempotent. It works cross-platform on Windows, macOS, and Linux.

2. Verify Plugin Hook Registration

Check that hooks are configured in Claude Code:

cat plugin/hooks/hooks.json

You should see entries for SessionStart, UserPromptSubmit, PostToolUse, and Stop.

3. Confirm Data Directory Location

All Claude-Mem data is stored in ~/.claude-mem/:

File	Purpose
~/.claude-mem/claude-mem.db	SQLite database with all sessions and observations
~/.claude-mem/.worker.pid	Worker process ID
~/.claude-mem/.worker.port	Worker port (default: 37777)
~/.claude-mem/logs/worker-YYYY-MM-DD.log	Daily worker logs
~/.claude-mem/settings.json	Plugin configuration (auto-created on first run)

To use a custom data directory:

export CLAUDE_MEM_DATA_DIR=/custom/path

4. Check Worker Logs

npm run worker:logs

The logs show worker startup, observation processing, and any errors.

5. Test Context Retrieval

npm run test:context

This verifies that the worker is running and context can be retrieved from the database.

Upgrading

Upgrades are automatic when you update through the plugin marketplace. The worker service restarts automatically after an upgrade.

Marketplace Update

Use the Claude Code plugin update command to upgrade to the latest stable release. The marketplace handles dependency reinstallation and worker restart automatically.

Version Notes

v7.1.0: PM2 replaced with native Bun process management. Migration is automatic on first hook trigger after upgrade.

v7.0.0+: 11 configuration settings and dual-tag privacy system introduced.

v5.4.0+: MCP tools-based search replaces the previous approach, saving ~2,250 tokens per session.

See the CHANGELOG for the complete version history.

Next Steps

Getting Started

Learn how Claude-Mem works automatically — what gets captured, how context injection works, and how to search your history.

Configuration

Customize observation limits, context injection behavior, AI model selection, worker port, and privacy settings.

MCP Search Tools

Query your project history with natural language using the 3-layer MCP search workflow.

Troubleshooting

Solutions for common issues including worker startup failures, missing context, and Windows-specific problems.