Who claude-mem is for#
Developers on long-running codebase projects
On a project active for weeks or months, accumulated context (architectural decisions, dead ends, conventions, dependency choices) is valuable. claude-mem captures that context automatically and injects it at the start of each session, so the agent picks up where it left off rather than starting from the README.
Skip if:
Your project is a short-lived script or one-session task. The memory engine's value scales with session count; on a two-session project the overhead of setup outweighs the benefit.
Teams using multiple agents and IDEs simultaneously
When a team uses Claude Code for one task and Cursor for another, each agent normally operates in isolation. claude-mem writes all observations to a shared local database (or a shared CMEM Cloud timeline on the paid tier), so context captured in one agent is available to the others without any manual sync.
Skip if:
Your team's agents are intentionally siloed and sharing context between them would create interference. Use per-project database directories to keep observations separate in that case.
AI engineers studying agent memory architectures
claude-mem provides a working implementation of observation capture, vector indexing, semantic retrieval, and MCP serving in a single installable package. Engineers exploring how to build agent memory into their own tooling can study the hooks architecture, the SQLite schema, and the 3-layer MCP workflow as a reference implementation.
Skip if:
You are building a multi-tenant product that needs a scalable memory API for end-users. claude-mem is designed for local, single-developer or small-team use; managed services like Mem0 or Pinecone are a better starting point for multi-tenant workloads.
The problem it solves#
AI coding agents start every session without any memory of previous work. The agent does not know which architectural decisions were already made, which approaches were tried and discarded, or what conventions the project follows. Developers spend the first minutes of every session re-explaining context that was already established, or watching the agent repeat a mistake from three sessions ago.
The problem compounds on larger codebases. Context that would take seconds to recall from memory takes minutes to re-establish from scratch, and in practice it often never fully comes back. The alternative of manually maintaining a memory file or README is a second job on top of the actual work.
How it solves it#
Lifecycle hook-based observation capture
Five hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) intercept every agent action automatically. Each observation is structured and written to a local SQLite database without any manual input. The engine runs in the background via a Bun worker process, so no intervention is needed between sessions.
Hybrid semantic and keyword search
Memory retrieval combines SQLite full-text search (FTS5) with a Chroma vector database for semantic matching. At session start, the most relevant prior observations are ranked and injected into context. A 3-layer MCP workflow (search index, timeline, get_observations) delivers roughly 10x token savings over naive full-history injection.
Multi-IDE and multi-agent support
Installs natively into Claude Code, OpenCode, Codex CLI, Cursor, Gemini CLI, and other MCP-compatible clients. A single observation database is shared across all of them, so context captured in one agent is available in another. The CMEM Cloud tier extends this across machines via a private MCP link.
Privacy control with private tags
Wrap any content in <private> tags to exclude it from observation storage. This lets developers keep sensitive credentials, client-specific details, or personal notes out of the memory database without disabling capture for the whole session.
Configurable workflow modes and languages
The CLAUDE_MEM_MODE setting controls both the capture behavior (code, chill, investigation) and the language used in generated observations. Built-in modes include English (default), Simplified Chinese, and Japanese, with ISO 639-1 language codes available for additional locales.
Optional CMEM Cloud sync for cross-device access
The local SQLite database mirrors to CMEM Cloud behind a private MCP link, making the full memory timeline accessible from any machine or agent. The free, open source engine runs without a cloud account; the $20/month cloud tier adds cross-device sync, a live mobile feed, and end-to-end private key scoping.
Strengths and trade-offs#
Strengths
- Apache-2.0 license with full self-hostingThe entire engine runs on your own machine with no licensing fees, no usage caps, and no cloud dependency. Apache-2.0 permits commercial use, modification, and redistribution without restriction. Unlike Pinecone or Mem0 Cloud, there is no per-query billing and no vendor dependency on the data path.
- Single-command install across IDEsnpx claude-mem install handles dependency detection, hook wiring, database creation, and worker startup automatically. The installer checks for Bun and uv/Python and installs them if missing, so the only explicit prerequisite is Node.js 20 or higher. The same install pattern works for Claude Code, OpenCode, and other supported clients with one flag.
- Token-efficient progressive disclosureThe 3-layer MCP workflow surfaces a compact index first (~50-100 tokens per result), then timeline context, then full details only for the IDs that are relevant. This approach delivers roughly 10x token savings compared to injecting all prior observations at the start of each session, which keeps cloud API costs predictable.
- Active development and broad communityThe repository shows sustained development, with the last push within two days of this writing and 92,000+ GitHub stars. The project is listed in Awesome Claude Code and ships multilingual README translations across 30+ languages, reflecting a broad, active contributor community. Version 13.4.0 is published on npm.
Trade-offs
- -Requires Bun and uv for full functionalityThe Bun JavaScript runtime manages the local worker process, and uv (a Python package manager) installs the Chroma vector database for semantic search. Both are auto-installed by the installer if missing, but this adds startup overhead on first install and introduces two non-obvious system dependencies that users maintain independently.
- -Node.js 20 or higher requiredThe minimum Node.js version is 20.0.0. Developers on older Node versions (common in enterprise environments with locked-down toolchains) need to upgrade before install. The README notes that Windows users may need to update PATH manually after a Node.js installation.
- -High open issue count reflects active edge casesWith 312 open issues, the project is actively used and actively developed, but some rough edges exist. Users on Windows, non-standard IDE configurations, or less common MCP clients may encounter setup issues not yet covered by the official troubleshooting guide.
claude-mem vs alternatives#
claude-mem vs Pinecone
Pinecone is a fully managed vector database service used to build semantic search and RAG pipelines into applications. claude-mem serves a different purpose: it is an agent-local memory engine that runs on your machine, writes to SQLite and Chroma, and injects context at the session level rather than exposing a general-purpose query API.
| Feature | claude-mem | Pinecone |
|---|---|---|
| License | Apache-2.0 | Proprietary |
| Self-hosting | Yes, local | No |
| Storage | SQLite + Chroma (local) | Managed cloud |
| Primary use | Agent session memory | App-level vector search |
| Pricing | Free (self-hosted) | Free tier, then pay-per-use |
claude-mem is the better pick when your goal is giving an AI coding agent continuity across sessions on a local machine. Pinecone is worth considering when you need a scalable, managed vector index accessible from multiple backend services with no infrastructure overhead on your end.
claude-mem vs Mem0
Mem0 is a commercial memory layer for AI applications, available as a managed cloud API and a self-hosted open source version. Both tools give AI agents persistent memory, but they serve different workflows. Mem0 is built for product teams embedding agent memory into their apps; claude-mem is built for developers who want session continuity in their own coding environment.
| Feature | claude-mem | Mem0 |
|---|---|---|
| License | Apache-2.0 | Apache-2.0 (OSS) / Proprietary (cloud) |
| Self-hosting | Yes, full | Yes (open source version) |
| Primary use | Local agent session memory | App-level agent memory API |
| IDE integration | Native (Claude Code, Cursor, etc.) | API-based |
| Install | npx claude-mem install | Self-hosted or managed API |
For a developer who wants persistent memory in their own coding sessions without API integration or a cloud account, claude-mem installs in one command and works without leaving the terminal. Mem0's commercial platform is worth considering when you are building an application that needs a managed memory API for end-users or third-party agents.
Install and self-host#
Install the plugin into Claude Code or any supported agent IDE with one command.
```bash
npx claude-mem install
```What it's built on#
- Languages
- JavaScriptTypeScript
- Frameworks
- ExpressReact
- Databases
- PostgreSQLSQLite
- Cache
- Redis
- Tooling
- esbuild
FAQ#
Does claude-mem require a cloud account or internet connection to work?
No. The core engine runs entirely on your local machine with no internet connection required. It writes observations to a local SQLite database and serves them via a local HTTP API. The optional CMEM Cloud tier ($20/month) adds cross-device sync and a private MCP link, but the free open source version has no cloud dependency.
Which AI agents and IDEs does claude-mem support?
claude-mem installs natively into Claude Code and OpenCode via npx. It also supports Cursor, Codex CLI, Gemini CLI, Copilot, Hermes, and other MCP-compatible clients. The CMEM Cloud private MCP link extends compatibility to any agent that can connect to an MCP server. The README lists the full set of supported clients.
How does claude-mem protect sensitive information from being stored?
Oops! Something went wrong
[next-mdx-remote-client] error compiling MDX: Expected a closing tag for `<private>` (1:21-1:30) before the end of `paragraph` > 1 | Wrap any content in <private> tags during a session and claude-mem will exclude it from the observation database. This handles credentials, client-specific details, or anything else you do not want persisted. All data is stored locally on your machine by default; the cloud tier uses end-to-end private keys scoped to your account. | ^ More information: https://mdxjs.com/docs/troubleshooting-mdx
Is the CMEM Cloud paid tier required to use claude-mem?
No. The open source engine (Apache-2.0) is fully functional without a cloud account. It stores all observations locally, runs semantic search locally via Chroma, and serves context via a local MCP worker. The $20/month CMEM Cloud tier adds cross-device sync, a mobile feed, and a private MCP link accessible from any machine.
How is claude-mem different from manually maintaining a context file?
claude-mem captures observations automatically during every agent session via lifecycle hooks, without requiring manual updates. It indexes them with semantic vector search, so retrieval at the start of a new session is ranked by relevance rather than requiring you to know what to look for. A manually maintained context file requires discipline to keep current; claude-mem requires no maintenance after the initial install.
Similar open-source tools#
Supermemory
Add persistent user memory to any LLM app via API, Apache 2.0
Qdrant
Self-hosted vector database for AI similarity search and RAG
Weaviate
AI-native vector database for semantic search and AI apps
turbovec
Rust vector index with TurboQuant compression, no managed service
ai-memory
Persist AI agent context across sessions and tool switches
mex
Persistent memory and code graph for AI coding agents