Memory & Compaction

Pain Signals — You Need This Pattern When:

• Long sessions hit the context window ceiling and the API rejects the next turn
• Tool output (file reads, search results, command stdout) dominates the transcript and crowds out the user's actual instructions
• The agent forgets early-session decisions because they were truncated by a naive sliding window
• Cost per turn grows linearly with session length even when most history is stale
• An agent re-reads the same file three times in one session because the prior read was evicted
• Token budget is dominated by input cost, not output

Compaction is a lossy compression problem. The goal is to keep load-bearing facts (decisions, invariants, user goals) and discard repeatable detail (raw tool output, intermediate reasoning). Done wrong, the agent loses memory of why it is doing what it's doing.

Core Principle

Treat the model's context as a cache with eviction, not a log. Three tiers: