[FEATURE] Two-Tier Context Architecture: Persistent Critical Knowledge + Rolling Fresh Summary

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Current compaction treats all context as a single blob — summarizing everything into one compressed summary. This creates two major problems:

1. Recursive degradation: After 2-3 compactions, you're summarizing a summary of a summary. Critical architectural decisions, file paths, naming conventions, and project structure get progressively more lossy with each pass — the telephone game effect.
2. Loss of structural knowledge: Information relevant for the entire session (app architecture, component hierarchy, tech stack decisions, conventions) gets mixed with transient task-level details and compressed together. The agent eventually "forgets" things it should know for every single turn.

The current workaround — putting everything in CLAUDE.md — is static and manual. It doesn't capture decisions made during a session, and it requires the developer to maintain it by hand.
Additionally, /clear is all-or-nothing. There's no way to reset the working context while preserving hard-won project knowledge. And closing Claude Code means losing all session context entirely — /resume is unreliable for long-running projects.

Proposed Solution

Two-Tier Context Architecture
Split the context into two separately managed sections:
Tier 1 — Persistent Critical Knowledge (slow-growing, never discarded during regular compaction)
A dedicated section the agent curates during the session. Only structural information qualifies:

File/folder structure and key file paths
Architectural decisions affecting multiple files
Tech stack choices and conventions (e.g., "Tailwind only, no inline styles")
Component relationships and data flow patterns
API contracts or interfaces referenced repeatedly

Could be implemented as an index pointing to files on disk rather than storing full content inline. Essentially an auto-maintained CLAUDE.md that lives within the session and captures decisions as they happen.
Tier 2 — Rolling Fresh Summary (replaced wholesale, never recursively compacted)
When compaction triggers:

Discard the previous Tier 2 summary entirely
Create a fresh summary of only the recent work (actual conversation since last compaction)
Keep Tier 1 untouched

This eliminates recursive degradation. The summary is always first-generation compression of real interactions — never a summary of a summary.
Tier 1 Compaction (when critical knowledge grows too large)
Tier 1 gets its own compaction that deduplicates and merges (not summarizes): removes superseded decisions, consolidates scattered file path references, prunes entries not referenced in last N turns. Triggers automatically at a configurable threshold or manually via /compact tier1.
New Commands
/clear smart — Clears Tier 2 and all active working context, but preserves Tier 1. The "I'm done with this batch, same project" command. Regular /clear stays as-is (nukes everything).
/context save [name] — Serializes Tier 1 + Tier 2 to disk (lightweight — ~20-30K tokens). E.g., /context save payments-refactor. Files stored in .claude/contexts/.
/context load [name] — Restores a saved context into a new session. Agent immediately has project structural knowledge (Tier 1) and a summary of where you left off (Tier 2), with full ~163K active window ready for work.
/context list — Shows saved contexts with timestamps.
Context Layout
┌─────────────────────────────────────────────┐
│ System prompt + CLAUDE.md │
├─────────────────────────────────────────────┤
│ Tier 1: Persistent Critical Knowledge │
│ (auto-curated, slow-growing, has its own │
│ compaction — deduplicates & merges, never │
│ summarizes. Could be disk-backed index.) │
│ ~5-15K tokens │
├─────────────────────────────────────────────┤
│ Tier 2: Fresh summary of most recent work │
│ (replaced wholesale each compaction, │
│ never recursively summarized) │
│ ~10-20K tokens │
├─────────────────────────────────────────────┤
│ Active working context │
│ ~163K tokens available for actual work │
│ │
│ /clear smart → clears here + Tier 2 only │
│ /context save → persists Tier 1 + Tier 2 │
└─────────────────────────────────────────────┘
Configuration
json{
"compaction": {
"strategy": "two-tier",
"tier1": {
"max_tokens": 15000,
"backing": "memory",
"auto_compact_threshold": 15000
},
"tier2": {
"strategy": "fresh-summary"
}
},
"context_persistence": {
"save_dir": ".claude/contexts/",
"auto_save_on_exit": false
}
}
Backward compatible: "compaction": "summarize" (default) keeps current behavior.

Alternative Solutions

Truncate mode (as proposed in #25528) — simpler but loses everything before the cutoff, including structural knowledge that's still relevant. Two-tier preserves the important parts while still discarding stale task details.
Better CLAUDE.md — Making CLAUDE.md auto-update during sessions would partially solve Tier 1, but doesn't address Tier 2 (recursive summary degradation) or session persistence (/context save/load).
Larger context windows — Using sonnet[1m] delays the problem but doesn't solve it. Eventually you still hit compaction, and the recursive degradation is even worse because there's more content to summarize. The two-tier approach works at any window size.

Priority

High - Significant impact on productivity

Feature Category

Performance and speed

Use Case Example

Scenario: Freelance developer working on a React + FastAPI app, doing a batch of 8 UI fixes in one session.
With current compaction:

Fix 1-3: Great context, agent knows the project well
Fix 4: Compaction triggers, summary preserves broad strokes
Fix 5-6: Agent is decent but occasionally forgets conventions
Fix 7: Second compaction — summary of a summary. Agent starts suggesting inline styles when you established Tailwind-only in fix 1
Fix 8: Developer gives up and runs /clear, re-explains everything

With two-tier architecture:

Fix 1-3: Agent promotes "Tailwind only, component structure is X, API routes are Y" to Tier 1
Fix 4: Compaction triggers — Tier 2 gets a fresh summary of fixes 1-3. Tier 1 untouched
Fix 5-6: Agent still knows all conventions (Tier 1) and has clean context of recent work (Tier 2)
Fix 7: Second compaction — old Tier 2 discarded, fresh summary of fixes 4-6. Tier 1 still intact
Fix 8: Works perfectly. No /clear needed
End of day: /context save ui-batch — saves Tier 1 + Tier 2 to disk, closes Claude Code
Next morning: /context load ui-batch — full project knowledge restored, 163K tokens free
Switching tasks: /clear smart — wipes the UI fix context, keeps project structure. Ready for backend work without re-explaining the codebase

Key insight: The planner can now develop full features across long sessions without losing the structural map of the app. Each compaction throws away stale task details but the agent never forgets what the project looks like. This is how human developers actually work — you forget the details of yesterday's bug fix but you always know your project's architecture.

Additional Context

_No response_