Why does my agent forget rules after compaction?
When a long session is compacted (summarised to free context), details can be lost, and users have reported that instructions from CLAUDE.md stop being followed afterwards. Instruction files are advice the model reads, not rules that are enforced, so the reliable fixes are shorter instruction files, the critical rules stated early and plainly, and deterministic hooks for anything that must never be skipped.
What helps
- Keep the file short. Research on context files found that extra instructions do not generally improve task success and that agents follow them anyway, which costs tokens; every rule you keep should earn its place.
- Put the few rules that must survive at the top, as concrete statements, not hedges.
- Do not rely on advice for hard requirements. A formatter, a test run or a block on a dangerous command belongs in a hook or CI, which runs every time.
- When you compact manually, say what must be kept in the compaction instructions, and start a fresh session between unrelated tasks.
- If the same correction keeps coming back, that rule is not sticking. Move it into a skill with a clear trigger or into a hook.
A worked example
A way to find the rules that do not stick, using your own session history. review --chats reads your agent sessions locally and proposes changes; nothing changes without your approval. Output from the landing page:
$ skillhawk review --chats
[af240c47] no skill covers this 4 corrections (repeated) pending
The Skillhawk command that helps
What Skillhawk can do about it today:
npx skillhawk review --chats # repeated corrections in your own sessions -> proposed skill edits
npx skillhawk review <dir> # bloat, contradictions and vague wording in instruction files
npx skillhawk tokens --days 7 # where the tokens go, per session
Skillhawk does not detect which rules a compaction dropped, and does not write re-injection hooks. A compaction survival check is an idea we have not built.
Questions
Does Claude Code forget CLAUDE.md after /compact?
Users have reported exactly that in a Claude Code issue. Treat it as a risk: keep the file short, restate critical rules, and enforce hard requirements with hooks or CI.
How do I make an agent follow a rule every time?
Do not rely on instructions alone. Put the check in a hook or CI so it runs regardless of what the model remembers.
Sources
- anthropics/claude-code issue #19471
"After compaction, CLAUDE.md is completely ignored without warning" - Claude Code issue #15465 (mirror): Claude Code ignores claude.md context file before task execution
- arXiv 2602.11988: evaluating context files for coding agents
"Surprisingly, we find that providing context files does not generally improve task success rates."