A context file is a plain document an agent reads at the start of a session: CLAUDE.md, AGENTS.md, a system prompt, a project README written for machines. They are excellent. Unforgetter started with them, and its canonical record is still Markdown for the same reasons. This guide is not “files bad”. It is a precise description of where files stop, drawn from watching them stop.
Where a context file wins
- It is readable, versioned in git and owned by you.
- It costs nothing and works in every client that can read a file.
- For one project, one agent and a slow-changing set of conventions, it is hard to beat.
If that describes your work, use a file and stop reading.
The four points where it stops
1. Supersession
A file says what is true when it was last edited. It does not know that a decision changed on 6 August unless someone edited it on 6 August. In practice the decision is made in a chat, the file is updated later or never, and the agent reads the stale version with full confidence.
A working truth records supersession as data: the new decision, the date, and what it replaced. The compiler applies it. Nobody has to remember to edit.
2. Scope
A file is read in full by every agent that opens it. You can split files per project, but then the shared conventions are duplicated, and client material has to be kept apart by directory discipline. One misplaced file and an agent working for one client reads another’s.
A working truth is scoped by policy. The token decides which projects can be selected, and unlisted material cannot be retrieved even by search. Discipline is replaced by enforcement.
3. Corrections
You correct an agent in a session. Where does the correction go? Into that session’s history, which the next session may or may not find, and which other agents never see. Corrections that live in transcripts return as fresh suggestions.
A working truth treats a correction as an input. The record changes, and every agent’s next context reflects it. Rejected ideas are kept as rejected so they are not proposed again.
4. Maintenance
Files are maintained by people. The better the agents get, the more decisions happen inside their sessions, and the further the file falls behind. Eventually somebody rewrites it from scratch, and the history of why things are the way they are is gone.
A working truth is maintained by the sessions themselves: agents propose what they learned, and a single publisher reconciles. People review diffs instead of rewriting documents.
What does not change
The record is still Markdown. The canonical memory opens in any editor and would still be useful if Unforgetter stopped existing. Export is a product function, not an escape hatch. If the arguments above sound like an argument against files, they are not. They are an argument for keeping the file and adding the three things it cannot do for itself: supersession, scope and a controlled write path.
A practical test
Take your current context file and ask three questions.
- Is there a decision in it that has been reversed in a chat since the last edit?
- Is there material in it that at least one of your agents should not see?
- Is there a correction you have made more than twice?
One “yes” is normal. Three is the point where the file has become the silo. The homepage demo shows what the second agent receives instead, and How it works shows how the record stays current.