claude-mem: Give Your Coding Agent a Memory That Survives the Session

claude-mem is a persistent memory system for coding agents, built for Claude Code and extended to other harnesses. It automatically captures tool usage observations during a session, generates semantic summaries of what happened, and makes them available to future sessions, so the agent keeps continuity of knowledge about your projects even after a session ends or reconnects.

It comes from Alex Newman (@thedotmack), is written in TypeScript, and is licensed under Apache 2.0. The repository was created on August 31, 2025, and when we checked on November 3, 2026 it had 111,386 stars and 9,706 forks, with a version 15.9.0 badge on the README and translations into more than thirty languages. That scale makes it one of the most starred developer tools on GitHub, and it is trending again today.

The pitch is simple: the most annoying thing about AI coding agents is that they forget everything when the session ends. You re-explain decisions, re-find bugfixes, and re-teach conventions every time you start over. claude-mem records what the agent does, summarizes it, and feeds it into the next session automatically, so the next session starts where the last one ended.

The system has six core components. Lifecycle hooks fire at SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop and SessionEnd, each as one shell-free command, claude-mem hook claude-code <event>, run by a small launcher the installer puts on PATH. A smart install step checks cached dependencies, and a worker service provides a local HTTP API with a web viewer UI and search endpoints, managed by Bun.

Underneath, a SQLite database stores sessions, observations and summaries, with FTS5 full-text search, and a Chroma vector database adds hybrid semantic plus keyword search for intelligent retrieval. A mem-search skill ties it together: the agent queries its own project history in natural language instead of relying on whatever fits in the current context window.

Two more pieces round it out. A local My Work view shows live requests, progress, human handoffs and a saved review queue at the worker URL printed on startup, with memory, sessions and settings at /viewer. TeamBrain is an optional shared workspace beside it, with real team work lists and member attribution, where each person chooses what to share and personal requests and review notes stay separate.

Memory is only useful if recalling it does not eat the context window it is meant to save. claude-mem's answer is a three-layer workflow through its MCP search tools, designed around progressive disclosure: filter cheaply first, fetch details only for what survives.

First, search returns a compact index with IDs, at roughly 50 to 100 tokens per result. Then timeline gives chronological context around the interesting results, so the agent sees what was happening around a decision rather than a single isolated note. Finally, get_observations fetches full details only for the filtered IDs, at roughly 500 to 1,000 tokens per result. The README claims about 10x token savings from filtering before fetching, and the shape of the workflow makes the claim easy to believe: most results never reach the expensive layer.

Search supports full-text queries with filters by type, date and project, and observation types include decisions, bugfixes, security alerts and other needles worth finding later. Citations work through observation IDs, viewable in the web viewer or through the worker API.

The recommended install is a single command, and the installer sets everything up before asking anything of you:

npx claude-mem install

After setup it asks you to sign in to claude-mem in your browser with an email magic link, no card required. Signing in provisions a memory key and unlocks the claude-mem observer with a 30 day free trial, during which memory runs off-plan, so you get up to 100 percent more usage from your plan. When the trial ends, memory automatically falls back to your Anthropic plan unless you subscribe.

Prefer to skip the sign-in? Pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false, or run in CI or a non-interactive shell, and the installer completes without any account interaction. You can pick the claude-mem observer, your own OpenRouter or Gemini key, or your Anthropic plan as the memory provider.

One trap to avoid: claude-mem is also published on npm, but npm install -g claude-mem installs the SDK and library only. It does not register the plugin hooks or set up the worker service, so always install via npx claude-mem install or the plugin marketplace commands. Inside Claude Code that is /plugin marketplace add thedotmack/claude-mem followed by /plugin install claude-mem, then a restart.

Although it started with Claude Code, claude-mem now covers a wide bench of harnesses. OpenCode works from version 1.3.4 onward, including OpenCode 2, with npx claude-mem install --ide opencode and a restart. T3 Code, which manages Codex and Claude Code providers, gets native plugins through --ide t3code. Antigravity CLI, Oh My Pi, Pi and DeepSeek Harness all have their own install flags or guides, and OpenClaw gateways get a one-line curl installer that handles dependencies, plugin setup, provider configuration, worker startup and optional real-time observation feeds to Telegram, Discord and Slack.

Grok Bot is a special case worth knowing about: it has no host hooks, so claude-mem watches its chat log files instead, and an awareness push pilot appends dated needle observations into that bot's memory log. If you use several harnesses, one setting matters: CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES in the settings file includes observations from every harness in Claude Code and Codex session-start context. The default is false, which limits startup context to the current harness.

Workflow modes add another layer. The CLAUDE_MEM_MODE setting controls both behavior and the language of generated observations, with modes such as code, code--zh and code--ja defined in the plugin's modes directory. Restart Claude Code after changing it.

A tool that records everything your agent does has to answer the privacy question first, and claude-mem gives you real controls rather than a promise. Wrap content in <private> tags to exclude it from storage entirely. Screenshots are opt-in and off by default: when enabled, converted copies are kept under ~/.claude-mem/media-v1/, uploaded to cmem.ai only when Cloud Sync is on, and sent to the observer model only when image inference is separately enabled.

Settings live in ~/.claude-mem/settings.json, auto-created with defaults on first run, covering the AI model, worker port, data directory, log level and context injection settings. Cloud Sync backs memories up to cmem.ai with no daemon, since the worker syncs on write. The viewer settings also expose the include-all-sources toggle, so you can change recall behavior without editing JSON.

System requirements are modest but specific: Node.js 20 or higher, a recent Claude Code with plugin support, Bun as the runtime and process manager, uv for vector search, and SQLite 3, with Bun and uv auto-installed if missing. On Windows, the installer places a launcher at %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe and adds it to your user Path; restart your terminal or IDE afterwards, and run npx claude-mem doctor if hooks report the executable as missing.

The free trial is the first thing to calendar. After 30 days, memory falls back to your Anthropic plan unless you subscribe, so a workflow built on off-plan memory quietly gets thinner if you do nothing. The README is upfront about this, but it is easy to miss in the excitement of the first week.

The second watch-out is provider choice. The default path signs you into a hosted observer, which means your agent's observations pass through a third-party service. If that bothers you, the local observer and bring-your-own-key options exist, but they are opt-in, not the default, so choose deliberately at install time rather than accepting the default flow.

Finally, one naming trap: CMEM is a token created by a third party but officially embraced by claude-mem's creator as a community catalyst. It is not the tool, not a licence, and not required to use it, so do not confuse buying or holding it with using claude-mem. The tool itself is Apache 2.0 open source, and its docs live at docs.claude-mem.ai with installation, usage, search, architecture and troubleshooting guides.