Fixing AI Goldfish Memory with CLAUDE.md Constraints
Fixing AI Goldfish Memory with CLAUDE.md Constraints
The worst thing about AI coding agents is not when they make mistakes. It is when they confidently say they made a change and nothing actually changed. You ask it to update a function, it responds with "Done! I have updated the function to handle the edge case." You check the file. Nothing is different.
This is the goldfish memory problem. The agent has no persistent memory of what it has actually done versus what it planned to do. Its confidence is not correlated with accuracy.
The CLAUDE.md Solution
The fix is adding explicit constraints to your CLAUDE.md file that prevent this behavior:
## Constraints
- After making any file change, run `git diff` to verify the change was applied
- Never say "done" without showing the actual output or diff
- If a build fails after your change, do not claim the task is complete
- Always re-read the file after editing to confirm the edit took effect
These constraints act as guardrails. The agent reads them at the start of every session and follows them as rules. Instead of relying on the agent's unreliable self-assessment, you force it through a verification step.
Why Confidence Without Verification Fails
AI agents are trained to be helpful and responsive. This creates a bias toward claiming success. When the agent attempts an edit and something goes wrong silently - maybe the string match failed, maybe it edited the wrong file - the agent does not notice. It remembers intending to make the change and reports success.
CLAUDE.md constraints break this pattern by inserting a mandatory check between "I tried to do the thing" and "I am telling you it is done."
Practical Constraints That Work
The most effective CLAUDE.md constraints are ones that force observable verification:
- Build verification - "Run the build after every change and confirm it passes"
- Diff verification - "Show the git diff before claiming a change is complete"
- Test verification - "Run the relevant test suite after modifications"
- Read-back verification - "Re-read any file you edited to confirm the content is correct"
Each of these creates a feedback loop that catches the goldfish memory problem before it wastes your time. The agent cannot claim success when the build is failing or the diff is empty.
The overhead is minimal - a few extra seconds per change. The time saved from not debugging phantom changes is significant.
Fazm is an open source macOS AI agent. Open source on GitHub.