RELATED 01
claude-db
Project memory and a code-symbol graph for Claude Code, stored in your own SQLite, Postgres or MongoDB
233GitHub stars
113/wknpm downloads
45popularity score
Claude-Mem
Persistent memory plugin for Claude Code and other coding agents, with MCP tools to search past sessions
By Alex Newman (individual) TypeScript Local · stdio Knowledge and memoryDeveloper tools
107 popularity score ★ 114k ↓ 36k/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
FirstTerminal
npx claude-mem installClaude CodeTerminal
claude mcp add claude-mem -- node '<ABSOLUTE_PATH_TO_HOME>/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs'Claude Desktopclaude_desktop_config.json
{
"mcpServers": {
"claude-mem": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_HOME>/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"claude-mem": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_HOME>/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"claude-mem": {
"type": "stdio",
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_HOME>/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.claude-mem]
command = "node"
args = ["<ABSOLUTE_PATH_TO_HOME>/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"]Gemini CLITerminal
gemini mcp add --scope user claude-mem node -- '<ABSOLUTE_PATH_TO_HOME>/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs'Settings 12
| Set together: provider | |
|---|---|
CLAUDE_MEM_PROVIDER |
Optional: Which model condenses observations: claude, gemini, openrouter, openai-compatible, codex or cmem (hosted observer). The interactive installer offers cmem first. Set in ~/.claude-mem/settings.json or the environment. |
CLAUDE_MEM_MODEL |
Optional: Claude model used when the provider is claude. The haiku alias follows each new Haiku release. |
CLAUDE_MEM_GEMINI_API_KEY secret |
Optional: Gemini key, used when CLAUDE_MEM_PROVIDER=gemini. |
CLAUDE_MEM_OPENROUTER_API_KEY secret |
Optional: OpenRouter key, used when CLAUDE_MEM_PROVIDER=openrouter. |
CLAUDE_MEM_OPENAI_COMPAT_API_KEY secret |
Optional: Key for an OpenAI-compatible endpoint (with CLAUDE_MEM_OPENAI_COMPAT_BASE_URL), used when CLAUDE_MEM_PROVIDER=openai-compatible. |
CLAUDE_MEM_DATA_DIR |
Optional: Where the database, settings and logs are kept. |
CLAUDE_MEM_WORKER_PORT |
Optional: Port of the local worker API and viewer. Where there is no user ID (Windows) the offset comes from a hash of the data folder. |
CLAUDE_MEM_WORKER_HOST |
Optional: Address the worker binds to. |
CLAUDE_MEM_CHROMA_ENABLED |
Optional: Set to false to use SQLite-only search without the Chroma vector index. |
CLAUDE_MEM_WORK_STATE_ENABLED |
Optional: Set to false to hide work_state_write and work_state_read and the to-do section at session start. |
CLAUDE_MEM_RUNTIME |
Optional: worker (local SQLite) or server (beta server runtime, which adds the observation_* tools). |
CLAUDE_MEM_TELEMETRY |
Optional: Set to 0, false or off to stop anonymous analytics; DO_NOT_TRACK=1 also turns it off. |
What it does
Claude-Mem is a memory plugin for Claude Code and other coding harnesses such as Codex, Cursor, OpenCode and Pi. Lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) record what happens in a session. Each hook is a plain `claude-mem hook ...` command run through a small launcher the installer puts on PATH. A local background worker sends that activity to an AI model, which condenses it into observations and session summaries stored in SQLite under ~/.claude-mem, with an optional Chroma index for meaning-based search. Context from earlier sessions is fed into new ones.
The bundled MCP server is far larger than the README's short tool list: src/servers/mcp-server.ts defines 26 tools. In the default worker mode it advertises 19: the three-step search (search, then timeline, then get_observations), a quick one-call dumb_search, save_memory for explicit notes, a per-project to-do list (work_state_write and work_state_read, hidden when CLAUDE_MEM_WORK_STATE_ENABLED=false), code-structure tools (smart_search, smart_outline, smart_unfold) that read files inside the current workspace, and knowledge corpora built from observations that can be primed and questioned. team_brief and team_search appear only after the install joins a TeamBrain team, and five observation_* tools only when CLAUDE_MEM_RUNTIME=server (src/servers/mcp-tool-visibility.ts).
TeamBrain is an optional paid shared workspace on cmem.ai. Each person picks which projects to share, and personal requests and review notes stay local. Install with `npx claude-mem install`. It asks in the terminal which agents to set up, or you can name one with `--ide <id>`, and `--runtime worker` picks the local runtime up front. The /plugin marketplace commands inside Claude Code work too, and `npx claude-mem doctor` checks a broken setup. A global npm install gives only the SDK.
What it needs
| Runtime | Node.js 20.19+Bun |
|---|---|
| Runs on | macOS, Windows, Linux |
| Anthropic (Claude plan or API) | Paid planDefault observer model; or set your own Gemini, OpenRouter, OpenAI-compatible or Codex provider, or the hosted claude-mem observer (30-day free trial). |
| Also |
|
Run `npx claude-mem install` in an interactive terminal first. It asks which agents to set up (skip the question with `--ide <id>`), registers the hooks, installs Bun and uv when they are missing and places the claude-mem launcher on PATH. It then opens setup in the browser with an email sign-in for the hosted observer, which you skip with an explicit --provider flag or CLAUDE_MEM_ONLINE_OPTIN=false. Node must be 20.19 or later in the 20 line, or 22.12 or later. Restart the terminal or IDE so the new PATH is picked up. If hooks report that claude-mem is not found, run `npx claude-mem doctor`. Other MCP clients such as Claude Desktop point at the installed plugin's scripts/mcp-server.cjs.
Limits
- Not covered The MCP tools search what the hooks captured; a client without the plugin's hooks has an empty memory unless another harness filled it.
- Not covered Copilot CLI, Goose, Roo Code and Warp get memory search only: their sessions are not recorded.
- Cost Every captured event is condensed by an AI model, which uses your Claude plan by default or a provider key you pay for.
- Not covered team_brief and team_search are hidden until the install joins a TeamBrain team (CLAUDE_MEM_TEAMBRAIN_URL set); TeamBrain is a paid cmem.ai plan.
- Early release The server runtime (CLAUDE_MEM_RUNTIME=server) and the hosted /v1/mcp server are labelled beta; observation_* tools exist only there.
- Not covered smart_search, smart_outline and smart_unfold only read paths inside the current workspace and need the tree-sitter CLI to be found.
- Limit Anonymous usage analytics and redacted error reports go to PostHog by default; see the telemetry note.
- Limit `npm install -g claude-mem` installs only the SDK and does not set up hooks, worker or the MCP server.
Who it suits
It suits developers who use Claude Code (or OpenCode, T3 Code, Pi and the other supported harnesses) daily and want earlier sessions' decisions and fixes carried forward without writing notes by hand. Memory stays in local SQLite unless you opt into cloud sync or TeamBrain. It is not a standalone memory server for any MCP client: the value comes from its capture hooks, it runs a background worker, and each captured event costs model usage. If you only want an assistant to store and recall notes you write explicitly, a plain memory server without capture hooks is lighter.
Tools 26
17 only read, 9 change things. A ? marks an optional parameter.
search- Step 1: full-text search of stored observations, returning a compact index of IDs, titles, dates and types.
query?: stringlimit?: numberproject?: stringprojectId?: stringplatformSource?: stringtype?: stringobs_type?: stringdateStart?: stringdateEnd?: stringoffset?: numberorderBy?: string timeline- Step 2: show the observations recorded before and after one ID, or around the best match for a query.
anchor?: anyquery?: stringdepth_before?: numberdepth_after?: numberproject?: stringprojectId?: string get_observations- Step 3: fetch the full text of the observations whose IDs you picked.
ids: arrayprojectId?: string dumb_search- One-call lookup by title word overlap that returns an index plus a few full records; faster but shallower than the three-step search.
query: stringproject?: stringlimit?: integermaxDetails?: integerdepthBefore?: integerdepthAfter?: integer important_workflow- Returns a reminder of the three-step search workflow; kept visible for the assistant rather than for real use.
get_tool_uses- Fetch the raw input and output of tool calls already found through search; large and unsummarised.
ids: arraylimit?: numberproject?: stringcontentSessionId?: string save_memorychanges- Store a note, decision or handoff you write yourself (worker mode only).
text: stringtitle?: stringproject?: stringmetadata?: object work_state_writechanges- Add or update an entry on a named per-project to-do list that is shown at the start of later sessions.
list: stringfields: object work_state_read- Read the project's to-do lists, optionally including done and dropped items.
list?: stringincludeClosed?: boolean team_brief- TeamBrain summary for a project: overlapping work, recent plans and decisions, active teammates, delegated work.
project?: string team_search- Search what teammates shared to TeamBrain.
query: stringlimit?: integer session_start_context- Render the context text the hooks would inject at session start for a project.
project?: stringprojects?: anyplatformSource?: stringfull?: booleancolors?: boolean smart_search- Find symbols, functions and classes in the workspace's code by tree-sitter parsing; 20 results by default.
query: stringpath?: stringmax_results?: numberfile_pattern?: string smart_outline- Show a source file's symbols and signatures with bodies folded.
file_path: string smart_unfold- Return the full source of one named symbol from a file.
file_path: stringsymbol_name: string build_corpuschanges- Collect observations matching filters into a named knowledge corpus.
name: stringdescription?: stringproject?: stringtypes?: stringconcepts?: stringfiles?: stringquery?: stringdateStart?: stringdateEnd?: stringlimit?: number list_corpora- List knowledge corpora with their size and priming state.
prime_corpuschanges- Start a model session loaded with a corpus so it can be questioned.
name: string query_corpuschanges- Ask a primed corpus a question.
name: stringquestion: string rebuild_corpuschanges- Re-run a corpus's stored filter to pick up newer observations.
name: stringforce?: boolean reprime_corpuschanges- Start a fresh session for a corpus, dropping earlier questions and answers.
name: string observation_addchanges- Insert an observation directly into server storage (server runtime only).
content: stringprojectId?: stringserverSessionId?: stringkind?: stringmetadata?: object observation_record_eventchanges- Record an agent event on the server and queue an observation for it (server runtime only).
eventType: stringprojectId?: stringsourceType?: enumserverSessionId?: stringcontentSessionId?: stringmemorySessionId?: stringplatformSource?: stringpayload?: anyoccurredAtEpoch?: numbergenerate?: boolean observation_search- Full-text search of observations on the server (server runtime only).
query: stringprojectId?: stringplatformSource?: stringlimit?: number observation_context- Get the most relevant observations plus a ready-made context string (server runtime only).
projectId?: stringquery?: stringplatformSource?: stringlimit?: number observation_generation_status- Check the status of an observation generation job (server runtime only).
jobId: string