claude-mem turns agent sessions into a searchable memory layer

The most expensive resource in an AI agent session is not the tokens. It is the context window, and everything the model forgets when the session ends. claude-mem, an open-source plugin by Alex Newman (@thedotmack), attacks that problem directly: it captures everything an agent does during a session, compresses it with AI, and injects relevant context back into future sessions. The project, which works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode, and others, is a serious attempt to give agents durable memory without rebuilding the model itself.

The core mechanism is a set of lifecycle hooks. Claude-mem registers five lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd, plus a pre-hook dependency checker) that observe agent activity. Observations are stored in a SQLite database, then summarized and made searchable through a hybrid retrieval system that pairs SQLite FTS5 full-text search with a Chroma vector database. A local worker service, managed by Bun, exposes an HTTP API with a web viewer UI and search endpoints. The whole thing installs with a single command: npx claude-mem install.

What makes this interesting is not the storage layer. It is the retrieval strategy, which the project calls “progressive disclosure.” Instead of dumping a wall of past context into every new session, claude-mem uses a three-layer MCP tool workflow. First, search returns a compact index with IDs, costing roughly 50 to 100 tokens per result. Next, timeline gives chronological context around promising results. Finally, get_observations fetches full details only for filtered IDs, at 500 to 1,000 tokens per result. The project claims this filtering-before-fetching approach yields roughly 10x token savings.

That number matters. Context injection is the hidden tax on agentic workflows. Every token of injected memory competes with the model’s working capacity, and the cost compounds across long projects. Claude-mem’s design treats memory as a query problem, not a storage problem. The model asks for what it needs, when it needs it, and pays only for the slices it actually uses.

The ambition extends beyond Claude Code. The README lists support for OpenClaw gateways, Codex, Gemini, Hermes, Copilot, and OpenCode, with a one-line installer for OpenClaw: curl -fsSL https://install.cmem.ai/openclaw.sh | bash. There is also a Claude Desktop skill for searching memory from desktop conversations, and a web viewer UI for inspecting the memory stream in real time. Cloud sync backs up memories to cmem.ai, with the worker syncing on write rather than running a separate daemon.

Privacy controls are built in. Users can wrap sensitive content in <private> tags to exclude it from storage, and configuration files at ~/.claude-mem/settings.json control what context gets injected. The project also ships language-specific modes, including a built-in Simplified Chinese mode (code--zh) and a Japanese mode (code--ja), following the ISO 639-1 pattern. That localization effort signals an audience beyond the English-speaking developer bubble.

Licensing is Apache 2.0, a deliberate choice. The project’s license note says durable agentic memory “should be easy to embed in developer tools, local agents, MCP servers, enterprise systems, robotics stacks, and production agent harnesses.” That is a positioning statement as much as a legal one. Memory is infrastructure, and infrastructure wants to be embedded everywhere.

There is a wrinkle worth flagging. The README also mentions CMEM, a token created by a third party but “officially embraced” by Newman, the project’s creator. The token is described as a “community catalyst for growth” with an official Base chain contract address included in the README. For a developer tool, the presence of a token is a red flag for some users and a feature for others. It is the kind of thing that can split a community, and it is worth watching whether the token becomes a distraction from the technical work.

The deeper question is what claude-mem reveals about the state of agent tooling. The project is built with the Claude Agent SDK and TypeScript, and it works by hooking into lifecycle events rather than by modifying the model. That is the right architectural instinct. Model-level memory, where the model itself retains state across sessions, is a hard research problem that labs like Anthropic and OpenAI are still wrestling with. Tool-level memory, where an external system observes, compresses, and retrieves, is solvable today with off-the-shelf components: SQLite, Chroma, Bun, and a few well-placed hooks.

That division of labor is the real story. Claude-mem does not try to make the model remember. It makes the environment around the model remember, then serves that memory back on demand. This is the same pattern that turned databases into a commodity layer under applications. The agent is the application; claude-mem is the database. The model does not need a better memory if the tooling around it can recall better on its behalf.

The implications for AI builders are concrete. First, session persistence is no longer a reason to avoid agentic workflows. A developer can now run a long-running project across dozens of sessions and expect the agent to pick up where it left off, with citations pointing back to specific observations. Second, the token-efficiency design sets a benchmark for how memory should be injected: progressively, on demand, and with visible cost. Third, the open-source, embeddable license means this pattern can be folded into enterprise harnesses, robotics stacks, and MCP servers without licensing friction.

There are open questions. How well does the compression hold up over very long projects, where summaries of summaries accumulate drift? How does the hybrid search perform when the observation store grows to millions of rows? And what happens when multiple agents share the same memory store, with concurrent writes and conflicting observations? The SQLite-backed design is robust for single-user workflows, but multi-agent shared memory is a different beast.

The token situation adds another layer of uncertainty. Newman’s embrace of CMEM is a bet that community tokens can accelerate adoption. It may work, and it may alienate the enterprise users the Apache license is courting. The two signals are in tension: a permissive license says “embed this everywhere,” while a token says “speculate on this project’s growth.” Builders evaluating claude-mem for production should weigh both.

What is clear is that claude-mem has tapped a real need. Agent amnesia is the single most cited frustration in long-running agent workflows, and the project’s approach, observe, compress, retrieve, is the most pragmatic answer yet. It does not require a new model, a new framework, or a new hardware stack. It requires a few hooks, a local database, and a retrieval strategy that respects the context window.

The marker of success will be adoption outside the Claude Code ecosystem. If claude-mem becomes the memory layer for OpenCode, Codex, and Gemini workflows, it will have proven that memory is a tooling problem, not a model problem. If it stays pinned to Claude Code, it will remain a useful plugin with a ceiling. Either way, the architecture is now public, Apache-licensed, and easy to fork. The pattern is out of the bottle.

The next version of this idea will not be a plugin. It will be a standard: a memory format, a retrieval protocol, and a set of hooks that any agent can speak. Claude-mem is an early draft of that standard, and it is shipping today.

Model-level memory is a hard research problem. Tool-level memory is solvable today with SQLite, Chroma, and a few well-placed hooks.

The project’s own documentation frames the ambition: persistent context across sessions for every agent. That is a big claim, and the README backs it with a working implementation rather than a roadmap. The hooks exist, the worker runs, the search works. What remains is the hard part: proving the memory stays trustworthy as it scales, and convincing a skeptical developer base that a token-adjacent project can be a stable foundation.

For now, the practical advice for builders is straightforward. Try it on a single long-running project. Measure the token savings on retrieval. Inspect the SQLite database to see what is actually being stored. The architecture is transparent enough to audit, and the Apache license means there is no lock-in. If the pattern holds, it will be easy to embed. If it does not, the hooks and schema are still a useful reference for building your own.

The agent memory problem is not solved. It is, for the first time, tractable from the tooling side, and claude-mem is the clearest demonstration yet that the answer does not have to wait for the next frontier model.