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

​
When an AI agent installs for a user

  1. On the user’s computer, run npx claude-mem install --runtime worker in an interactive terminal. Enable PTY if your shell tool offers it. Leave --provider and --no-auto-start unset so first-time setup can open in the browser.
  2. Before the browser opens, the installer asks in the terminal:
    • Overwrite existing installation?, only when claude-mem is already installed.
    • Which agents to set up. Pass --ide <id> (for example --ide claude-code) to skip this question.
    • Disable Claude Code auto-memory?, only when Claude Code is one of the agents. Passing --disable-auto-memory answers “disable” and skips it; there is no flag for “leave enabled”, so ask the user.
    Relay each question to the user and type the answer they give.
  3. Keep that terminal running. When it prints Continue setup in your browser, open the printed URL in the user’s browser if the page hasn’t opened automatically. If you can’t open their browser, give them that exact URL to open on the same computer.
  4. At the end, the installer may ask in the terminal whether to share anonymized usage data. Relay that question too. It is skipped when CI or DO_NOT_TRACK is set, or when the user already answered it.
  5. Hand control to the user. They choose how to use memory and complete any sign-in themselves. Wait for the installer to report the outcome before confirming setup.
If you only have a remote sandbox or can’t allocate a local PTY, give the user the same command to run in their own terminal.

​
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. Before the first stage, an interactive terminal install asks once, optionally, for your email and a note on how we can help; press Enter to skip it. If you answer, the email and note (with the claude-mem version and OS) are sent to https://cmem.ai/api/waitlist and saved in ~/.claude-mem/settings.json so you aren’t asked again. Non-TTY (agent-run) installs, installs with CI set, and CLAUDE_MEM_ONLINE_OPTIN=false never ask.
  1. Choose agents and install runtime. Pre-selects detected agents, including OpenCode, OMP, Cursor, and Codex CLI. Offers to install Claude Code only when you select it and it isn’t found. If the host download or installation fails, returns to agent selection so you can retry or choose another agent. Then checks Bun and uv, copies plugin files into the marketplace directory, registers the plugin, installs dependencies, and puts the claude-mem hook launcher on your PATH (see How hooks reach claude-mem).
  2. Sign in. Skipped for --provider claude (memory runs on your own Anthropic plan). An interactive terminal install with no --provider signs in only if you pick CMEM Pro in stage 3; --provider codex, gemini or openrouter still signs in first. Sign-in never asks 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. 30 Day Free Trial, then subscribe or fall back. Fallback is event-driven: CLAUDE_MEM_PRO_FALLBACK_AT is set when the gateway stops serving the account (a spent allowance, an inactive subscription, or a refused key), not on the trial end date, and memory then uses your Anthropic plan. 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 send cmem.ai only your email and optional note (with the claude-mem version and OS) if you share them when an interactive terminal install asks, and a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names) when setup creates a sign-in link; nothing else is sent to cmem.ai unless you choose to upload your prompts during browser setup. 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. Unattended runs (no TTY) without --provider default to the Anthropic plan on a fresh install and reuse the configured provider otherwise. After an unattended install that skipped sign-in, the CLI offers an optional sign-in link; it is best-effort, never blocks or changes the exit status, and is skipped when CI is set. Local installs send cmem.ai only your email and optional note (with the claude-mem version and OS) if you share them when an interactive terminal install asks, and a numbers-only usage summary (observation counts and token totals, no prompts, paths, or project names) when setup creates a sign-in link; nothing else is sent to cmem.ai unless you choose to upload your prompts during browser setup. 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. A marketplace-only install has no installer step, so the plugin places the claude-mem launcher itself on the first session start (see below). That first session can run without memory context while the launcher compiles; the next one has it. Running npx claude-mem install once avoids the gap.
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. A global npm claude-mem that sits earlier on PATH than the hook launcher shadows it; see Troubleshooting.

​
How hooks reach claude-mem

Every Claude Code hook is one short command with no shell: claude-mem hook claude-code <event> (the worker-start entry is claude-mem start). Claude Code looks claude-mem up on PATH and runs it directly, so runtime hooks need no bash on any platform, and Windows needs no Git Bash for them. The one exception is the Setup hook, which still runs through bash but only fires for claude --init / --maintenance. This exec form ("command": "claude-mem", "args": [...]) needs Claude Code 2.1.139 or later. An older Claude Code ignores args and runs bare claude-mem, which only prints usage, so no memory is captured. npx claude-mem install and npx claude-mem doctor warn when the detected Claude Code is older; update it with claude update. claude-mem here is a small compiled launcher, not the npm CLI. It finds the installed plugin, runs the hook under Bun, and exits 0 on any failure so it never blocks a session.
  • npx claude-mem install and npx claude-mem update compile and place it. They skip the compile when the placed launcher is already current.
  • Marketplace-only installs are covered by an extra SessionStart entry, node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs, which runs at startup and places or refreshes the launcher when it is missing or out of date.
  • If the launcher cannot be made active, session start shows:
  • After a PATH change, restart your terminal or IDE so Claude Code inherits the new PATH.
  • npx claude-mem doctor shows a Hook launcher row with where claude-mem resolves on PATH and whether it is the launcher. See claude-mem: command not found in hooks.
  • npx claude-mem uninstall removes the launcher binary. It leaves your shell rc file and user Path alone and prints the line to remove.

​
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 2.1.139 or later (the first release with exec-form hook args), 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, compiling the hook launcher) happens behind a visible installer spinner. Works cross-platform on Windows, macOS, and Linux. The plugin also ships a Setup hook (version-check.js) that runs bun install in the plugin root when its declared dependencies are missing and records the .install-version marker once they are complete. Claude Code fires Setup only for claude --init, claude --init-only and claude -p --maintenance, never on plugin install, update or a normal session start, so for a marketplace install whose dependencies are missing, run npx claude-mem install (or claude --init-only). The Setup hook always exits 0.

​
2. Verify Plugin Installation

Check that hooks are configured in Claude Code and that the launcher is on PATH:

​
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

claude-mem updates itself: once a day it checks the release its owner promotes and installs it while you are away (see Auto-update). To update by hand, run npx claude-mem update. The on-PATH launcher is version-stable: it carries no claude-mem logic, so an update does not need a new one. When an update does need a newer launcher, the startup SessionStart self-heal compiles it, and that first session may miss memory context while it does. npx claude-mem update refreshes the plugin, its dependencies and the launcher in one step. If an update leaves dependencies missing, run npx claude-mem@latest install. See CHANGELOG for complete version history.

​
Next Steps