An agent’s context window is its only working memory — and it’s both finite and rented by the token. Long sessions overflow it; new sessions start blank. The memory pattern organizes what the agent keeps, where, and how it shrinks what no longer fits.

The analogy

The desk and the filing cabinet. On the desk (the context): the case you’re working on right now. In the cabinet (persistent memory): everything worth keeping between cases. And when the desk overflows, you don’t throw papers on the floor — you write a summary sheet and file the rest. That summary step is called compaction.

The principle

flowchart LR
    W["working memory — the context window"] -->|"overflowing?"| S["summarize: keep decisions, drop noise"]
    S --> W
    W <-->|"save / recall"| L["long-term memory — files, notes, database"]

Three mechanisms, three lifespans:

  • Working memory — the conversation itself: full detail, but paid on every turn (input tokens) and capped.
  • Compaction — when the context fills up, an LLM call rewrites the history into a dense summary: decisions made, current state, open questions. Detail is lost; the thread survives.
  • Long-term memory — facts written to durable storage (a notes file, a database) and recalled on demand in later sessions. This is exactly what a CLAUDE.md or an agent’s memory folder does.

A concrete example

A coding agent, three hours into a refactor:

context at 90% → compaction:
  "Goal: extract PaymentService. Done: 12 files moved,
   tests green. Decision: keep the old API as a facade.
   Next: update the docs."
new session next day → reads memory note:
  "PaymentService refactor in progress, facade pattern chosen"
→ picks up where it left off, without re-reading 3 hours of logs

When to use it

  • Long sessions: any agent that works for hours will hit the ceiling — plan compaction before it’s needed.
  • Recurring work: preferences, conventions and project state belong in long-term memory, not re-explained every morning (the amnesiac-new-hire problem).
  • Cost control: a lean context is cheaper on every single turn.

When to avoid it

  • Short, one-shot tasks: memory infrastructure for a task that fits in one context is pure overhead.

The classic trap

Memory rot. A note written three weeks ago says the API uses v1 — it has since moved to v2, and the agent confidently builds on the stale fact. Treat recalled memory as a hint to verify, not a truth: date your notes, and check anything load-bearing against the current state before acting on it.