Why not a notes file?
Everything mcue records could be typed into a NOTES.md at the bottom of
your repository. That objection is correct, it is the first thing most people say,
and it deserves a straight answer rather than a feature list.
The short version: a notes file has no boundary, no derived view, and no way to admit it is unreliable. Those three gaps are what mcue closes. If none of them bite you, keep the notes file — the last section here says so plainly.
"I already keep a NOTES.md"
A notes file works until it is long. Then it fails in three specific ways.
It has no cap. The whole point of re-entry is reading less than you wrote. A notes file grows monotonically, so coming back means skimming everything to find the part that still matters. A resume packet is bounded at roughly 300 or 1000 tokens and assembled on demand — it is derived from your history rather than being your history. That cap is the feature, and a file cannot have one.
It cannot tell you it is unreliable. When you write notes while being pulled
into an incident, the file looks exactly like notes written calmly with the test
output in front of you. mcue marks that session mode: degraded, drops its trust
score, and the resume packet leads with Trust: low (degraded, low confidence)
before you act on it. You can write "I'm not sure about this" in a notes file, and
you will not, because the moment you are least sure is the moment you are most
rushed. See a week with mcue for what that looks
like in practice.
It stops at the project boundary. A notes file cannot answer "which of my
projects has gone quiet?" — that question needs a view across every project at once,
which is what mcue index derives. With one project this does not matter. With
twelve it is the only question that matters, and it is the one a per-repo file
structurally cannot answer.
There is also a quieter problem: a NOTES.md inside the repository is source
control's business, so it shows up in diffs, conflicts on merge, and gets reviewed.
Operating state is not source, and putting it under review changes what people are
willing to write down. Honesty about a bad session is the most valuable thing in the
record and the first thing to go when it is public to the team.
"My todo app already does this"
Todo apps hold future work: things to do, with a status. Operating state holds past intent and the gap between what you meant to do and what happened.
That gap is the whole product. "Intended to wire refunds to the ledger; spent the session discovering our ULIDs double-post through their UUID-keyed client" is not a task. It has no status, it will never be checked off, and it is the single most valuable sentence you will read in three weeks. A todo app has nowhere to put it.
The two are complementary rather than competing. Your todo app can keep the next action; it cannot keep the reason the last one failed.
Practically: todo apps also store data in a service you do not control, in a format you cannot grep, and they cannot hand an agent a bounded brief.
"That's what commit messages are for"
Commit messages record what the code became. They are the closest real competitor here, and they still miss on three counts.
They only exist where there is a commit. The four hours you spent ruling out an approach produce no commit. The afternoon lost to a connection-pool bug that turned out to be a misconfigured local environment produces no commit. Those are exactly the sessions whose lessons evaporate.
They are written for a different reader. A commit message explains a diff to someone reviewing it. Re-entry needs something else entirely: what you were trying to do, what is blocking, and where to put your cursor. Those are not the same document, and writing one well does not produce the other.
They are attached to work that survived. Abandon a branch and its messages go with it, along with the reason you abandoned it — which is the part worth keeping.
mcue does not compete with any of this. Git records source history; mcue preserves the operating state needed to continue the work. That boundary is deliberate and is covered in Operating state.
When a notes file really is enough
It genuinely is enough, and pretending otherwise would be dishonest. Keep the notes file if all of these hold:
- One project, or few enough that you never lose track of which has gone quiet.
- Working alone, with no agent that needs your context in a bounded form.
- One machine, so there is no question of state being reachable from elsewhere.
- Sessions close together, so you rarely return cold enough to have forgotten the specifics.
Under those conditions the overhead of a tool buys you very little. A file and some discipline will do.
The conditions that break it are ordinary, though, and they arrive one at a time:
| What changes | What breaks |
|---|---|
| a second and third project | you can no longer tell what has gone quiet |
| an agent joins the work | prose notes are the wrong shape; a bounded packet is not |
| a second machine, or a phone | the file is on the wrong computer |
| a three-week gap | you re-read everything to find the part that matters |
| a session that ends badly | nothing in the file marks it as unreliable |
If you have hit two of those, the notes file has already stopped working and you are probably compensating by hand.
The honest summary
mcue is not a better notes file — it is continuity infrastructure that keeps what a file cannot: a bound on what you read back, a derived view across every project, and a record that admits when it is unreliable. If you do not need those three things, you do not need mcue, and the quickstart takes five minutes to find out.
Next
- A week with mcue — the same argument as a worked example.
- Operating state — the boundary between what mcue owns and what Git owns.
- Projects, lanes, and plans — when one lane stops being enough.