An agent with a context window but no persistent memory relearns the same things every session: the user's role, the standing preferences they stated last week, the decision that was already made and doesn't need revisiting. An agent with unbounded persistent memory has a different problem, arriving later: it recommends a function that was renamed two months ago, cites a file path that no longer exists, or repeats a "fact" about the codebase that a memory entry recorded once and nobody ever updated. Both failure modes come from treating memory design as an afterthought — either skipped, or built as "write down everything, read it all back" with no filter in either direction.
Context window management, covered separately, decides what stays visible within one continuous session — it's about crowding, not durability. Persistent memory answers a different question: what should still be true and useful in a session that hasn't started yet, possibly after the code has changed, the user's priorities have shifted, or weeks have passed. The two get conflated because they look similar — both are "deciding what to keep" — but the right contents are different. A context window legitimately holds a lot of transient tool output; a persistent memory store should hold almost none of it, because transient output is exactly what goes stale first.
| Weak pattern | Stronger equivalent |
|---|---|
| saving a snapshot of the architecture, file layout, or code patterns to memory | re-deriving that from the current codebase each time; memory holds what isn't recoverable by reading the code |
| one flat, growing memory file with no categories | separating durable facts (a stated preference, a business constraint) from perishable ones (an in-progress task's status) so each can be pruned on its own schedule |
| writing a memory entry and never revisiting it | checking, before acting on a recalled entry, whether the thing it names (a function, a file, a person's role) still exists in current reality |
| recording what happened chronologically, like a log | recording what's still true now, organized by topic, so contradictions overwrite instead of accumulate |
| saving a correction only ("don't do X") | also saving confirmations of approaches that worked, so the agent doesn't drift away from validated judgment calls it never got explicit credit for |
Before writing an entry, ask whether it's derivable from a source of truth that still exists. Code structure, current file contents, recent commit history — all recoverable by reading the repository again, so storing them in memory just creates a second copy that can silently diverge from the first. What isn't recoverable that way: a preference the user stated in conversation and never wrote down anywhere else, the reasoning behind a decision that the code itself doesn't explain, a standing constraint like a deadline or a compliance requirement that no file encodes. The dividing line is "would re-reading the current state of the world reproduce this fact." If yes, derive it fresh every time instead of trusting a memory that might be stale. If no, it's a genuine candidate for persistent storage.
A memory entry is a claim about the world at the moment it was written, and the world keeps moving after that. A saved fact naming a specific function, config flag, or person's responsibilities is implicitly asserting "this was true then" — not "this is true now." Before an agent acts on a recalled memory in a way that matters (recommending a change, making a claim to the user, taking an action with consequences), it's worth a cheap check: does the named thing still exist, does the config flag still have that value, is the fact still current. Treat memory as context for what was true at a point in time, and prefer what can be directly observed right now when the two conflict — then correct or delete the stale entry rather than let it keep contradicting reality on every future recall.
The test to apply before trusting a recalled memory: if it names a specific file, function, flag, or person's role, and the user is about to act on it (not just asking about history), verify it against current reality first. "The memory says X" and "X is true now" are different claims, and only the second one is safe to act on.
Related: context window management for long-running agents covers the same instinct — deciding what deserves to survive — applied within a single session instead of across many.
A memory system that never gets pruned has the same shape as a context window that never gets summarized: it grows until the signal-to-noise ratio makes it worse than having no memory at all. See also writing a CLAUDE.md that actually changes behavior for the adjacent case of static, repo-committed context rather than a memory store that updates itself over time.
Don't confuse a memory entry with a task checkpoint. Memory holds facts worth recalling in a different, later conversation; a checkpoint holds progress through one specific run and should be read once at resume time, then ignored — see checkpointing long-running agent tasks.
This guide covers facts about the world. Guidance about how the agent should work — corrections and confirmations from the user — is a related but distinct store with its own staleness rules: see designing feedback memory for agents.