Give Your AI Coding Assistant Long-Term Memory: claude-mem Keeps Claude Code from Forgetting

claude-mem is a 96k-star open-source plugin (Apache-2.0) that gives coding agents like Claude Code, Codex, and Gemini CLI real long-term memory. It auto-logs what the agent did, compresses it into summaries, and feeds relevant context back next session — no more re-explaining your project every morning. For developers on multi-day builds who are done with assistant amnesia.

Data cited from the official repository and documentation (checked on October 6, 2026).

In a nutshell: A 96k-star open-source plugin (Apache-2.0) that adds a cross-session memory layer to programming agents like Claude Code, Codex, and Gemini CLI. It automatically logs what the agent has done, compresses it into summaries, and feeds relevant context back in when you start a new session—saving you from having to re-explain the project background every single time.

The Pain Point: Close the Session, and the Assistant Amnesia Kicks In

When working on a multi-day project using tools like Claude Code, the most frustrating part isn’t that the model lacks intelligence; it’s that it just can’t remember things:

The API contracts and hard lessons established yesterday all have to be re-explained when starting a fresh session today;
Long sessions trigger automatic compression, washing away the details and causing the agent to start repeating mistakes in the second half;
Manually maintaining project notes by writing CLAUDE.md helps, but it relies entirely on discipline, and things fall out of sync when you get busy.

The root of the problem: An agent’s “working memory” lives entirely inside the current session. It isn’t persisted to disk, nor is there a mechanism to retrieve it on demand.

What It Solves: Record → Compress → Inject on Demand

claude-mem treats memory as a sidecar system, sparing you from manual note-taking entirely:

Automatic Logging: Uses 5 lifecycle hooks (session start, prompt submission, post-tool execution, stop, and session end) to capture the agent’s tool-calling process into sequential “observations”;
AI Compression: A background worker uses your configured model to compress these observations into semantic summaries, storing them in a local SQLite database (powered by FTS5 full-text search), with an optional Chroma vector index for semantic search;
On-Demand Injection: When a new session spins up, only memories relevant to the current project are injected into the context rather than dumping the entire history blindly—the maintainers call this “progressive disclosure,” with token savings being a major selling point (savings ratios are based on official/community claims and remain to be fully verified);
Searchable & Visual: Provides MCP search tools and mem-search skills, allowing you to query things in natural language like “how did I fix that login bug last week?”; a local web dashboard lets you watch the memory stream in real-time; and it automatically generates a CLAUDE.md complete with an activity timeline in your project folder;
Privacy Control: Drop a <private> tag into the content to keep it out of the database, and disable cross-source injection for sensitive projects.

This neatly complements two tools previously covered on this site: Agent Reach gives agents “eyes” (browsing Twitter, Reddit, and Bilibili), while claude-mem gives them “memory.” Meanwhile, WeKnora handles document knowledge base Q&A—which is entirely different from an “agent’s own working memory,” so don’t confuse the two.

Claude-mem AI coding assistant long-term memory cover image

Prerequisites

Node.js: Version 20.0.0 or higher—this is a hard requirement;
Bun: Version >= 1.0. If missing during installation, it will be installed automatically to run the worker;
uv: Also installed automatically to provide the Python environment for Chroma vector search;
Host Tools: Claude Code (plugins support the latest version), along with Codex CLI, Gemini CLI, OpenCode, Cursor, etc., each with corresponding --ide installation methods;
Hardware: Doesn’t demand a heavy GPU or massive RAM; it’s essentially a lightweight local service plus a SQLite database, with all data stored under ~/.claude-mem/;
Model Costs: Observation compression requires calling an LLM. You can use your own Anthropic, OpenRouter, or Gemini API keys. The project also offers a hosted observer (email login during installation with a 14-day trial, after which it automatically falls back to your own configuration). If you don’t want to register an account, explicitly specify the --provider flag during installation or install via the plugin marketplace to skip it.

Getting Started in Three Steps

1. Installation (Choose One)

Install and register hooks with a single command:

npx claude-mem install

npx claude-mem install

Or install via the Claude Code plugin marketplace:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Note: npm install -g claude-mem only installs the SDK/library; it will neither register hooks nor start the worker. Don’t fall for this—a pitfall explicitly highlighted in the official documentation.

2. Restart and Verify

Restart Claude Code, do some quick work in any project (read a few files, modify a snippet), and then open a new session. Check if it automatically brings along the context from the previous session at startup. Next, open the local dashboard address printed when the worker boots up (typically localhost:37777, though newer versions assign ports dynamically per user—check your terminal output). If you see memories streaming in one by one, the pipeline is fully operational.

3. Switch to Chinese Mode (Optional but Recommended)

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODE": "code--zh"
}

{
  "CLAUDE_MEM_MODE": "code--zh"
}

code--zh is the built-in Simplified Chinese mode (out of 28 supported languages). Save the file and restart to take effect. Future observations and summaries will be generated in Chinese, making history browsing much easier on the eyes.

The right way to query history: Avoid bluntly telling the assistant to “dump all details.” The official recommendation is a three-tier approach: first use search to grab indices (one line per entry, costing dozens of tokens), inspect the timeline to narrow down items of interest, and finally fetch the full text via get_observations by ID. Filtering before fetching reportedly cuts token usage by around 10x (pending verification).

For more ideas on agent debugging workflows, check out our deep dive: Hermes Agent In-Depth Configuration Guide. The memory layer and gateway layer are two different dimensions to tinker with.

FAQ

I installed it, but I don’t see any memories in a new session?

A: First, confirm the worker is running (check if the web dashboard opens), then check if data is growing in the ~/.claude-mem/ directory. Failing to register hooks correctly is the most common culprit—re-run npx claude-mem install or reinstall via the plugin marketplace.

The worker fails to start?

A: Follow the official troubleshooting sequence: verify Bun is installed (bun --version) -> check worker logs -> restart the worker. If the port is occupied, change it via CLAUDE_MEM_WORKER_PORT and relaunch.

Vector search throws errors / Chroma fails to start?

A: Don’t panic. It automatically falls back to pure SQLite FTS5 full-text search. Core functionality remains intact, though semantic recall is slightly reduced. To fix it, ensure uv/Python are operating correctly and restart the worker.

Getting a “Database is locked” error?

A: Most likely a leftover process is holding onto the database. Stop the worker, clear any stale processes, and restart.

On Windows, getting an error that npm is not recognized as an internal command?

A: Node.js isn’t installed or hasn’t been added to your system PATH. Install the latest Node.js package, and crucially, restart your terminal before trying again. Windows users trip over this step the most.

Three Cold Truths to Keep in Mind

Token savings claims are unverified. Numbers like “saves 75% tokens” or “10x reduction” stem from official and community estimates, and we haven’t benchmarked them locally at scale yet. Injecting memory also consumes tokens; installing this for short, one-off tasks purely adds overhead.
Compression is lossy. A summary might remember that you “fixed a login bug,” but it might forget the exact line of critical diff. Important agreements still belong in your CLAUDE.md. Don’t rely on the memory layer as a single source of truth; occasionally audit the dashboard to see what it’s actually logging.
It records your tool interactions. Although data is stored locally by default and features <private> tags and sanitization options, think twice before pointing it at sensitive codebases to figure out what shouldn’t enter the memory store. Don’t run it raw without checking.

Also worth noting: This project iterates at breakneck speed (over 350 versions released, with database schemas actively evolving). Scan the release notes before upgrading, and avoid blindly overwriting across major version bumps.

Who Is This For / Who Is It Not For?

Ideal for: Developers tackling multi-day projects with Claude Code or Codex daily; those running multiple agent tools who want to share a single stream of project memory; and anyone tired of re-explaining context at the start of every session.

Not ideal for: Casual users who only ask a random question once in a blue moon; anyone uncomfortable with the idea of a tool logging their background actions; and those expecting 100% precise historical recall out of the box—remember, it stores summaries, not CCTV footage.

The Bottom Line

Coding agents rarely lack raw intelligence; what they lack is memory. claude-mem automates note-taking, summarization, and on-demand retrieval using local SQLite and vector indices. Your data stays on your machine, and Chinese language mode works right out of the box. If you are already a heavy agent user, this is easily the most worthwhile memory layer to test drive. Light users can bookmark it and install it once their projects start getting lengthy.