ContextQMD
Back to Claude Mem

Installation

docs/public/installation.mdx

13.24.06.8 KB
Original Source

Installation Guide

Grok mem — Grok Mem is how Grok Bots remember. Sits next to Grok's own memory. Does not replace it.

Quick Start

Option 1: Grok Bot

Grok Bot has no host hooks. Install it independently of Cursor or Claude Code. Default is CMEM Pro, the hosted memory:

bash
npx claude-mem install --ide grok-bot

Local host-login observer is opt-in: --provider host. --ide is a single string — a second host is a second install command. Installing this plugin does not install Cursor. See Grok Bot Integration.

Option 2: npx

Install and configure Claude-Mem with a single command:

bash
npx claude-mem install

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

  1. Install runtime. Runs a runtime check (auto-installs Bun and uv if missing), detects your installed IDEs (Claude Code, Cursor, Windsurf, OpenCode, Codex CLI, Antigravity CLI, Grok Bot) 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. Skipped only for --provider claude (that path never talks to cmem.ai). The CLI does not ask for an email. It starts an OAuth pairing (POST https://cmem.ai/api/installer/oauth/start), prints a device code XXXX-XXXX, opens authorization_url in your browser, and polls until you are authenticated. No card required.
  3. Choose your memory provider. CMEM Pro is pre-selected. Picking it opens a checkout/trial URL, polls until the account is ready, writes ~/.claude-mem/settings.json, and restarts the worker. Other choices: personal OpenRouter, Gemini, Anthropic plan, or --provider host (local loopback observer).

Headless or already signed in? See CMEM Pro (manual / headless) for the exact settings the installer writes.

Memory Provider Options

  • CMEM Pro / claude-mem observer (pre-selected) — memory runs off-plan through https://cmem.ai/api/inference/v1 with model cmem-observer. Free trial, then subscribe or fall back. Fallback is event-driven (CLAUDE_MEM_PRO_FALLBACK_AT after a terminal gateway quota/key error), not the trial end date. See CMEM Pro (manual / headless).
  • Your OpenRouter key — memory runs off-plan on your OpenRouter credit. Empty base URL (or https://openrouter.ai/api/v1). Never send a personal sk-or- key to the cmem.ai inference gateway.
  • Gemini API key — memory runs off-plan on your Gemini key.
  • Anthropic plan (--provider claude) — memory shares your Claude plan usage. Skips cmem.ai entirely. Prompts for the Claude model used to compress observations (Haiku / Sonnet / Opus).
  • Host observer (opt-in) — --provider host uses the already-logged-in agent over a local loopback. No API key. See Grok Bot Integration.

Skipping the Sign-In

--provider claude never touches cmem.ai and skips OAuth. You can finish a CMEM Pro pairing anytime by re-running npx claude-mem install, or by writing settings by hand (manual / headless).

Option 3: 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 host (Cursor, Grok Bot, 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

6. CMEM Pro / sync

bash
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/health"
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/sync/status"

See CMEM Pro (manual / headless).

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