Skip to main content

​
Installation Guide

Grok mem — Grok Mem is how Grok Bots remember. Sits next to Grok’s own memory. Does not replace it. The package name is still claude-mem.

​
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:
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:
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 for --provider claude (memory runs on your own Anthropic plan). 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 the sign-in step; local installs contact cmem.ai once, at signup, to create the sign-in link, with a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names), and nothing else is sent to cmem.ai. 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

Interactive --provider claude skips the sign-in step. Non-interactive runs (no TTY, as when an AI agent runs the installer) without --provider default to the Anthropic plan on a fresh install and reuse the configured provider otherwise. Every non-interactive install that skipped sign-in prints an optional sign-in link at the very end; it is best-effort, never blocks or changes the exit status, and is skipped when CI is set. Local installs contact cmem.ai once, at signup, to create the sign-in link, with a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names); nothing else is sent to cmem.ai. 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:
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

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

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

​
4. Check Worker Logs

​
5. Test Context Retrieval

​
6. CMEM Pro / sync

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