Notes and progress files
A NOTES.md, PLAN.md or progress log the agent keeps in the repo. The agent writes its plan, decisions and next steps to a file as it works, and reads it back at the start of the next session.
Verdict
The best free option for one agent on a long task, if you make it commit the file; it breaks down with several agents.
Best for
One engineer running one agent on a multi-day task who wants something today, with no new tools.
Poor fit
Several agents in one repo (the file becomes a merge conflict) and disposable sandboxes where uncommitted files die with the container.
Scores
| Criterion | Score | Why |
|---|---|---|
| Survival across sessions | Partial | Survives only if it is committed and pushed before the session or sandbox ends. |
| Cross-tool reach | Strong | Any agent that can read a file can read it. |
| Multi-agent sharing | Weak | Shared through git, so other agents see it at merge time, often as a conflict. |
| Retention of reasons | Partial | Keeps the reasons the agent bothered to write down, in its own paraphrase. |
| Scale | Weak | Read whole into context each time; it stops working once it is too long to read. |
| Openness | Strong | Plain files you own. |
Strengths
- Free, plain text, in your repo and your history.
- Any agent can read a file, so it crosses tools without setup.
- You can read and correct it yourself.
Limits
- It holds only what the agent chose to write, which is usually the plan and not the argument behind it.
- Uncommitted notes are lost with the sandbox or working copy.
- It grows until it has to be summarised, and then it has the same problem as compaction.
How it fails
- The agent stops updating the file halfway through a long run, and the next session trusts a stale plan.
- Two agents append to the same file and one set of notes is lost resolving the conflict.
Cost
Free: a file in your repo. You pay only the tokens the agent spends reading and writing it.