Skip to main content

​
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

RequirementDetails
Node.js18.0.0 or higher
Claude CodeLatest version with plugin support
BunJavaScript runtime and process manager — auto-installed if missing
uvPython package manager for Chroma vector search — auto-installed if missing
SQLite 3For 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:
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.
Check that hooks are configured in Claude Code:
cat plugin/hooks/hooks.json
You should see entries for SessionStart, UserPromptSubmit, PostToolUse, and Stop.
All Claude-Mem data is stored in ~/.claude-mem/:
FilePurpose
~/.claude-mem/claude-mem.dbSQLite database with all sessions and observations
~/.claude-mem/.worker.pidWorker process ID
~/.claude-mem/.worker.portWorker port (default: 37777)
~/.claude-mem/logs/worker-YYYY-MM-DD.logDaily worker logs
~/.claude-mem/settings.jsonPlugin configuration (auto-created on first run)
To use a custom data directory:
export CLAUDE_MEM_DATA_DIR=/custom/path

npm run worker:logs
The logs show worker startup, observation processing, and any errors.
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.
Use the Claude Code plugin update command to upgrade to the latest stable release. The marketplace handles dependency reinstallation and worker restart automatically.

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us