How to Use claude-mem | Adding Persistent Memory to Claude Code

What Is claude-mem? How Cross-Session Memory Works

claude-mem is an open-source memory plugin that automatically captures and compresses Claude Code session content, then injects it as context into future sessions. It was created by developer thedotmack, and the GitHub repository has grown into a popular project with over 80,000 stars. It is licensed under Apache 2.0, so commercial use is permitted.

The problem it solves is straightforward. Claude Code is excellent within a single session, but the moment you close that session, it forgets everything. Project structure, recent decisions, bugs you were tracking — all of it needs to be re-explained the next day. With claude-mem installed, a summary of "what was done" is automatically written to local storage when a session ends, and that memory is automatically loaded at the start of the next session.

Note that despite the similar name, this is a separate tool from the "memory feature" built into the Claude chat app. The differences are explained later.

How It Works | 5 Hooks, SQLite, and Vector Search

claude-mem consists of automated processes tied to Claude Code's lifecycle. According to the official documentation, processing occurs at five moments: SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd.

The data flow works as follows:

1. Tool executions during a session (file edits, command runs, etc.) are observed and recorded in the background
2. At session end, the raw logs are compressed by AI into short, typed summaries such as "bug fix," "discovery," and "decision"
3. The summaries are stored in a local SQLite database and indexed for both full-text search (FTS5) and vector search (Chroma)
4. At the start of the next session, only the most relevant memories are selected and injected into the context

The key point is that it does not load everything. A three-tier retrieval approach (index search → timeline → detail fetch) progressively pulls only relevant memories, consuming very little of your valuable context window. All memories are stored on your local machine and never sent to external servers — an important reassurance for many users.

Installation | Done in One npx Command

Setup is extremely simple. The requirements are Node.js 20.0.0 or later and an up-to-date version of Claude Code. Runtimes used internally, such as Bun, are installed automatically.

1. Run npx claude-mem install in your terminal
2. Restart Claude Code
3. Confirm that a summary of previous work appears automatically at the start of a new session

You can also install it through the Claude Code plugin marketplace:

1. Run /plugin marketplace add thedotmack/claude-mem inside Claude Code
2. Run /plugin install claude-mem
3. Restart Claude Code

After that, no further action is needed — memory is saved and loaded automatically with every session. "Install it, then just use it as usual" is the design philosophy behind claude-mem.

Source: Claude-Mem Official Documentation Introduction

Retrieving Memories | mem-search and the Web Viewer

Stored memories can be actively searched, not just automatically injected.

The primary tool for this is mem-search. You can ask in natural language — for example, "What was that authentication refactoring I did last week?" — and it will search through past session observation records to find the relevant parts. Search uses a hybrid of keyword matching and semantic search, so you can get results even if you do not remember the exact filename.

In addition, a locally running worker service provides a web viewer at http://localhost:37777, letting you browse all stored memories in real time from your browser. This is handy when you want to visually confirm what has been recorded.

Privacy Settings | Exclude Content with the <private> Tag

One concern for business use is whether "everything gets recorded." claude-mem includes a mechanism to handle this.

Any content wrapped in <private> tags within a prompt is excluded from memory storage. This is useful when you need to use information like API keys or customer data within a session but do not want it recorded. Combined with the fact that all recordings are stored entirely in local SQLite, this makes claude-mem a straightforward choice even for teams that do not want their data on remote servers.

How It Differs from Claude's Built-in Memory Feature

The official Claude chat app from Anthropic also includes a standard "memory feature" that automatically summarizes conversations and retains context across sessions. Since the two are easy to confuse, here is a quick comparison:

In short: use Claude's built-in memory feature if you want the chat version of Claude to remember your preferences, and use claude-mem if you want Claude Code to remember your development context. For details on how to configure or disable the built-in memory feature, see How to Turn Off Claude's Memory.

Things to Know Before Installing

While very convenient, there are a few things to be aware of:

1. It is an unofficial plugin: Because this is not an Anthropic official tool, updates to Claude Code itself could temporarily affect how it works. It is updated at a high frequency — over 280 releases — and stays current, but if you plan to rely on it for critical workflows, make a habit of checking the release notes
2. A background service runs persistently: A worker service runs as an HTTP API around port 37777. If port conflicts or resource usage are a concern in your environment, check this in advance
3. Memory quality depends on how you use it: If you run scattered, unfocused sessions, the summaries will be scattered too. Keeping to one topic per session helps build memories that are easier to search later
4. It works with environments other than Claude Code: It supports other development environments such as Gemini CLI and OpenCode. You can specify the target with a flag like npx claude-mem install --ide gemini-cli

Summary | The Fastest Way to Stop Explaining from Scratch Every Time

claude-mem is a plugin that solves Claude Code's biggest weakness — losing memory between sessions — with a single install command. The mechanism is simple: automatic summarization of session content, local SQLite storage, and automatic injection of relevant memories. It lets you carry over past context while keeping context window consumption low.

Over 80,000 GitHub stars is a testament to how many developers have shared this frustration. If you want to experience a Claude Code that picks up where you left off yesterday, start with npx claude-mem install.

References:

• thedotmack/claude-mem (GitHub)
• Claude-Mem Official Documentation