memheal tells a coding agent when it is going in circles.
A small Claude Code plugin for the two moments an agent loses the thread: when it keeps repeating a call that keeps failing, and when a new session starts with no idea what you were doing.
The agent runs npm run build. It fails: Error: Cannot find module 'dotenv'. Then it runs it again, unchanged.
Without memheal
With memheal
A scripted replay with one real part: the notice is memheal’s actual output for this error. Seven is how many times one reported session repeated a failing command before a person stepped in. What an agent does after reading the notice is up to the agent.
An agent that has just failed tends to try the same thing again
Each attempt looks reasonable on its own. The command is plausible, the error is familiar, and nothing in the session is counting. So the fourth run looks exactly like the first, and the work stops moving while the steps keep adding up.
One reported session ran the same failing command seven times before a person stepped in. Claude Code issue 19699
In a study of command-line coding agents, repeating one failing approach showed up in 15% of failed runs and cost 29% of the steps wasted in them. Failure as a Process
A request that Claude Code itself bound repeated identical calls was closed without a fix. Claude Code issue 67812
What memheal does about it
- It counts. Each failed call is reduced to who ran it, which tool, what was attempted and the lines of the error that say what went wrong. Only a hash of that is kept.
- It speaks up on the third. When the same failure comes back a third time, the agent is told so, with the failing line quoted, and nudged to change approach or ask you.
- It resets on an edit. Running the same command again after changing a file is normal work, so an Edit or Write call starts the count over.
The notice is advice. memheal never blocks a call.
A new session starts cold
Close the terminal on Friday and open it on Monday, and the agent knows nothing about last week. The same thing happens in the middle of long work, when the conversation is compacted to make room.
memheal keeps a short record of what you have been asking about in each project, in your own words. When a session starts or is compacted, the agent is shown that record once. Play a week to see it form, shift and fade.
What you asked this week
Topics memheal is holding
The bar is the topic’s weight right now.
What the agent would be shown if a session started now
Every topic, weight and record here was produced by the plugin’s own code from these eight prompts. A weight falls by about 70% a day, so after a weekend the bars are nearly empty and only their order matters. Topics are grouped by shared words, which is rough.
Four moments, and nothing in between
memheal runs only when Claude Code calls one of its hooks. It starts no background process and adds nothing to your prompts.
The failure is counted. On the third, fifth and seventh identical one, the agent gets the notice.
The failure counts start again.
The prompt is filed under one of at most 24 topics for the project. Nothing is printed.
The agent is shown the record, at most 900 characters, once.
- 40 to 65 ms per hook on the machines we measured
- About 850 lines of plain JavaScript, no dependencies
- Node.js 18 or newer is the only requirement
What it keeps, and what it never touches
Everything memheal stores is plain JSON in the plugin’s own folder on your machine. Two commands cover it: /memheal:status prints what is stored for the project, and /memheal:forget deletes it.
It keeps
- Up to 24 topics per project: topic words, a prompt count, and up to three excerpts of your prompts cut to 140 characters.
- Up to five file paths you named per topic, and only ones that exist.
- For failures, a hash and a count. No command, no error text.
- A topic for 30 days after its last prompt. Failure counts for two days.
It never
- Opens your conversation transcripts or Claude’s memory files.
- Reads the files in your project.
- Makes a network request or a model call.
- Stores text that looks like a key, token or password. That is replaced before anything is written.
Small on purpose
memheal started as a much larger plan. Before building any of it, each idea got a cheap test that could kill it. We explored five directions. One was built, one was kept in a smaller form, and three were dropped, two of them by our own measurements.
Where it stands
Version 0.1.0 is written and tested, and not released yet. It passes Anthropic’s plugin validator, Claude Code loads it and registers its hooks, and 63 automated tests pass. What is left before release is a full check in live sessions and Anthropic’s directory review.