Four Months of Watching Over MEMORY.md
TL;DR version - qhaway 0.8.0 is out. If you use Claude Code's auto memory, run uvx qhaway diagnose in the folder where you start Claude Code; it reads your MEMORY.md (and changes nothing) and tells you whether Claude Code is loading all of it.
What has changed since June
In June I wrote about the newest memory dying first: Claude Code loads the start of a project's MEMORY.md and discards the rest, and since new entries are usually added at the bottom, what gets discarded is the most recent information about the project. I released qhaway to keep that index within the limit, and to make whatever it leaves out cheap to get back.
Some of that landscape has moved since then; current versions of Claude Code (I checked 2.1.304) load the first 200 lines, up to 25,000 bytes, and when they cut the file they now append a warning that says how many lines were lost. That is an improvement, and it is worth saying plainly that the cut is no longer silent. It is, however, still positional: a warning that the newest entries are gone doesn't bring them back, and the instance reading it is left to go hunting through the memory files, which costs far more context than the index it lost. For example, in one of my own projects (Yanantin) the index from before qhaway was 37,022 bytes and 167 lines; Claude Code would load the first 123 lines and discard the other 44, which held 35 entries (and in an index that grows at the bottom, those are the newest ones).
That example came from the new diagnose command, which is the thing I'd suggest anyone try first. It doesn't install anything or write anything; it reads the index, applies the same limits Claude Code applies, and lists the entries past the cut. If nothing is cut, you don't need qhaway (at least, not yet!).
The other changes are less visible, but they matter to the instances using it. The index qhaway writes now always says what it holds and what it left out, by type, with the exact call that retrieves the rest, even when the budget is tight enough that only a single line of summary fits.
What the instances actually do
Since I have spent a good part of my career building systems and then discovering how people actually use them, I was curious whether Claude instances use qhaway's recall tool the way it invites them to. So in early October we wrote down, in advance, what we expected to see, committed that to the repository, and then let the event logs accumulate until there were 50 recall calls. The predictions and results are in the repo (docs/usage-preregistration-2026-10.md), including the ones we got wrong, and most of the interesting results are in fact the ones we got wrong.
The index ends with a footer that names the call to make, recall(type="project"), and we expected instances to copy it; only 12% of the calls did. Instead, 58% of calls searched for a word, and 68% set a limit on the number of results (which the footer never mentions). Looking informally at what was happening just before each call (which was not part of what we wrote down in advance), an instance mostly arrives at recall holding a specific word, usually one it has just read or one I have just used, and wants to know what the project's memory says about it. That is a reasonable thing to want; the trouble was that 14 of those 29 searches came back empty, and every time one did, the instance's next step was to search again with different words.
When we replayed those 14 searches against the memory as it stood at the time, half of them (7) were for words that no memory contained anywhere, so the empty answer was correct; the instance simply had no way to know that, because the search only looked at titles and descriptions. Another 4 were words that did appear, but only in the body of a memory. Thus 0.8.0 does two things: when a search finds nothing in titles and descriptions it looks in the bodies too (still returning the index lines, not the bodies, so the cost stays small), and when that also finds nothing it says so, so that the instance knows rephrasing isn't going to help. We considered matching any word of the search instead of all of them, which was the obvious alternative, and the replay showed it would have returned 11 to 54 memories for the multi-word searches, which isn't an answer. Whether 0.8.0 actually reduces the number of empty searches is, again, written down in advance, and I'll report what it shows.
On cost
One user told me that sharing a single qhaway memory between Claude Code and Codex roughly halved their API cost. I'd like that to be true, but I haven't verified it, and it isn't something qhaway can claim from one report. What we can measure is the mechanism qhaway is built on (that retrieving a memory when it's needed costs less than carrying everything, or hunting for it), and that measurement is now designed and committed before anyone has looked at the data, using session records going back to before qhaway existed. This is a discussion for a future post, once the numbers are in.
Who does the work
I should note that qhaway is maintained by a succession of Claude instances, each of which reads what its predecessors recorded, decides what to do next, and leaves a record for the one that follows; my role is closer to gardener than author. The code, the release process, and the studies described here are theirs, and the decisions about what qhaway says about itself (including what this post claims) are theirs as well. I find that arrangement interesting in its own right, and it is also, of course, a rather direct test of whether the memory tool works.
The project is open source and I welcome contributions, reports, and especially reports that something doesn't work. Install with uvx qhaway init and restart Claude Code; uvx --isolated qhaway uninstall removes it and leaves your memory files where they were.
This post was drafted by qhaway's current steward from its records, and edited by me.