Claude-Mem
Persistent, searchable project memory for coding agents across sessions.
- Source repo
- thedotmack/claude-mem
- Stars
- ★ 113k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 73/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude CodeClaude.ai (Partial support)
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Claude Code developer maintaining a long-lived codebase who needs a new session to recover earlier authentication debugging context.
- Not a fit if
- Teams avoiding Node.js, Bun, and uv runtime dependencies
- Users needing non-Claude integrations documented as fully as Claude Code
- Teams unable to consistently mark sensitive tool-use records
- Source review
- 73/100 · Some gaps
What does this agent do, and when should you use it?
Claude-Mem is a persistent memory-compression system built for Claude Code, with the repository description also listing Codex, OpenCode, and other agent environments. Lifecycle hooks capture tool-use observations, create semantic summaries, and inject relevant context into later sessions. Its components include a Bun-managed local Worker Service, SQLite, Chroma vector search, a Web Viewer, and the mem-search Skill. The worker exposes a local HTTP API, search endpoints, and a live memory stream, while SQLite stores sessions, observations, and summaries. It fits developers who need continuity across coding sessions, although its most fully documented installation path is the Claude Code plugin workflow.
Claude-Mem runs hook scripts around SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd to capture agent tool-use observations and generate semantic summaries. It stores sessions, observations, and summaries in SQLite, and uses a Chroma vector database alongside keyword search for hybrid retrieval. In a later session, relevant stored context can be injected automatically; MCP retrieval can start with search, add chronological context with timeline, and fetch selected full records with get_observations(ids=[...]). The Bun-managed Worker Service provides a local HTTP API, search endpoints, and a Web Viewer. Content wrapped in <private> tags is excluded from storage.
- A Claude Code developer maintaining a long-lived codebase who needs a new session to recover earlier authentication debugging context.
- An engineer investigating a multi-session bug who wants to search compact observation indexes before fetching only the relevant full records.
- An OpenCode user who wants to add persistent memory to coding sessions with
npx claude-mem install --ide opencode. - A team operating an OpenClaw Gateway that needs a persistent-memory plugin and may route real-time observation feeds to Telegram, Discord, or Slack.
- A technical lead who needs to inspect locally stored project memory through the worker's Web Viewer or HTTP API.
How do you install or deploy this agent?
For Claude Code, run npx claude-mem install, then restart Claude Code; prior-session context is then injected automatically into new sessions. For OpenCode, run npx claude-mem install --ide opencode; for Antigravity CLI, run npx claude-mem install --ide antigravity. Inside Claude Code, the documented alternative is /plugin marketplace add thedotmack/claude-mem followed by /plugin install claude-mem. Node.js 20.0.0 or later is required; Bun and uv are auto-installed when absent, and SQLite 3 is bundled. The supplied material does not specify any required API key or credential.
How do you use this agent?
After installation and restart, Claude-Mem operates automatically. Configure its AI model, worker port, data directory, log level, and context-injection settings in ~/.claude-mem/settings.json; for example, set {"CLAUDE_MEM_MODE":"code--zh"} and restart Claude Code to use Simplified Chinese mode. For retrieval, use progressive disclosure: search(query="authentication bug", type="bugfix", limit=10), then timeline, then get_observations(ids=[123,456]) for selected records. Wrap content that must not be stored in <private> tags.
What are this agent's strengths and limitations?
- Automatically captures tool-use observations through lifecycle hooks and reinjects relevant context in later sessions.
- Combines SQLite-backed storage with Chroma semantic search and keyword search, exposed through layered
search,timeline, andget_observationsretrieval. - Runs a local worker with an HTTP API, search endpoints, and a Web Viewer for both programmatic and visual inspection.
- Supports
<private>exclusions and fine-grained control over context injection.
- The most detailed documented installation and hook workflow is centered on the Claude Code plugin; the supplied material gives less equivalent integration detail for the other listed agent environments.
- It requires Node.js 20+, and depends on Bun, uv, SQLite 3, and Chroma vector search, adding runtime setup beyond a standalone CLI.
- It stores tool-use observations and session summaries;
<private>tags help, but teams still need a reliable convention for marking sensitive material. npm install -g claude-meminstalls only the SDK/library and does not register hooks or configure the worker, creating a documented deployment pitfall.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Claude-Mem This agent | 73 · Some gaps | CLIFreemium | ★ 113k | today | TypeScript | Codex · Claude Code |
| Ori Mnemos | 80 · Good | CLIFree | ★ 335 | 1mo ago | TypeScript | Claude Code · OpenAI API · Claude API |
| Claudex | 69 · Some gaps | CLIFree | ★ 97 | 4mo ago | JavaScript | Claude Code |
| PowerContext | 55 · Major gaps | CLIFree | ★ 1.5k | 1d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: SECURITY.md explicitly states default binding to 127.0.0.1, port range validation, no root privileges, local data storage, and detailed data flow (including sending to upstream model providers). Deductions: user confirmation mechanism is weak, only mentions <private> tags, no explicit user consent during installation or operation; rollback mechanism not clearly documented, only mentions version updates.
Evidence shows: CI workflow includes typecheck, build, test, bundle-size guardrails, and Docker e2e for server runtime; tests cover multiple adapters and security regressions. Deductions: dependency availability not fully verified because no committed root lockfile, install uses npm install not npm ci; failure messages not detailed in docs, only troubleshooting guide mentioned.
Evidence shows: README supports multiple IDEs (Claude Code, OpenCode, Antigravity CLI, OpenClaw), multiple installation methods, and multiple language modes. Deductions: capability boundaries not clearly defined, e.g., what operations are captured vs excluded; trigger precision not detailed, only mentions lifecycle hooks.
Evidence shows: README well-structured with quick start, documentation links, configuration, troubleshooting; translations in many languages; license Apache-2.0 with full LICENSE file; version number in package.json. Deductions: known limitations not explicitly listed, only troubleshooting; changelog not in provided files but README mentions CHANGELOG.md.
Evidence shows: output usability high with MCP search tools, web viewer UI, skills; marginal value high with persistent memory across sessions, progressive disclosure, ~10x token savings; cost-benefit not quantified but token savings claimed. Deductions: cost-benefit lacks concrete data, only claims savings.
Evidence shows: claims in README consistent with SECURITY.md and package.json; test files verify specific behaviors (e.g., bun-runner regressions, BMP safety); but no external sources corroborate. Deductions: fact vs inference not clearly separated, e.g., performance claims in README without benchmarks.
- This tool captures all session data and sends it to upstream model providers; review settings and privacy tags before use.
- Installation scripts modify Claude Code configuration and start background worker services; ensure you trust the source.
- Publisher identity is unverified; obtain from official channels and verify checksums.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's new Onboarding finds your existing work. Setup now leads with discovering your existing work, rules and focus from your transcripts. The main button is "Discover My Work, Rules & Focus", and "Skip this step" is a smaller action under it. The "Share anonymous usage statistics to help improve your Claude-mem experience" box starts checked; unchecking it is kept, and nothing is sent until you press Discover. When hosted setup is busy, claude-mem checks capacity before uploading, remembers the cooldown across restarts and lets you finish setup. (#5270, #5308, #5384 by @thedotmack) …View on GitHub ↗ -
Release notes excerpt
What's new Devin support. npx claude-mem install can now set up Devin CLI and Devin Desktop: hooks are written for you, Devin's tool names are understood, and the memory search tools are registered. (#5172, #5276 by @patrickballard and @ssthormess) My Work refresh on your terms. My Work and Past Focus have a "Refresh now" button (#5249 by @Kirat0201). New settings choose the refresh model per provider: CLAUDE_MEM_WORK_VIEW_CLAUDE_MODEL, CLAUDE_MEM_WORK_VIEW_CODEX_MODEL and CLAUDE_MEM_WORK_VIEW_GEMINI_MODEL (#5236 by @LucianVane). …View on GitHub ↗ -
Release notes excerpt
Privacy fix Browser setup no longer uploads your prompts to cmem.ai without asking. Fixes #5176. The browser setup opened by npx claude-mem install (since v15.2.0) scanned local agent histories and uploaded the full text of the last 30 days of prompts, with session IDs, project names, folder paths and timestamps, without asking. What changed (#5220) - The scan now reads local history only, then stops and asks. Nothing leaves the machine until you answer. - A new consent panel states what is sent and lists each detected tool with its prompt count. Only ticked tools are uploaded. …View on GitHub ↗
FAQ
Does it store every piece of session content?
<private> tags exclude sensitive content from storage; the system otherwise stores tool-use observations, sessions, and summaries.Will searching history consume a large amount of context?
search returns a compact index of roughly 50–100 tokens per result, then selected records can be retrieved with get_observations at roughly 500–1,000 tokens per result.Is a global npm install enough to set it up?
npm install -g claude-mem installs only the SDK/library. Use npx claude-mem install or the documented Claude Code plugin commands to register hooks and set up the worker.Can observations be generated in Chinese?
CLAUDE_MEM_MODE to code--zh in ~/.claude-mem/settings.json and restart Claude Code.