claude-mem — persistent memory system for Claude Code and other coding agents

What it claims

The repository ships an install-time memory provider choice that the summary does not describe. By default the installer opens a browser sign-in (email magic link, no card) and provisions the hosted "claude-mem observer". The observer runs memory compression off your Anthropic plan and is free for up to 14 days. When the trial ends, memory automatically falls back to your Anthropic plan unless you subscribe. The page also puts numbers on the retrieval layers: a search index result costs about 50–100 tokens, and a full get_observations result costs about 500–1,000 tokens. The headline "~10x token savings" comes from filtering on the cheap layer before fetching the expensive one.

flowchart TD
  I[npx claude-mem install] --> Q{--provider flag, ONLINE_OPTIN=false, or CI?}
  Q -- yes --> L[No account interaction]
  Q -- no --> S[Browser sign-in]
  S --> P{Pick provider}
  P --> O[Hosted observer, 14-day trial]
  P --> K[Own OpenRouter / Gemini key]
  P --> A[Anthropic plan]
  O -- trial ends, no subscription --> A

How to use it

Install with one of the following commands. Do not use npm install -g claude-mem. That command installs only the SDK/library. It does not register the hooks or start the worker.

npx claude-mem install
npx claude-mem install --ide opencode
npx claude-mem install --ide t3code
npx claude-mem install --ide antigravity
npx claude-mem install --ide omp
npx claude-mem install --ide grok-bot

Inside Claude Code you can install from the plugin marketplace instead, then restart Claude Code:

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

For OpenClaw gateways the page gives a piped installer. It can optionally set up observation feeds to Telegram, Discord or Slack:

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

Requirements. Node.js 20.0.0 or later. Bun and uv are auto-installed if missing (uv is used for vector search). SQLite is bundled.

Configuration. Settings live in ~/.claude-mem/settings.json. Useful keys:

• CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES: "true" pulls observations from every harness (Claude Code and Codex) into SessionStart context. The default is "false", which limits it to the current harness.
• CLAUDE_MEM_MODE sets both the workflow behaviour and the language of generated observations. Examples are code, chill, investigation, and code--<ISO 639-1> such as code--zh.
• Wrapping content in <private> tags excludes it from storage.

Usage notes.

• Batch IDs in get_observations(ids=[...]).
• A web viewer runs at the worker URL printed on startup.
• To file issues, generate a bug report with cd ~/.claude/plugins/marketplaces/thedotmack && npm run bug-report.

Release branches. Only main is published to npm. core-dev and community-edge are run from source.

Limits

• Data leaves your machine by default on the interactive path (hosted observer) and on Grok Bot. Grok Bot has no host hooks, so claude-mem watches its chat log files and defaults to the hosted CMEM Pro. Local processing there is opt-in with --provider host. A separate Cloud Sync to cmem.ai is also documented.
• Grok Bot "awareness push" writes into the bot's own files. It appends decision, bugfix, security_alert and sensitive observations as dated lines to memory/log/YYYY-MM.md. Disable it with CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false.
• Watch for silent cost changes. When the trial lapses, compression starts consuming your Anthropic plan without any further prompt.
• The README is internally inconsistent. It says "4 MCP tools" but lists three. It cites "6 hook scripts" in one place and "7 hook scripts" in the docs index. The ~10x saving is asserted with no benchmark or baseline.
• Licensing has a boundary. The project is Apache-2.0, but the README points to docs/ip-boundary.md for an "open/commercial boundary". Read that before embedding the project.
• There is a crypto token. The README promotes a third-party crypto token (CMEM, BASE contract 0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3) that the author "officially embraced". Factor that into your assessment of the project's governance and incentives.