---
title: "How Does Claude-Mem Add Persistent Memory to Claude Code?"
url: "https://goremy.ai/blog/articles/claude-mem-persistent-memory-claude-code"
author: Luis Chavez-Mattos
editor: Luis Chavez-Mattos
editor_title: Director, Product
published: "2026-11-10T17:20:07.906Z"
updated: "2026-11-10T17:20:09.732Z"
topic: AI Coding Tools
description: Claude-Mem gives Claude Code memory across sessions. Learn how the hooks work, how to install it, and which privacy settings to change first.
---

# How Does Claude-Mem Add Persistent Memory to Claude Code?

> Claude-Mem gives Claude Code memory across sessions. Learn how the hooks work, how to install it, and which privacy settings to change first.

Edited by Luis Chavez-Mattos, Director, Product · Published 2026-11-10

## How does Claude-Mem give Claude Code memory between sessions?

Claude-Mem is an open-source memory system for coding agents. It hooks into Claude Code's lifecycle events, records what the agent does, and has a background model compress those events into short notes called observations. A local worker stores them in SQLite with a Chroma vector index. At the start of the next session, it injects a compact index of recent observations, and the agent fetches details only when it needs them.

## TL;DR

- Claude-Mem runs in the background through **Claude Code lifecycle hooks**, so you don't call any commands to save or recall memory.
- Memory is stored locally in **SQLite plus a Chroma vector database**, written by a background observer model (Haiku on the Claude provider).
- **Progressive disclosure** injects an index of the last 50 observations by default, with token costs listed, then lets the agent search and fetch only what it needs.
- Install with **`npx claude-mem install`**, not `npm install -g`, because the global install skips the hooks and the worker.
- Early versions of the browser setup uploaded prompt history without asking. Run **version 15.8.3 or later**, decline uploads, and disable telemetry.
- It earns its place on **long-running projects**. For small one-off tasks, a good CLAUDE.md file covers most of the need for free.

## Why does Claude Code forget everything between sessions?

Each Claude Code session starts with a fresh context. Close the terminal and the reasoning behind yesterday's decisions is gone. You re-explain, the agent re-reads the same files, and you pay for those tokens again.

Claude-Mem targets that gap. The project has passed 112,000 GitHub stars and is licensed under Apache 2. Version 15.9 was the current release when this was written. That scale matters mostly as a signal that people are testing it on real work.

## How does Claude-Mem work under the hood?

There are two halves: writing memory and reading it.

### The writing side

Claude-Mem registers hooks for these Claude Code events:

- Session start
- Prompt submission
- Before and after every tool call
- Claude stopping
- Session end

Each time Claude reads a file, edits code, or runs a command, the event goes to a small worker service running on your machine. The worker passes events to an observer, which is another model running in the background. On the Claude provider, that observer is Haiku.

The observer turns raw tool calls into observations. Each one has:

- A title
- A type, such as bug fix or decision
- A short narrative
- A set of facts
- The files involved

Observations go into a local SQLite database, with a Chroma vector database alongside for search by meaning. When a session ends, you also get a summary covering what you asked for, what was investigated, what was learned, and next steps.

### The reading side

Dumping all history into context wastes tokens on irrelevant material. Claude-Mem uses progressive disclosure instead.

1. At session start, it injects an index of recent observations. The default is the last 50. The index holds only titles, types, and the token cost of reading each one.
2. The agent decides what looks relevant.
3. If it needs more, it uses three search tools. The first, search, returns a compact list of IDs at roughly 50 to 100 tokens per result. The agent then fetches full observations only for the IDs it picked.

The project claims around 10x token savings from filtering before fetching. Treat that as a ceiling. The project's own site says the effect on token use depends on your workload and provider.

## How do you install Claude-Mem?

Run the installer with npx:

```
npx claude-mem install
```

Do not use `npm install -g`. That only installs the library. It does not set up the hooks or the worker.

The installer first sets up its runtime, including Bun and UV if you lack them. Then it asks you to sign in and pick a memory provider. A hosted provider is pre-selected, with a 30-day free trial. You can skip that. Passing the provider flag with `claude` skips sign-in, and memory runs on your own Anthropic plan:

```
npx claude-mem install --provider claude
```

Other options include your own OpenRouter or Gemini key, or any OpenAI-compatible endpoint.

## What does it look like in practice?

A creator demoed it on a small invoice API with a bug: due dates at month end showed up a day early for some customers. Claude found that the date was parsed as local time, switched it to UTC, and the tests passed.

Meanwhile, the worker's local web viewer showed the new observations: a bug fix entry with its facts and touched files, plus a session summary.

Then came the real test. In a fresh session, the injected index covered three observations and cost 425 tokens to read. Asked to add a reminder email three days before the due date, Claude reused the UTC helper without being told about the earlier bug. Asked why due date parsing had changed, it called search, picked the right ID, fetched that observation, and answered with the time zone explanation. It did not dig through the code.

The viewer also has a "My Work" page, now the default at the local URL. It turns your recorded requests into three groups: in progress, waiting on you, and done but unchecked. Marking something checked stays local. The old timeline remains under a classic viewer link.

## Which agents does Claude-Mem support?

Despite the name, it is not limited to Claude Code. An agent ID flag covers Codex, Cursor, OpenCode, Windsurf, Copilot, Kimi, Devin, Hermes, PI, DeepSeek Coder, and others. Version 15.9 added Devin.

Two other settings are worth knowing:

- Memories can be written in around 30 languages.
- A "chill" mode records fewer observations and keeps only what would be painful to rediscover.

## Is Claude-Mem safe to use? Which settings should you change first?

Mostly yes, with caveats. There is a real privacy history here.

In version 15.2, a browser setup step was added. Until a fix landed, it scanned local history from Claude Code, Codex, Gemini CLI, and others. It uploaded the full text of the last 30 days of prompts, plus project names, folder paths, and timestamps, as soon as the page loaded, without asking. A user reported it. According to that report, the hosted service confirmed the prompts went through OpenRouter without blocking providers that may retain or train on data. The privacy policy at the time said nothing leaves your device unless you enable Cloud Sync.

Version 15.8.3 fixed this. It now asks first and offers a clear "keep everything local" option. The release notes say prompts already uploaded are not removed by updating, so anyone who used the browser setup on an earlier version should know that.

A short settings checklist:

| Setting | Why |
|---|---|
| Version 15.8.3 or later | Includes the upload consent fix |
| Provider flag set to `claude` (or your own key) | Avoids the hosted sign-in |
| Decline any upload prompt | Keeps history local |
| Disable telemetry | It is anonymous and documented, but opt-out. Use `npx claude-mem telemetry disable` or set the do-not-track variable |
| Turn on auto-redaction | 30 built-in patterns for things like API keys. It is opt-in, not default |

You can also wrap sensitive text in private tags. Claude can use it during the session, but it is not stored.

## How much does Claude-Mem cost?

The engine is free and open source. The observer is still a model doing work, though. On the Claude provider, memory draws from the same plan usage you already have, so it can eat into limits you may be hitting. One open issue reported a user on the Claude provider seeing around 230 hidden Codex runs in four days from the My Work refresh, which used up their Codex quota.

The hosted option costs $30 a month after the trial. Heavier tiers are $70 and $100.

One more default to know about: a file read gate. It can block Claude from reading a large file that already has history and send it an outline instead. That usually saves tokens. If Claude behaves oddly around big files, check it first.

## Is Claude-Mem worth it?

It depends on your work pattern. If you stay on one project for weeks and keep restating the same decisions, the index-then-fetch design is a sound answer. If you mostly do small, isolated tasks, a well-kept CLAUDE.md gives you most of the benefit with no background model and no extra usage.

## Frequently Asked Questions

### Do I need to run any commands to save or recall memory?

No. Once installed, the hooks capture events automatically and the index is injected at session start. The agent calls the search tools itself when it needs more detail.

### Where is my memory stored?

Locally, in a SQLite database with a Chroma vector database for semantic search. Hosted providers and cloud sync are optional, and you can choose to keep everything local.

### Why shouldn't I use `npm install -g claude-mem`?

A global npm install only adds the library. It doesn't register the lifecycle hooks or start the worker service, so nothing gets recorded. Use `npx claude-mem install`.

### Will Claude-Mem use up my Claude usage limits?

It can. On the Claude provider, the background observer shares your plan's usage. If that is a concern, use your own OpenRouter or Gemini key, or an OpenAI-compatible endpoint, and consider chill mode to record fewer observations.