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.

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
Chinese text in video always turns to mush. Dreamina handed the typesetting to code
Dreamina launched Motion Studio on November 10. It no longer generates frames; the model writes code that lays out text, shapes and pacing. Chinese titles stop blurring, but whether the content is right is still on you.
A community spreadsheet of taps that turns off the ads inside Chinese Android builds
A no-root tool that switches off the ads Chinese phone makers ship inside the system UI. Its method is a hand-written tap script per phone model, maintained by volunteers every time a ROM moves. It works, and the maintenance is the point.
GPT Image 2.6 held the token price and raised the bill
GPT Image 2.6 kept every token rate from 2.5 and still costs more per image, because more of the work now happens in output tokens. Eleven days into the ramp, the pricing structure says more than the leaderboard does.
Someone rebuilt IDM from the outside and wrote down what they did not touch
A Rust reimplementation of Internet Download Manager claims 5x the speed and 86 languages. The more interesting document is the paragraph explaining how it was built without copying anything.