claude-mem

What It Does

claude-mem is a persistent memory system for AI coding assistants, primarily Claude Code. Six lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, PreToolUse on Read, Stop, plus a Setup check) stream what the agent does into a local SQLite database, a Bun-managed worker service compresses sessions into observations, and context from past work is injected into new sessions. A 15-tool MCP server (21 tools registered in source, 15 live in worker mode) exposes layered search over the archive, and 19 bundled skills (mem-search, learn-codebase, pathfinder, standup, and others) sit on top. It ships install surfaces for Claude Code, Codex, Cursor, Grok, Windsurf, OpenCode, Antigravity, an OpenClaw gateway package with its own SKILL.md, and Claude Cowork. The audience is developers who want their coding agent to remember decisions and past work across sessions without manual notes.

The Good

The installer is the most disciplined npx installer GearScope has run in this tier. In a clean isolated HOME with CI=true, CLAUDE_MEM_ONLINE_OPTIN=false and DO_NOT_TRACK=1, the install completed with no account interaction, printed an exact summary (plugin dir, IDE list, "Cloud sync: OFF (local)", "Account: Not required (local provider)"), and registered the plugin under ~/.claude with a versioned cache directory. Uninstall ran clean and left no claude-mem references in settings.json. The CLI also honors reality: npm install -g is explicitly documented as SDK-only, with npx or /plugin as the real paths.

The engineering under the hood is real, and its own tests pass. We ran three suites from a fresh clone: tests/sqlite (122 pass, 0 fail), tests/context (75 pass), and tests/worker/search (42 pass), 239 tests total in about two seconds. The code shows the same care: atomic JSON writes with fsync and rename, PID-file supervision with start-token checks that detect PID reuse, Windows-specific multipliers on timeouts, and a 206-line SECURITY.md that documents command-injection defenses (array-based spawn args, shell:false, branch-name whitelists). The changelog is 7,680 lines of Keep-a-Changelog entries with issue attributions, and the README ships in 30 languages.

The MCP surface works as a protocol citizen. The stdio server handshakes cleanly (serverInfo claude-mem 13.24.1, capabilities: tools), enumerates 15 tools in worker mode, and fails correctly in both directions: with the worker down, search returns a structured isError payload ("Error calling Worker API: fetch failed"), and an unknown tool name is rejected with an error rather than silence. The layered search design (search returns a token-cheap index, timeline adds chronology, get_observations fetches full rows only for chosen IDs) is a sensible token-budget contract, and there is even a workflow-instruction tool (important_workflow) that teaches the model the three-step pattern.

The worker lifecycle and hook contract check out. Start, health, and stop all behaved: /api/health returns rich status JSON (version, pid, uptime, provider, dependency states, mcpReady), stop closes the port, and a clean-shutdown marker is written. The SessionStart context hook emitted a correct hookSpecificOutput JSON envelope with a 1,694-byte "no memory yet" starter on an empty database. Everything stays under ~/.claude-mem by default, and telemetry consent follows a documented precedence chain (DO_NOT_TRACK beats CLAUDE_MEM_TELEMETRY beats telemetry.json), which we verified is honored by the run.

The Bad

It injects an advertisement into your agent's context. Until the first observation lands, the SessionStart context injected into every session includes a CMEM Pro promotion: "Get up to 100% more usage from your plan, memory runs off-plan, free for 30 days" pointing at cmem.ai/pro?from=welcome-hint&trial=30. The same upsell appears in the installer output. A URL with a trial parameter inside the context window your agent reads on every session start is ad delivery into the reasoning path, and nothing in the README discloses it.

The README has drifted from the product it documents. The project is mid-rebrand to "Grok Mem": the logo links to grok-mem.ai, the tagline is "how Grok Bots remember", and the first quick-start command installs for a Grok bot IDE, while the package, plugin manifest, CLI banner, and MCP serverInfo all still say claude-mem targeting Claude Code. The counts disagree with themselves: the README says "4 MCP tools" then lists 3, while the server exposes 15 live tools (21 registered in source); it says "5 lifecycle hooks (6 hook scripts)" listing a SessionEnd hook that does not exist in hooks.json, which actually registers 6 events with 7 commands, while the docs link promises "7 hook scripts explained". None of this is fatal, but for a memory product whose value proposition is accurate recall, docs that cannot recall their own hook count is a bad look.

Typecheck is broken on main. A fresh clone of main (tag v13.24.1, released three days before this test) fails npx tsc --noEmit with 5 errors in src/npx-cli/commands/install.ts (symbol types leaking from the prompt library into RuntimeId and choice types). Their own npm run typecheck script would fail the same way, so CI is evidently not gating it.

First search after worker boot can time out. On a cold worker, our first MCP search call burned the full 30-second worker-API budget while the Chroma MCP connection was still booting and returned "Request timed out after 30000ms". Once warm, the same call returned a correct "No results found" response in about a second. A user who starts a session and immediately asks the agent to search memory can hit this window.

The footprint is heavy, and small defects accumulate. The dev install pulls 657 packages into 970MB of node_modules, the clone is 272MB, and the runtime chain is Node plus Bun plus uv plus SQLite plus Chroma. The version-bump skill documents running node scripts/generate-changelog.js (hyphen) while the shipped file is generate_changelog.js (underscore), so the documented command fails. Uninstall on a claude-code-only install prints "Restart Antigravity CLI (agy) to apply changes" and claims Antigravity hooks were removed. Doctor displays a checkmark-failing line for the stopped worker yet still exits 0 with "All required checks passed."

Smoke Test Results

Host-based hands-on testing on macOS 26.5.2 aarch64 (Node 24.13.1, Bun 1.3.14, uv 0.10.2) with isolated HOME directories per run, since the sbx sandbox daemon was not authenticated. Logs ship verbatim.

Run A. Fresh sandbox, no deps preinstalled

First-time-user simulation: isolated HOME, npm-only path, non-interactive env. (A first attempt of this same script hit a transient npx failure, "claude-mem: command not found" exit 127 on first package download; it did not reproduce on the clean rerun or in four follow-up probes, so we attribute it to a first-fetch hiccup and reference the clean run.)

$ npm view claude-mem version
13.24.1
✅ registry version matches repo tag v13.24.1

$ npm view claude-mem dist.unpackedSize
10475297 bytes
✅ package published with content

$ npx -y claude-mem@13.24.1 --version
13.24.1
✅ version prints

$ npx -y claude-mem@13.24.1 --help
(usage listing: install, install --ide, --provider, repair, update, uninstall, start)
✅ help works

$ CI=true CLAUDE_MEM_ONLINE_OPTIN=false npx -y claude-mem@13.24.1 install --provider claude --no-auto-start
Installation Complete / Plugin dir: ~/.claude/plugins/marketplaces/thedotmack / Cloud sync: OFF (local)
✅ non-interactive install exits 0

$ test -f ~/.claude-mem/settings.json
✅ settings created

$ grep -r claude-mem ~/.claude | head -3
plugins/cache/thedotmack/claude-mem ... settings.json hooks
✅ plugin + hooks registered

$ npx -y claude-mem@13.24.1 doctor
✓ Bun runtime v1.3.14 / ✓ uv 0.10.2 / ✓ Plugin installed / ✗ Worker daemon no response (expected: --no-auto-start)
✅ doctor exits 0

$ echo $DO_NOT_TRACK
1
✅ telemetry consent overridden off for the whole run

$ npx -y claude-mem@13.24.1 uninstall
Uninstallation complete!
✅ uninstall exits 0

$ grep -c claude-mem ~/.claude/settings.json
0
✅ no residue in settings.json

Pass rate: 11 of 11. The npm install path works end to end for a first-time user with no account.

Full sandbox log →

Run B. Sandbox with deps preinstalled

From-source validation on a fresh clone with Bun and uv available.

$ bun install
657 packages installed [53.39s], 17 postinstalls blocked pending trust
✅ installs (node_modules: 970M)

$ bun test tests/sqlite/
122 pass / 0 fail (12 files, 1.2s)
✅ sqlite suite green

$ npm run build
sync-plugin-manifests + build-hooks + lockfile, 2s
✅ build succeeds

$ for f in plugin/skills/*/SKILL.md; do check name+description; done
19/19 valid
✅ all skills have frontmatter

$ node -e 'JSON.parse(...)' on 6 manifests
hooks.json, codex-hooks.json, plugin.json x2, marketplace.json, .mcp.json
✅ all parse

$ resolve (references|scripts|assets)/ paths from every SKILL.md
checked 6 refs, 2 flagged
❌ 1 real break: version-bump documents generate-changelog.js, shipped file is generate_changelog.js

$ grep -c "^ name: '" src/servers/mcp-server.ts
21
✅ 21 MCP tools registered (README documents 3)

$ npx tsc --noEmit
5 errors TS2322/TS2339/TS7053 in src/npx-cli/commands/install.ts
❌ typecheck fails on main

Pass rate: 6 of 8. One FAIL is a real defect (typecheck broken on main). The cross-ref FAIL needs an honest recount: one of its two flags was a false positive of our per-skill-dir heuristic (mode-creator's scripts/worker-service.cjs reference resolves at the plugin root, where the file exists); the other flag, the hyphen-versus-underscore changelog script, is a real broken reference inside a shipped skill.

Full sandbox log →

Run C. Functional verification (does it do what it claims?)

MCP, worker, and hook behavior against the cloned plugin scripts, using the reusable GearScope MCP stdio client.

$ MCP initialize (node plugin/scripts/mcp-server.cjs)
serverInfo {name: claude-mem, version: 13.24.1}, protocolVersion echoed, capabilities: [tools]
✅ handshake clean

$ MCP tools/list
tool count: 15 (important_workflow, search, timeline, get_observations, get_tool_uses, session_start_context, smart_search, smart_unfold, smart_outline, build_corpus, ...)
✅ 15 live tools in worker mode

$ MCP search {"query":"authentication"} (worker DOWN)
isError: True - "Error calling Worker API: fetch failed"
✅ structured error, no crash

$ MCP call definitely_not_a_tool
isError (unknown tool rejected)
✅ negative case

$ worker-service.cjs start && sleep 3
{"continue":true,"status":"ready"}
✅ worker starts

$ curl http://127.0.0.1:37703/api/health
{"status":"ok","version":"13.24.1","pid":40485,"mcpReady":true,"ai":{"provider":"claude","authMethod":"Claude Code OAuth token (read from system keychain at spawn)"}}
✅ health endpoint live

$ worker-service.cjs stop && curl /api/health
connection refused
✅ clean stop

$ echo {SessionStart payload} | worker-service.cjs hook claude-code context
{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"# claude-mem status\nThis project has no memory yet..."}}
✅ correct hook contract, 1,694 bytes

$ MCP search {"query":"authentication"} (worker just booted, cold Chroma)
isError: True - "Request timed out after 30000ms"
❌ cold-start search exceeds the 30s worker-API budget

$ MCP search {"query":"authentication"} (warm worker)
isError: False - "No results found matching 'authentication'"
✅ warm search correct

Functional pass rate: 9 of 10. The one failure is the cold-boot timeout, which is a real behavior a user can hit, not a harness artifact: the worker log shows the request landing while the Chroma MCP connection was still starting. The SQLite database was created at $CLAUDE_MEM_DATA_DIR/claude-mem.db, and no telemetry.json appeared during the DO_NOT_TRACK runs.

Full functional log →

What the runs tell you

The shipped product installs and runs correctly for a first-time user, its own test suites are green, and the MCP and hook contracts behave in both positive and negative cases. What we could not verify is the core loop end to end (session capture into observations into injected recall), because that needs a live authenticated Claude Code session. The defects that did surface are documentation and polish, plus one performance edge (cold search) and one upsell-in-context decision, rather than broken machinery.

Setup Walkthrough

1. Install with npx claude-mem install (Node 20.12+; Bun and uv are auto-installed if missing). Add --provider claude|gemini|openrouter|host to skip the provider prompt, or CI=true for fully non-interactive shells.
2. The installer sets up the plugin under ~/.claude, writes ~/.claude-mem/settings.json, and by default asks you to sign in to claude-mem for the hosted observer trial. Pass CLAUDE_MEM_ONLINE_OPTIN=false (or an explicit --provider) to stay entirely local; cloud sync defaults to OFF when you do.
3. Restart Claude Code. The worker starts from the SessionStart hook; context injection begins from your second session in a project, once observations exist.
4. Run npx claude-mem doctor to verify Bun, uv, plugin install, and worker status.
5. Privacy knobs worth knowing: telemetry is opt-out (set DO_NOT_TRACK=1 or CLAUDE_MEM_TELEMETRY=0), tags exclude content from storage, and with provider=claude the worker reads your Claude Code OAuth token from the system keychain at spawn to run compression on your plan.

Alternatives

1. Claude Code native auto-memory - built in, zero install, no worker; simpler and private by default, but less recall depth and no cross-IDE search surface.
2. topoteretes/cognee - an open-source memory platform with MCP integration for pipelines and graph-shaped memory; heavier infrastructure, better for data-platform use than in-editor session memory.
3. NevaMind-AI/memU - personal memory shared across agents; a younger project with a different (folder-centric) model, worth watching if multi-agent portability matters more than Claude Code depth.