← Back to blog
AiAbout 6 min read

The Agent Memory Tool With a Search Index, a Viewer, and a Token Problem

Published Nov 2, 2026
The Agent Memory Tool With a Search Index, a Viewer, and a Token Problem

Every coding agent has the same embarrassing habit. You spend an afternoon explaining why the auth middleware cannot be touched, where the legacy config lives, and which two tests are flaky on purpose. Then you close the laptop. The next morning the agent greets you like a stranger and cheerfully suggests refactoring the exact file you told it to leave alone.

That gap is what claude-mem is aimed at, and the numbers suggest a lot of people feel it. The repo sits at roughly 110,000 stars, picked up about 5,850 in the past week, and has been the top of GitHub's weekly trending list for days. Alex Newman's project describes itself as a "persistent memory compression system" for Claude Code, and the key word there is compression, not storage.

What actually gets saved

The mechanism is less magical than the pitch. claude-mem registers itself on the lifecycle hooks Claude Code already exposes: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd. Each hook is a single command, claude-mem hook claude-code <event>, run by a small launcher the installer drops on your PATH.

As you work, tool calls get turned into "observations" — short semantic notes about what the agent did and what happened. A background worker service, managed by Bun, writes them into SQLite. When a new session starts, the most relevant observations get injected back into context before you type anything.

There is also a Chroma vector database in the stack for semantic search, alongside SQLite's FTS5 for keyword search. In practice the hybrid matters: "that migration script from Tuesday" is a keyword query, "the thing where the token refresh silently fails" is a semantic one, and you will type both.

Two details are worth flagging because they show the project has been used in anger. First, a <private> tag: anything wrapped in it never gets stored. Second, screenshots are opt-in and off by default, and they only go to the observer model if image inference is separately enabled. Someone thought about the failure mode where a memory tool quietly becomes a surveillance tool.

A wooden card catalog drawer pulled open, index cards fanned out under soft blue light

The three-layer retrieval trick

The part I find genuinely well designed is the search surface. Instead of dumping memories into context and hoping the model sorts it out, claude-mem exposes a three-step MCP workflow.

search returns a compact index with IDs, roughly 50 to 100 tokens per result. timeline gives you chronological context around an interesting hit. get_observations fetches full detail, at 500 to 1,000 tokens each, but only for the IDs you actually selected. The README claims about 10x token savings from filtering before fetching, which is the right shape of claim: it is an accounting argument, not a capability one.

This is the difference between a memory system and a context window. A bigger window is a flat cost you pay every turn. Progressive disclosure is a cost you pay only when you go looking. Anyone who has watched a long session burn through tokens on stale tool output will recognize which one scales.

Installation is one line, and that is the point

The happy path is:

npx claude-mem install

It works with --ide opencode, --ide t3code, --ide pi, --ide antigravity and a few others, plus a Grok Bot mode that watches chat logs because that host has no hooks. Inside Claude Code you can also go through the plugin marketplace:

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

You need Node 20 or newer. Bun and uv get pulled in automatically if missing. On Windows, the installer puts a launcher in %LOCALAPPDATA%\claude-mem\bin and adds it to your user PATH; if hooks complain about a missing executable, npx claude-mem doctor is the troubleshooting entry point.

One trap worth repeating from the README: npm install -g claude-mem installs the SDK only. It does not register hooks or set up the worker, so nothing happens and you will assume the tool is broken.

The part that makes me uneasy

During install you get asked to sign in with an email magic link, no card required. Signing in provisions a memory key and unlocks a hosted observer with a 30-day trial; when the trial ends, memory falls back to your Anthropic plan unless you subscribe. You can skip the whole thing by passing --provider, setting CLAUDE_MEM_ONLINE_OPTIN=false, or running in CI. Fine so far.

Then, near the bottom of the README, there is a section titled "What About CMEM?" explaining that CMEM is a token created by a third party and "officially embraced" by the project's author, complete with a contract address.

I do not think that makes the software bad. The code is Apache-2.0, the architecture is documented, and the licence choice is explicitly justified as a bet on embedding durable memory into developer tools. But a memory system that ships with a memecoin and asks you to sign in before it starts remembering is asking for a specific kind of trust, and you should decide whether to give it before you point it at a private repository. The local-only path exists. Use it deliberately rather than by accident.

Does memory actually make agents better?

The honest answer is: it makes them less repetitive. That is not the same thing. A remembered observation is a claim about the past, and the codebase has probably moved since. If the injected context says "the migration lives in db/legacy.ts" and someone split that file three weeks ago, you have not given the agent knowledge, you have given it confidence in a stale fact.

claude-mem's own framing helps here: observations are cited by ID, and you can inspect them in the local viewer at the worker URL. Treat them as notes, not as truth. The projects that get value out of this will be the ones that prune, not just accumulate.

There is a second-order effect too, and it is the one I would watch. Memory changes what an agent is willing to do without asking. An agent with history will happily proceed on assumptions it inherited from last week. That is a productivity gain right up until it is a very expensive misunderstanding.

Who should bother

If your agent sessions are short and self-contained, skip it. The overhead is not worth it, and a fresh context is a feature.

If you are running multi-day work on one repository, if you keep re-explaining the same architectural decisions, or if you have parallel agents that need to know what the others concluded, this is the most complete open implementation of that idea right now, and the one-line install means the experiment costs you ten minutes.

Just go in with the right expectation. claude-mem does not give your agent a memory. It gives your agent a filing cabinet, a search tool, and a habit of writing things down. Whether the notes are still true is, as always, your problem.

Related articles