memheal

What we learned before building

memheal is small because most of what we set out to build did not survive being measured. This page is the record: the questions we asked, how we tested them, what the numbers said, and what other people had already done.

How we workFour habits that decided what went into the plugin.

Measure first, and let the number decide

Write the pass mark down before the test

Each idea got the cheapest test that could kill it, with the threshold fixed in advance. A week of measuring replaced six weeks of building.

Check what the host already does

Claude Code keeps its own memory and audits its own instruction files. A plugin that repeats that work is competing with the product it runs inside.

Read a sample of what your tool flags

Our first scan reported 38% of paths as broken. Reading fifty of them showed almost all were package names and placeholders. The number measured our parser.

Keep it small enough to read

The plugin is about 850 lines with no dependencies and no model calls, so a reviewer, or a user, can read all of it in one sitting.

Five directionsEach one a question, a test, and a verdict.
Experiment 1 Finished
14 November 2026

Maintained notes almost never point at nothing

The checker is Anchored, a small Go program. It reads an agent’s notes file, pulls out every statement git can verify (file paths, commands, names in code, commits) and checks each one between the commit that wrote the line and today.

Each statement ends up fresh, drifted or dead. Drifted means the file it mentions was edited, so the note may still be true. Dead means the thing it mentions existed when the note was written and is gone now. Only dead notes are certainly wrong.

Try the checker. These notes were written at the first commit. Move through the history and watch what happens to them.

MEMORY.md

This is the tool’s real output on its own test repository, replayed commit by commit. That repository is built to go wrong. Real ones mostly do not, which is what the chart below shows.

What happened to the statements we could check

Two ways to get a frightening number that is wrong

38%

Count missing paths. Testing whether each path in the notes exists flags 325 of 864. We read a sample of 50. Almost all were package names, placeholders, globs and folders. That number measures the parser.

31%

Count drift. Our own first pass mark was “15% drifted or dead”, and the data cleared it. But drift only says a file was edited, and busy projects edit most files. That number measures activity.

Why so few notes are wrong

  • People and agents fix the notes as they change the code. That is the simplest reading of 1 dead statement in 1,125.
  • Claude Code’s memory is designed around the problem. Published readings of its instructions say it avoids saving what can be read from the code, and checks that a named file or function still exists before relying on a note. Sources below; they are third-party readings, not Anthropic documentation.

What this does not show

  • We did not measure Claude Code’s automatic memory directly. The script for it exists and has not been run.
  • We never counted tasks that failed because of a stale note.
  • The sample is active, well-known projects. Neglected ones may look worse.
  • The history we used reaches back about 120 days.
Experiment 2 Stopped before a result
One half became the plugin

Do agents repeat failures they already solved?

If notes are rarely wrong, maybe the gap is elsewhere: things an agent learned the hard way and never wrote down. A command that only works with a prefix. A config file that is not where you would look. Next week, a new session trips on the same thing.

Inside a single run this is measured. A study of command-line coding agents found that agents which keep repeating one failing approach account for 15% of failed runs and 29% of the wasted steps in them. Across sessions we found stories and no number, so we wrote a small Go tool, repeat-miner, to get one from our own history.

How the counting works

The tool reads the session transcripts Claude Code already keeps on disk. It makes no model calls and prints only counts. Step through three made-up sessions from its test suite to see what it records.

What an earlier session already learned

    Nothing yet.

    A failure where the very same call works later is normal work, such as fixing code and running the tests again. It is not counted, because a ledger could not have prevented it.

    The rule, written down before running it

    Of all tool failures, what share had an earlier session in the same project already hit and already solved?

    Under 10%Drop the idea
    10% to 25%Unclear, read the examples
    25% or moreWorth building a ledger

    Why it stopped before the run

    • It exists. deja-vu, a single program with no model, already answers “what did this machine run after that same error before”, and a second plugin recalls past fixes when a command fails.
    • Other people’s numbers are thin. One author hand-labelled 40 of his failed shell commands and found 6 were real mistakes by the agent. Another found the model no longer needed 30 of 35 lessons it had stored.
    • The rules. Anthropic’s policy for listed software forbids reading chat history and storing conversation content to change behaviour in later sessions. A ledger does both.
    • Our counter was wrong. On the first real transcript the first version found three fixes and all three were wrong. Checked against today’s transcript format, it also counted tool calls twice.

    What survived is the half of the question that has a number. Inside one session, repeating a failing approach is measured at 15% of failed runs, and it needs no history at all. That became the loop breaker in the plugin.

    Long-term memoryDropped on review

    A plugin should not compete with the memory it runs inside

    Our earlier tool, focus-gate, promoted recurring topics into long-term “stories”: append-only files the agent was instructed to maintain. Before porting it we reviewed it against what Claude Code does today.

    • It depends on obedience. The layer works only if the model follows instructions injected by a hook, every time. Nothing checks that it did.
    • It duplicates the host. Claude Code already keeps memory files per project and decides what belongs in them.
    • It was not sound. A code review of more than 5,000 lines found 21 defects, among them that the documented file format did not parse.

    What we kept from focus-gate is the part that needs no model: an attention score that rises when you return to a topic and decays when you do not.

    What was builtIn the plugin

    Two small things that survived

    The loop breaker

    Experiment 2 asked about failures repeated across sessions and never got a number. The half of that question that does have one is inside a single session: repeating one failing approach accounts for 15% of failed runs in a published study. It needs no history, no transcripts and no model, so it fits both the evidence and the directory rules.

    It is not a new idea. A published hook recipe and other plugins do something similar. Claude Code itself does not: a request to bound repeated identical calls was closed as not planned. memheal’s aim is a version small enough to read and clean enough to list.

    The session record

    focus-gate printed a summary on every prompt. While a conversation is intact the model already has your prompts, so that summary repeats what it knows. The moment it helps is when the conversation is gone: a new session, or after compaction. The record is now shown once at those two moments and never otherwise.

    See both working on the plugin page

    What the plugin cannot do

    • Topics are grouped by shared words. That is rough, and it works best in English.
    • A record made without a model is a list of your own words, not a summary.
    • The loop notice is advice to the agent. It does not stop anything.
    • It catches the narrowest kind of loop: the same call with the same error. An agent that rewords its command each time is not caught. The 15% figure in experiment 2 covers both kinds, so memheal addresses only part of it.
    • A file changed through the shell, with sed for example, does not reset the count. Only the Edit and Write tools do.
    • The idea is not new. Hook recipes and other plugins already do something similar. Claude Code itself does not: a request to bound repeated identical calls was closed as not planned. memheal’s aim is to be small, readable and acceptable to Anthropic’s directory.
    Directory rulesRead first-hand on 15 November 2026.

    Built to the rules of Anthropic’s directory

    The rules shaped the design as much as the experiments did. They are why the plugin is plain JavaScript and not the Go programs the experiments used, and why it never opens a transcript.

    What the publishing guide asks formemheal today
    A permanent, lowercase name that does not pass as one of Anthropic’smemheal, chosen
    A version that is raised with every releaseDone. 0.1.0
    Description, author, homepage, repository, a README of 40 words or more, and a licenceDone
    Readable source: no compiled, packed or minified code, no bundled executable, no dependency installDone. This is why the plugin is plain JavaScript and not the Go programs the experiments used
    Hooks that name every path from the plugin’s own folder, with no shell tricksDone, and held to it by a test
    claude plugin validate --strict passesDone. Run against the directory’s own profile, it flags one thing: there is no icon yet
    A load in a real sessionLoads and registers its hooks. A full session with a model is still to do
    Listing details: icon, documentation, support and privacy policy linksTo write. The privacy page will be short: nothing leaves your machine. The icon must be a square PNG of 512 to 2048 pixels, and the portal reads it only the first time, so it has to be right before the first save
    Submission as a plugin bundle through the developer portal, then review by a personAfter everything above

    Two things are worth saying plainly. A hook that runs a program is held for a human reviewer on every version, so each release waits for a person. And Anthropic’s policy for listed software says it must not store conversation content to change Claude’s behaviour across sessions. The session record does store short excerpts of prompts, on your machine. Another memory plugin is listed and does more, but we will ask before submitting. If the answer is no, the loop breaker ships alone.

    Sources: Publish and distribute a plugin, the plugin pre-submission checklist and the Software Directory Policy, read 15 November 2026.

    Sources Work by others that this rests on or competes with.