claude-mem: Persistent Context for Coding Agents, With a Token-Cost Trade-Off

What claude-mem Actually Solves

Coding agents like Claude Code start each session with no memory of what happened before. You spend the first minutes re-explaining project structure, past decisions, and pending tasks. claude-mem attacks that problem directly. It captures everything the agent does during a session, compresses it with AI, and injects relevant context into future sessions. The target user is a developer who works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, or OpenCode and wants continuity without manually maintaining notes. The README states it is a "persistent memory compression system built for Claude Code," but the tool has expanded to other agents. The core value is automatic: no manual intervention required, which is a strong claim for a tool that runs as a background worker.

How the Capture-Compress-Inject Cycle Works

The mechanism is visible from the README, though the full pipeline lives in the docs. claude-mem automatically captures tool usage observations during a session. These observations are not raw logs; they are structured records of what tools the agent called and what happened. The system then generates semantic summaries using AI. Those summaries are stored and made available to future sessions. When a new session starts, the system injects relevant context based on the current conversation. The README calls this "progressive disclosure": layered memory retrieval with token cost visibility. That means not all memory is dumped at once. The system retrieves only what it deems relevant, and you can see how many tokens that retrieval costs. This design tries to balance context density against the finite context window of the agent. The web viewer UI shows a real-time memory stream at the worker URL printed on startup, which gives you a way to inspect what is being captured.

Installation: One Command, But Watch the NPM Trap

The README gives a single command for most users: npx claude-mem install. For OpenCode, add --ide opencode. For Antigravity CLI, use --ide antigravity. Claude Code users can also install from the plugin marketplace with /plugin marketplace add thedotmack/claude-mem followed by /plugin install claude-mem. OpenClaw gateways get a separate installer: curl -fsSL https://install.cmem.ai/openclaw.sh | bash. There is a clear warning in the README: npm install -g claude-mem installs only the SDK/library and does not register plugin hooks or set up the worker service. That is a real footgun. If you follow the wrong install path, you get a library that does nothing for you. The README emphasizes that you must use npx claude-mem install or the /plugin commands. After installation, you restart Claude Code and context from previous sessions appears automatically. The worker service is a persistent process, which means you need to manage it as part of your environment.

Search and Retrieval: Skill-Based Querying

Beyond automatic injection, claude-mem offers search tools. The README mentions a "mem-search skill" that lets you query project history with natural language. There is also a Claude Desktop skill for searching memory from Claude Desktop conversations. Citations are supported: you can reference past observations with IDs through the worker API or view them all in the web viewer. This turns memory from a passive context injector into an active knowledge base. You can ask questions about what the agent did weeks ago. The token cost visibility in progressive disclosure is a differentiator. Most context injection systems just cram everything in. claude-mem at least shows you the cost. The README does not specify how the skill is invoked or what the exact syntax is, so you would need the docs for that. But the existence of a dedicated search skill suggests the automatic injection is not always sufficient.

Privacy Controls and the <private> Tag

The README lists privacy control as a key feature: use <private> tags to exclude sensitive content from storage. That is a manual, tag-based approach. You must remember to wrap sensitive parts of your conversation or tool output in those tags. The system will not automatically detect secrets or personal data. This is a limitation worth noting. If you forget the tag, the content gets captured and compressed by AI. The README does not say whether the compression runs locally or calls an external AI service. That matters for organizations with strict data handling rules. The OpenClaw installer handles AI provider configuration, which implies an external provider is typical. For a tool that captures everything your agent does, the privacy story is thin. Tag-based exclusion is better than nothing, but it is not a security boundary. You should assume that anything not explicitly tagged may end up in memory.

Operational Costs: Worker Service and Compression

claude-mem is not a single command that runs and exits. It requires a worker service that runs continuously. The README mentions the worker startup and the worker URL printed on startup. That means you have a background process to monitor, restart, and potentially secure. The compression step uses AI, which means each session incurs token costs beyond what the agent itself uses. The README does not give pricing or performance numbers. The progressive disclosure feature exists to manage retrieval token cost, but the compression cost is ongoing and unavoidable. For a heavy user, this could add up. There is also the question of storage: where are the observations and summaries stored? The README does not specify. You would need to check the docs for storage backend and retention policies. The OpenClaw installer handles dependencies and worker startup, which suggests the setup is not trivial for self-managed environments.

Alternatives and the Trade-Off

The obvious alternative is to manage context manually: keep a project notes file and paste relevant details into each session. That costs time and discipline, but it costs zero tokens and has no privacy exposure. Another alternative is to use the built-in memory features of agents like Claude Code, which may have some context persistence. The difference is that claude-mem automates the capture and compression, and it works across multiple agents. The trade-off is that automation introduces a third-party service, a worker process, and AI costs. If you work on a project with strict privacy requirements or a tight budget, manual notes might be the better choice. If you switch between agents frequently, claude-mem's cross-agent support is a genuine advantage. The README lists support for Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode, and more, which is broader than most competitors.

Maintenance and License

The project is licensed under Apache-2.0, which permits commercial use, modification, and distribution, with the condition that you preserve copyright notices. That is a permissive license, but you should read the full terms. The repository is actively maintained: the last push is from August 2026, with recent releases v13.17.0, v13.16.1, and v13.16.0. The version number suggests a mature project that has gone through many iterations. However, active development also means the API and configuration may change between releases. The README does not mention a migration guide or upgrade path. The OpenClaw installer handles updates, but for manual installs you need to track the release notes. The documentation is extensive, with links to installation, usage, and search tool guides. The existence of a docs site and an OpenClaw integration guide suggests the project is serious about support. Still, the worker service is a long-term operational commitment that you should evaluate before adopting.

Editorial conclusion

Adopt claude-mem if you use Claude Code or OpenClaw and lose too much time re-explaining project state in every new session. Skip it if you cannot run a persistent worker service or if your privacy rules forbid sending session logs to an AI for compression. Before adopting, verify the actual token cost of the progressive disclosure retrieval and test the <private> tag handling on a sample of sensitive files. Also confirm that the worker service restarts reliably after machine reboots, since the README does not detail that.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes