ContextQMD
Back to Claude Mem

Installation

docs/public/installation.mdx

13.21.25.2 KB
Original Source

Installation Guide

Quick Start

Option 1: npx (Recommended)

Install and configure Claude-Mem with a single command:

bash
npx claude-mem install

The interactive installer runs in three stages — install first, sign in second, then pick your memory provider:

  1. Install everything. Runs a runtime check (auto-installs Bun and uv if missing), detects your installed IDEs (Claude Code, Cursor, Windsurf, OpenCode, Codex CLI, Antigravity CLI) and lets you multi-select which ones to wire up, offers to install Claude Code if it isn't found, then copies plugin files into the marketplace directory, registers the plugin, and installs dependencies.
  2. Sign in to claude-mem. The installer asks for your email and sends a sign-in link; your browser opens to complete it. Every sign-in provisions a memory key for your account — no card required.
  3. Choose your memory provider. After sign-in you pick where observation extraction runs (see below), then the worker service auto-starts with your choice.

Memory Provider Options

  • claude-mem observer (recommended) — memory runs off-plan: get up to 100% more usage from your plan. Free for 30 days; when the free trial ends, memory automatically falls back to your Anthropic plan unless you subscribe.
  • Your OpenRouter key — memory runs off-plan on your OpenRouter credit.
  • Gemini API key — memory runs off-plan on your Gemini key.
  • Anthropic plan — memory shares your Claude plan usage. Prompts for the Claude model used to compress observations (Haiku / Sonnet / Opus).

Skipping the Sign-In

The sign-in step is skipped automatically when any of these apply:

  • You pass an explicit --provider flag (e.g. npx claude-mem install --provider claude)
  • CLAUDE_MEM_ONLINE_OPTIN=false is set in your environment
  • The install runs in CI or a non-interactive (non-TTY) shell

You can finish signing in anytime by re-running npx claude-mem install.

Option 2: Plugin Marketplace

Install Claude-Mem directly from the plugin marketplace inside Claude Code:

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

Both methods will automatically configure hooks and start the worker service. Start a new Claude Code session and you'll see context from previous sessions automatically loaded.

Important: Claude-Mem is 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. Always install via npx claude-mem install or the /plugin commands above.

System Requirements

  • Node.js: 20.0.0 or higher
  • Bun ≥ 1.0 (auto-installed by npx claude-mem install if missing)
  • uv (auto-installed if missing — provides Python for Chroma's embedding service)
  • Claude Code or another supported IDE (Cursor, Windsurf, OpenCode, Codex CLI, Antigravity CLI, OpenClaw)
  • SQLite 3: bundled via bun:sqlite

Advanced Installation

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

Clone and Build

bash
# Clone the repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# Install dependencies
npm install

# Build hooks and worker service
npm run build

# Worker service will auto-start on first Claude Code session
# Or manually start with:
npm run worker:start

# Verify worker is running
npm run worker:status

Post-Installation Verification

1. Automatic Dependency Installation

Dependencies are installed automatically by npx claude-mem install and npx claude-mem repair. Heavy lifting (Bun + uv install, bun install inside the plugin cache) happens behind a visible installer spinner. The Setup hook only performs a sub-100ms version-check.js read of the .install-version marker — on mismatch it prints run: npx claude-mem repair to stderr and exits 0, so it never blocks a session. Works cross-platform on Windows, macOS, and Linux.

2. Verify Plugin Installation

Check that hooks are configured in Claude Code:

bash
cat plugin/hooks/hooks.json

3. Data Directory Location

Data is stored in ~/.claude-mem/:

  • Database: ~/.claude-mem/claude-mem.db
  • PID file: ~/.claude-mem/.worker.pid
  • Port file: ~/.claude-mem/.worker.port
  • Logs: ~/.claude-mem/logs/worker-YYYY-MM-DD.log
  • Settings: ~/.claude-mem/settings.json

Override with environment variable:

bash
export CLAUDE_MEM_DATA_DIR=/custom/path

4. Check Worker Logs

bash
npm run worker:logs

5. Test Context Retrieval

bash
npm run test:context

Upgrading

Upgrades are automatic when updating via the plugin marketplace. After an external upgrade (for example claude plugin update), the Setup hook detects a version-marker mismatch and asks you to run npx claude-mem repair, which installs any missing runtime dependencies and refreshes the marker.

See CHANGELOG for complete version history.

Next Steps