Claude‑mem: Persistent Memory for Claude Code – Architecture, Token Savings, Quick Install

Conclusion: What It Is

claude-mem is a plugin‑style persistent‑memory compression system for Claude Code. According to the official README it automatically captures Claude’s actions during a coding session via the Claude Agent SDK, compresses them into reusable observations and semantic summaries, and injects the relevant information back into later sessions so the model need not repeat explanations.

It can be thought of as a searchable engineering notebook that is written, organized and retrieved by the machine.

We Don’t Lack Model Ability, We Lack “Glue” Between Sessions

Engineers accept a division of labor: models excel at reasoning and generation, humans at goals and aesthetics. The hidden cost is “context‑transfer cost”. Repeating constraints, environment‑variable notes, or previous debugging steps consumes attention and tokens.

claude‑mem’s entry point is simple: automatically move high‑probability‑re‑used information into structured memory instead of leaving it scattered in the chat scroll.

How claude‑mem Works: From Capture to Injection

From an architectural view the memory pipeline is:

Hook capture → Worker service processing & API → SQLite persistence → (combined with vector retrieval) hybrid search → Context injection at the right moment.

The main flow diagram (omitted) shows the primary path.

Lifecycle hooks : turn “when to remember” from a manual habit into a system mechanism.

Worker service : expose the memory as a tool‑able service rather than a chat by‑product.

SQLite + vector retrieval : provides reliable engineering storage while leaving a semantic‑search path.

Progressive Retrieval: A Three‑Stage Token‑Saving Rhythm

RAG‑style naïve feeding of a large context is noisy and costly. claude‑mem adopts a three‑stage rhythm: search → timeline → get_observations. First it obtains a compact index and IDs, then expands the surrounding timeline, and finally pulls full observations only for the selected IDs. The README claims this can reduce token usage by roughly an order of magnitude, depending on data distribution.

This design treats retrieval as a cost‑sensitive engineering problem: every extra character read must yield deterministic information gain.

Installation and Getting Started

For most users a single command installs the plugin, registers hooks and starts the worker: npx claude-mem install Alternatively, via Claude Code’s plugin marketplace:

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

Important caveat from the README: installing only the SDK with npm install -g claude-mem does not register hooks or the worker. Use the one‑command install or the /plugin flow.

After installation restart Claude Code; the next session will automatically surface relevant context from previous sessions.

Runtime requirements include Node.js ≥ 18, a recent Claude Code version that supports plugins, and optional dependencies Bun and uv for vector retrieval. Windows users must ensure npm is on the PATH.

Beyond Claude Code: Compatibility

claude‑mem is primarily built for Claude Code but also supports other CLI‑based AI tools such as Gemini CLI, OpenCode, and integration via the OpenClaw Gateway.

Privacy, Configuration and Collaboration Boundaries

Any memory product must answer “what to remember” and “what not to remember”. claude‑mem lets users wrap sensitive sections in special tags (as documented) to exclude them from storage. Settings live in ~/.claude-mem/settings.json and control model, worker port, data directory, log level, and language mode (e.g., CLAUDE_MEM_MODE=code--zh).

A local Web Viewer at http://localhost:37777 visualizes stored memories and retrieval hits, acting like an “oscilloscope” for the memory system.

Open‑Source License and Contribution

The project is released under the GNU Affero General Public License v3.0, allowing free use, modification and distribution while requiring derived network services to share source code.

Contributors can fork the repository, create a branch, add tests, update docs, and submit a Pull Request. Issues can be opened on GitHub for complex problems.

Final Thoughts

claude‑mem’s popularity (≈71 k Stars) stems from solving a real engineering pain: repetitive “context‑carrying” work that is low‑dignity but high‑frequency. Automating this transforms process artifacts into searchable assets, freeing developers from being “context movers”.