Context Rot & Pollution

Introduction

A knowledge OS that never gets pruned becomes a liability. Every piece of stale context carries the same authoritative weight as fresh context — and the model cannot tell the difference. When you write "the agent gateway runs at http://localhost:8080" in CLAUDE.md and then change the gateway URL without updating the file, the agent confidently sends requests to the wrong endpoint.

Context rot is not passive — it actively misleads. Stale rules don't just fail to help; they cause the agent to take confident wrong actions. This is worse than having no rule.

The Six Rot Patterns

The six patterns in order of severity:

Date mismatch (CRITICAL): CLAUDE.md references "the production server fix from last week" — it's now 6 weeks old. Not just stale — actively misleading about timing.

Contradictory rules (CRITICAL): Line 34 says "use Docker," lessons.md says "MC backend migrated to native launchd 2026-05-24." Both load. The agent has to guess which one is current. For Knox's stack, this was a real incident: the CLAUDE.md still documents the .ts.net funnel as production even though it was removed (now flagged as stale in the notes).

Orphaned references (HIGH): MEMORY.md index links to feedback_mc_login_invalid_token.md — file was deleted in a cleanup. The index entry points to nothing. The agent may spend tokens trying to fetch a missing file.

Superseded tool versions (HIGH): CLAUDE.md documents browser-use MCP — explicitly deprecated in Knox's stack. Any session loading this rule might try to invoke a deprecated tool.

Stale counts (LOW): MEMORY.md says "2,800 chunks in Semantic Memory Layer" — now 2,968. Creates confusion but doesn't cause operational failures.

Missing freshness signal (MEDIUM): A rule has no date stamp. No way to know if it's 3 weeks or 3 years old. Low immediate risk, high long-term rot accumulation risk.

The Freshness Signal System

The core question for every rule in your context files: "Can I verify when this was last accurate?"

Verifiable freshness signals:

• ## 2026-05-31 — Rule Title format in lessons.md — date is explicit
• Topic files with date: 2026-05-29 frontmatter — file mtime + frontmatter agree
• MEMORY.md index entries with date markers: [Semantic Memory Layer port 8002 fix](reference_memory_service_port.md) — 2026-05-30

Stale risk signals:

• Undated rules: "use Docker for all services" — when was this true? Still true?
• Inline counts: "2,800 chunks indexed" — no date, may have been copy-pasted months ago
• Tool references without version or date: "browser-use MCP" — deprecated when?

The fix for every stale risk signal is the same: add a date stamp or move to a topic file with frontmatter. If the rule is timeless by definition ("never commit to main" — this rule has no expiry), mark it explicitly: # Timeless — no date required.

Contradictions: The Most Dangerous Rot Pattern

Contradictions are dangerous because they create ambiguity without error. The agent loads both rules, they conflict, and the model has to choose. The model often chooses based on recency or position in the file — not based on which rule is actually correct.

Examples from Knox's stack:

Example 1: CLAUDE.md says "Agent Gateway, Semantic Memory Layer, Mission Control" all run via Docker. MEMORY.md notes "MC backend migrated from Docker to launchd 2026-05-24." Both are loaded. A session modifying MC configuration will have conflicting instructions about restart mechanisms.

Resolution: The CLAUDE.md entry is marked as stale in the notes. The MEMORY.md note is the ground truth. The fix is to update CLAUDE.md with a dated note: "MC backend: native launchd (as of 2026-05-24) — Docker entry below is stale."

Example 2: Global CLAUDE.md: "Supabase is the only auth stack." A new project switches to a different auth provider. If the project CLAUDE.md doesn't explicitly override this with "Auth: [provider] (override: not Supabase)" the global rule leaks into project sessions.

Resolution: Project CLAUDE.md must explicitly override contradicting global rules — not just add new rules, but explicitly invalidate the global rule for this scope.

The "Stale Beats Absent" Fallacy

A common rationalization for leaving stale context in place: "Even if it's slightly outdated, it's better than having nothing."

This is wrong for systematic reasons:

1. An agent with no rule proceeds cautiously — it will ask, hedge, or flag uncertainty. An agent with a wrong rule proceeds with confidence.

2. Stale context blocks correct context from surfacing — if CLAUDE.md says "use browser-use MCP," the agent won't look for the replacement tool. The stale rule occupies the decision space.

3. Confidence scales with specificity — a specific stale rule ("gateway at http://localhost:8080") causes the agent to be more confident in the wrong answer than a vague rule would.

4. Debugging stale-context failures is expensive — when the agent follows a stale rule and the system breaks, the failure mode looks like "the code is wrong" not "the context is wrong." This misdirects debugging effort.

Context Pollution: External Noise

Context pollution is different from rot — it is the introduction of irrelevant or misleading context from outside sources.

Examples:

• A sub-agent is given the full CLAUDE.md (including unrelated design rules) when its task is purely algorithmic
• Search results from a web query contaminate the context with outdated docs from a deprecated library version
• A file read returns verbose output (logs, test runs) that dominates the context window

Pollution is managed by scoping (the “Scoping Context to the Task” lesson) and by controlling tool output verbosity (the “The Context Window as a Budget” lesson). Rot is managed by pruning and freshness signals (this lesson and the next lesson).

Summary

• Context rot is active misleading, not passive irrelevance — stale rules cause confident wrong actions
• Six rot patterns by severity: date mismatch, contradiction (CRITICAL) → orphaned refs, deprecated tools (HIGH) → missing date, stale counts (LOW-MEDIUM)
• The freshness signal system: date stamps on every rule, frontmatter on topic files, timeless annotations for evergreen rules
• The "stale beats absent" fallacy is wrong — absent triggers caution, stale triggers confidence in the wrong direction
• Contradictions are the most dangerous pattern: both load, model guesses, which guess wins is unpredictable

What's Next

The next lesson introduces the tooling and process for cleaning up context rot: pruning, compaction, the memory lifecycle, and the specific decision tree for what to keep, what to archive, and what to delete.