claude-mem, agent memory that survives closing the terminal

A coding assistant starts every session from nothing. It does not remember why you rejected an approach yesterday, what the internal convention in this repository is called, or what you spent an hour searching for. claude-mem records the work, compresses it with a model, and serves the relevant parts back on the next run.

The problem it solves

Conversation context with an agent disappears when the session closes. In practice that means three things that cost time daily.

You repeat the introduction. Every morning you explain again that the project uses a particular package manager, that tests run with one command, and that payments live in a separate service.

You repeat mistakes. The agent proposes an approach you abandoned yesterday after half an hour of attempts, because no trace of that decision survives.

You lose conclusions. Findings from a long debugging session stay in the terminal window and vanish with it, even though they were the most valuable output of the work.

A project instructions file solves part of the first problem, since it describes durable state. It solves neither of the others, because nobody appends conclusions to it after every session.

How it works

The mechanism has three stages, and understanding them matters, because they decide whether the tool helps or gets in the way.

Session recording covers what the agent did: files read, commands run, changes applied, decisions made. The raw record is too large to feed back wholesale.

Model compression turns that record into concise notes. This is the pivotal step, since it decides what survives. The output is not a transcript but a set of statements worth remembering.

Context injection serves, at the start of the next session, whichever notes look related to the current work. The agent therefore starts from a state of knowledge rather than a blank page.

Compression carries one more consequence that is easy to forget: a model decides what matters. The session record passes through somebody else's judgement rather than a filter you set yourself. In practice that means some things obvious to you may not survive, while some trivia will. So it pays to read the notes occasionally instead of assuming they mirror the work faithfully.

That last stage determines how the tool feels. Matching too broadly clogs the context with irrelevant notes and raises the cost of every call. Matching too narrowly makes the tool seem not to work at all.

Installation

The plugin installs from inside a session, through the built in extension catalogue.

Code

TEXT

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

After a restart, context from earlier sessions appears automatically. You start nothing by hand, though it helps to know the plugin keeps a local worker service running on Bun in the background. That worker processes the session record and exposes a local API together with a browser view of the notes, and when the tool behaves oddly its state is where diagnosis begins. The notes themselves land in a SQLite database under ~/.claude-mem.

The project develops across three branches: stable, development, and community. Only the stable one reaches the package registry, so the other two run from source. With a tool of this kind, staying on stable is wise, because agent memory fails in ways that are hard to notice.

Update the plugin deliberately rather than automatically. A change in the compression layer can change what reaches the notes, and you will only see the effect several sessions later.

Code

Bash

/plugin list
/plugin update claude-mem

Copy the notes directory before updating. Reconstructing them from session history is not possible, so the file on disk is all you have.

The tool is not tied to one assistant. It supports several agent environments, so notes gathered in one are available in the next, as long as you work on the same project.

How it changes daily work

The biggest difference shows in work spread across days. A session after a weekend starts from a reminder of where things stood, rather than from reconstructing state out of git history.

The second difference concerns negative decisions. Knowing what not to do and why is usually more valuable than a description of the solution, because the solution is visible in the code while rejected variants leave no trace. A recorded note that a library did not work with your runtime version saves half a day on the next attempt.

The third concerns handover. Somebody joining the project receives, alongside the repository, a set of notes from earlier sessions, which is often more legible than commit messages.

Set expectations. This replaces neither documentation nor a project conventions file. It is a supplementary layer collecting what happens during work anyway and what nobody writes down by hand.

Privacy and security

The tool records session activity, so you need to know exactly what lands in the notes and where those notes live.

By default data stays local, while recent versions add synchronisation with the vendor's cloud service. That is precisely the point to pause: with a client repository or data under a confidentiality agreement, synchronising off your own machine deserves a deliberate decision rather than a default setting.

The second matter is secrets. A session where the agent read an environment variables file can leave that fragment in the notes. Before rolling the tool out across a team, check what enters the record and exclude configuration directories. The tool offers an explicit escape hatch here: content wrapped in a <private> tag stays visible to the model in the current session but is never stored as an observation. That is the simplest way to paste a production log dump without leaving it in memory for good.

Code

Bash

sqlite3 ~/.claude-mem/claude-mem.db .dump 2>/dev/null \
  | grep -nE "(sk|pk)_(live|test)_[A-Za-z0-9]{10,}|PRIVATE KEY|AKIA[0-9A-Z]{16}" | head

Run that once after a week of use, before anybody enables synchronisation. If anything turns up, the key itself has to be rotated rather than the notes merely cleaned: a value that once entered the record may already have travelled onward.

Check separately what happens on deletion. If notes synchronise, deleting them locally need not mean the copy on the other side is gone, and with a personal data deletion request that difference is legal rather than technical.

The third is housekeeping. Notes accumulate, and old ones can mislead, since they describe code as it stood before a refactor. A quarterly review with stale entries removed is a cheap task that keeps suggestion quality up.

What is worth remembering and what is noise

The quality of this tool reduces to the quality of its notes, and those depend on what happens in a session at all. A few habits improve the result markedly.

Name decisions explicitly. A conclusion arrived at silently through a series of commands does not survive compression, because there is nothing to summarise.

Code

TEXT

Weak:   change the queue to a database table

Better: we are staying with a database queue rather than a broker, since
        at a hundred jobs a day a broker is another service to maintain
        with no gain. We revisit this once we pass a thousand a day.

The second form carries the reason and the condition for revisiting the decision, so a month later the note still means something. The first leaves a fact with no context, and that is exactly the kind of entry that misleads in a later session.

Close sessions with a summary. Two sentences on what was done and what comes next give the model material to record. A session cut off midway leaves notes describing a transient state that misleads on the next run.

Keep projects separate. Working on two repositories in one session mixes contexts, and the notes injected later partly concern the wrong project.

Do not count on it remembering what the code already shows. Directory structure, function names, and dependencies are visible to the agent without memory. What is valuable is what the code does not show: reasons, rejected variants, external constraints.

It also helps to know that agent skills, described in agent-skills, cover part of this role. A skill holds instructions for handling a kind of task, memory holds the history of a specific project. Together they close two different gaps and do not substitute for one another.

Rolling it out across a team

Installing it for one person takes a minute, rolling it out to ten needs three agreements best not deferred.

The first concerns data scope. Decide whether notes stay local or synchronise, and whether that applies to every repository or only internal ones. On client projects this usually ends with synchronisation disabled for selected directories.

The second concerns sharing. One person's notes can be valuable to the rest of the team, but they also carry their way of working and their dead ends. A sensible starting point is individual memory, with conclusions worth sharing moved deliberately into a repository file.

The third concerns review. Pick a moment when somebody goes through the notes and removes stale ones, at the close of a larger phase for instance. Without that, a quarter later half the entries describe code from before a refactor.

For larger agent configurations, keeping the whole setup in the repository pays off, much as people do with templates from claude-code-templates. Somebody joining then receives the complete set along with the project instead of configuring an environment from scratch.

claude-mem against the alternatives

Approach	What it gives	Limitation	Pick it when
claude-mem	Automatic recording and context delivery with no effort from you	Notes need review, and a privacy layer arrives with them	Continuous work on one project across weeks
Project instructions file	Full control over content, versioned in the repository	You update it by hand, so it goes stale quickly	Conventions and durable state that changes rarely
Your own notes in the repository	Legible to humans and to the agent, no dependencies	Requires discipline that usually runs short	Small team with a documentation habit
Memory built into the tool	Nothing to install	Scope depends on the vendor, less control	Simple case with no data requirements

These approaches do not exclude each other. What works best is durable state in a repository file, with the automatic layer collecting what emerges during work.

When agent memory actually pays off

Not every way of working gains from this layer, and installing it just in case ends up adding cost with no visible return.

Continuous work on one project across weeks gains, especially when sessions are short and spread out. There the cost of reconstructing state at every start is real and repeated, so removing it shows immediately.

Debugging work gains too. Hunting a fault that appears once every few days stretches across many sessions, and the conclusions from each are worth more than whatever code came out along the way.

Task shaped work does not gain: a single fix, generating a component, a one off file migration. There a session begins and ends in the same context, so memory has nothing to carry.

Alternating across many unrelated repositories does not gain either. Notes from one project served in another are noise that occupies context and costs on every start.

A simple test before rolling it out: count how many minutes a day go into bringing the assistant up to speed on the project. If it is a few minutes across two sessions, the tool pays for itself. If it is seconds, because you work in one long window, the benefit will be hard to notice.

Common mistakes

The first is treating the tool as documentation. Notes record what happened rather than describing how the system should behave. Keep conventions and architecture in the repository.

The second is enabling synchronisation without checking what gets synchronised. On a client project that is a decision to agree on, not a setting to accept in passing.

The third is never reviewing the notes. After a few months some describe code that no longer exists, and the agent treats them as current.

The fourth is installing a development branch on a working machine. A fault in the memory layer surfaces as odd assistant behaviour rather than an error message, so diagnosis takes disproportionately long.

FAQ

Is claude-mem free?

The code is open and available in the repository, and the plugin installs at no charge. Cost arrives indirectly: compressing a session record means model calls, so your provider bill grows with session count. Optional synchronisation with the vendor cloud may be billed separately.

Does data leave my machine?

The default mode is local, while newer versions offer synchronisation with a cloud service. Before deploying on a project under confidentiality, check which option is active and decide deliberately.

Does it replace a project instructions file?

No. That file describes durable state: conventions, commands, architecture. claude-mem collects the flow of work and conclusions from sessions. The two layers complement each other, and replacing one with the other produces a worse result than using both.

Does it work with assistants other than Claude?

Yes, the tool supports several agent environments, so notes gathered in one appear in another when working on the same project. That sets it apart from memory built into a specific tool, Cursor for instance.

Does it slow a session down?

Recording and compression happen in the background, so work does not stall on that step. What can be noticeable is the size of the injected context: too many notes at startup lengthen the first response and raise cost, which is why limiting scope to the current project pays off.

The source code and installation instructions sit in the GitHub repository, and the package in the npm registry.