Claude-Mem
Persistent, searchable project memory for coding agents across sessions.
Per-dimension scores and reasoning
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.
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.
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 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.
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.