claude-mem persistent agent memory: install and monitor

claude-mem persistent agent memory: install per the README, session compression, context re-injection, token cost and worker health.
claude-mem mémoire persistante agents : installer et superviser

claude-mem persistent agent memory: the thedotmack/claude-mem repository describes itself as a “persistent memory compression system” built for Claude Code. It watches what the agent does during a session, summarises it, then re-injects the essentials when the next session starts. The repository showed about 103,000 stars and 9,100 forks at the end of October 2026, under the Apache 2.0 licence, with version 15.2.1 shown in the README.

For an operations team, it is a small service running next to the agent. It listens to every tool call, calls a language model to summarise it, stores the result and changes the context of every new session. Latency, token cost, the quality of what is recalled and privacy therefore become operational topics. This article follows the repository README and documentation, read on 26 October 2026.

A note on honesty: span.observer has not installed claude-mem. The commands come from the README, the settings from the official documentation, and the interface capture from the project’s own repository. For another approach to agent memory, see Hindsight, AI agent memory: the angle differs, as explained below.

claude-mem persistent agent memory: what the repository says

  • Author and licence: the README names Alex Newman (@thedotmack) as author. The LICENSE file is the standard Apache License 2.0 text, and the README confirms it. The files docs/license.md and docs/ip-boundary.md describe an “open-core” structure: the memory engine, server, CLI, adapters and MCP tools are Apache 2.0, while a hosted cloud, team sync, admin and SSO stay reserved outside the public repository.
  • Technology: TypeScript, Node.js 20 or later, Bun as process manager, SQLite with FTS5 full-text search, and optionally the Chroma vector database (installed through uv).
  • Principle: Claude Code lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) pass events to a local worker. The worker asks a model to compress them into structured “observations”.
  • Figures read on 26 October 2026: about 103,000 stars and 9,100 forks from the repository page; version 15.2.1 from the README badge and the npm package. The stars were read by a page-summarising tool: re-check them before quoting them elsewhere.

The README also lists installers for environments other than Claude Code (OpenCode, T3 Code, Antigravity, OMP, Pi, OpenClaw). This article sticks to Claude Code, the original case.

Interface tour: the web viewer

The worker serves a web interface, the “viewer”, that shows the stored observations live. The capture below is a frame from the cm-preview.gif animation published in the project repository: a Claude Code session on the left, the viewer on the right.

Frame from the claude-mem repository animation: a terminal with a Claude Code session and worker logs on the left, the claude-mem web viewer with observation cards sorted by type, Change and Feature, on the right
Source : github.com

Each card carries a type (for example change or feature), a title, a short narrative and an identifier. According to the documentation, the viewer updates through Server-Sent Events and filters by project. Context settings can also be edited there, with a live preview.

How memory is compressed, then re-injected

The flow described in the architecture documentation fits in one line: a hook writes to the database, the worker reads and processes the entries with the agent SDK, then the next session’s hook reads the summaries back. In practice:

  1. Capture: after each tool call (PostToolUse), the hook sends the event to the worker. The documentation speaks of “100+ times” per session.
  2. Compression: the worker hands each event to a model. By default CLAUDE_MEM_MODEL is claude-haiku-4-5-20251001 with the claude provider; other providers are listed: codex, gemini, openrouter, openai-compatible.
  3. Summary: when the agent stops (Stop), a final summary records the request, what was done and what was learned.
  4. Re-injection: at the next start, the context hook adds the latest observations. The default is 50 (CLAUDE_MEM_CONTEXT_OBSERVATIONS).
Excerpt from the claude-mem documentation: settings.json file with the context keys CLAUDE_MEM_CONTEXT_OBSERVATIONS, SESSION_COUNT, OBSERVATION_TYPES, FULL_COUNT and the display options for tokens read and saved
Source : docs.claude-mem.ai

The capture shows the manual configuration example from the documentation: one hundred observations, twenty sessions, filtering by type (bugfix, decision, discovery) and display of the read-token cost. These are not the defaults.

The project defends “progressive disclosure”: show a cheap index first, then fetch detail only when needed. The README describes three MCP tools: search (compact index), timeline (chronological context) and get_observations (details for filtered identifiers). The project claims a saving of about ten times in tokens; that is a README claim, not a measurement reproduced here.

Excerpt from the claude-mem README: three-step example with search to get an index, then get_observations with identifiers 123 and 456 to fetch the detail
Source : github.com

Step-by-step installation

Prerequisites

The README asks for Node.js 20 or later, a recent Claude Code with plugin support, Bun and uv (installed automatically if missing) and SQLite 3 (bundled).

Step 1 — Run the installer

npx claude-mem install

The README states that npm install -g claude-mem installs only the SDK, without registering the hooks or the worker. After installation, the tool offers an e-mail sign-in to a claude-mem account with a 30-day free trial of the hosted “observer”. To avoid it, the README suggests passing an explicit --provider flag, setting CLAUDE_MEM_ONLINE_OPTIN=false or working in a non-interactive shell.

Step 2 — Or use the plugin marketplace

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

Restart Claude Code: the README says context from earlier sessions then appears automatically in new ones.

Step 3 — Windows

The hooks do not need Git Bash. The installer puts a claude-mem.exe launcher in %LOCALAPPDATA%\claude-mem\bin and adds it to the user Path; restart the terminal afterwards. On an “Executable not found in $PATH: “claude-mem”” error, the README points to npx claude-mem doctor.

How to check it works

  • Run npx claude-mem doctor: the documentation says it shows a row for the hook launcher.
  • Start a Claude Code session, do a few things, then open the viewer at the address the worker prints at start-up. Observation cards should appear.
  • Query the worker: curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health, the command given by the configuration documentation to read the active port.

Monitoring claude-mem in operation

The documentation describes neither OpenTelemetry export nor Prometheus metrics. What it does let you follow:

  • Worker health: a local HTTP service, default port 37700 + (uid % 100), changeable with CLAUDE_MEM_WORKER_PORT. The “Worker Service” page cites GET /health, the configuration page GET /api/health: check which one answers on your version.
  • Queue: GET /api/pending-queue shows pending, processing, processed and failed messages (three attempts by default) and the number of “stuck” messages (more than five minutes in processing). POST /api/pending-queue/process restarts processing. It is the right indicator after a crash.
  • Logs: the logs/ folder of the data directory (~/.claude-mem by default, CLAUDE_MEM_DATA_DIR), with the level set by CLAUDE_MEM_LOG_LEVEL (DEBUG, INFO, WARN, ERROR, SILENT). The documentation pages name the files differently (worker-out.log on one, worker-YYYY-MM-DD.log on another).
  • Stored volume: GET /api/stats (counts per project) and the claude-mem.db file let you follow growth.
  • Cost: every observation goes through a model. Token tracking happens on the provider side; the method in the token cost of an AI agent with OpenTelemetry applies, as does observing MCP agents with OpenTelemetry for the search tool calls.

The worker listens on 127.0.0.1 by default (CLAUDE_MEM_WORKER_HOST). The documentation recommends keeping it that way for anyone not using remote access. For the general framework for monitoring a coding agent, see monitoring a coding agent in the enterprise.

How claude-mem differs from Hindsight

The article on Hindsight describes a memory server to deploy with PostgreSQL, called by any agent through an API and retain, recall and reflect operations. claude-mem starts elsewhere: it hooks into Claude Code, needs no agent-side code, stores everything locally in SQLite and re-injects an index at the start of every session. The first is a memory building block for building an agent; the second is an add-on for an existing coding agent.

Limits and open points

  • Sensitive data: any tool call may be captured, including paths, commands and file excerpts. The README describes <private> tags to exclude content, and the documentation covers filters (CLAUDE_MEM_SKIP_TOOLS, CLAUDE_MEM_SKIP_BASH_PATTERNS, excluded projects). They only protect what you thought to exclude.
  • Commercial offer up front: the README highlights an account sign-in, a 30-day free trial and hosted memory by default for one of the installers. The project claims up to 100% more usage on your plan: that is a commercial argument, not verified here. A local install remains possible.
  • Community token: the end of the README mentions CMEM, a token created by a third party but “officially embraced” by the author. span.observer neither recommends nor comments on it; it is a caution signal for anyone evaluating the project.
  • Open-core frame: some announced features (team, SSO, cloud) are reserved outside the Apache 2.0 repository, according to docs/ip-boundary.md.
  • Uneven documentation: the same information (worker health, log file names) differs from one page to another, and the README describes installation for Grok Bot first, then Claude Code. The “10 times fewer tokens” figure and the skill’s “100% effectiveness” are project claims.
  • Very active project: version 15.2.1, more than 3,600 commits according to the repository page; options change quickly.

Best practices

  • Try it first on a project without secrets, with CLAUDE_MEM_CONTEXT_OBSERVATIONS set low.
  • Add your sensitive patterns to CLAUDE_MEM_SKIP_BASH_PATTERNS before real use and keep the worker on 127.0.0.1.
  • Choose the compression provider explicitly, with the cheapest model that works, and track consumption on its side.
  • Back up the data folder before an update, and watch the queue after a restart.
  • Review what is stored: a wrong observation is re-injected into every session.

Frequently asked questions

Is claude-mem free and open source?

The repository code is Apache 2.0 according to the LICENSE file. The README also offers a hosted service with a 30-day free trial; by its own account it is optional.

Does my data leave my machine?

Observations are stored in a local SQLite database. But the summary goes through a model: Claude by default, or Gemini, OpenRouter or another provider according to CLAUDE_MEM_PROVIDER. The content of tool calls is therefore sent to that provider. Cloud sync is a separate service described by the project.

How is it different from a CLAUDE.md file?

An instructions file is written by hand and read in full each session. claude-mem generates entries automatically and injects only a bounded index, detailed on request afterwards. The two complement each other.

Conclusion

claude-mem automates a task teams do by hand: telling the agent what happened yesterday. It installs with one command and is tuned through a JSON file. Treat it as a service: watch its queue, count its tokens, limit what it remembers. Sources: thedotmack/claude-mem repository and the official documentation.

span.observer is an independent community blog, not affiliated with Dynatrace LLC or the projects mentioned. Trademarks belong to their owners. Tools change quickly: check commands and options in their official documentation.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
SkillSpector scanner sécurité skills : installer et lire

SkillSpector agent skills security scanner: install and read

Next Post
Caveman réduire tokens : superviser le coût d'un agent IA

Caveman reduce tokens: supervising the cost of an AI agent

Related Posts