Skip to main content

Staleness Management

In one line: Memory is a point-in-time observation, not live state — verify any specific claim (count, path, line number) against current code before acting on it.

Do this: Treat "X exists" in memory as "X existed when this was written." Re-check before importing a module, calling a function, or citing a file:line.

What: A memory written on day 10 that says "the codebase has 33 ORM models" may be wrong on day 20. The methodology treats all memory as potentially stale and requires verification before acting on specific claims.

Why: Stale memory is worse than none. With no memory of a count, the AI checks the code and gets it right; with a stale memory it trusts, it gives a confidently wrong answer. The memory provided false confidence that suppressed the verification the AI would otherwise have done.

This is especially dangerous for file locations, line numbers, and counts. "The audit trail is in app/services/audit_service.py at line 142" may be wrong the moment the function moves, the file is renamed, or the code is refactored.

Staleness management rules:

  1. Verify before acting. When a memory makes a specific factual claim (a count, a file path, a line number), verify it against the current code before using it in a response or an implementation. The memory provides a starting point for investigation, not a conclusion.

  2. Update stale memories. When verification reveals that a memory is outdated, update the memory as part of the current task. This is not extra work — it is maintenance that prevents the same stale information from misleading future sessions.

  3. Distinguish stable from volatile claims. Some memory content is stable: "we chose Temporal for workflow orchestration" is unlikely to change. Other content is volatile: "the codebase has 33 ORM models." Treat stable claims with higher trust and volatile claims with lower trust.

  4. Timestamp awareness. Claude Code displays a staleness warning on memory files older than a configurable threshold: "This memory is N days old. Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated. Verify against current code before asserting as fact." This warning is a structural reminder, not a suggestion.

The key mental model: A memory file that says "X exists" means "X existed when this memory was written." It does not mean "X exists now." The difference matters when the AI is about to import a module, call a function, or reference a file path based on memory. Verify first.

Evidence: The staleness warning is the mechanism — Claude Code automatically injects an age annotation on older memories ("this memory is N days old… verify against current code before asserting as fact"). It is structural, not a suggestion, and it fires whether or not anyone remembers the rule. See appendix-d-memory.md.