Claude Code Session Compaction in 2026: How Context Summarization Works and What Your Agent Forgets

Claude Code Session Compaction in 2026: How Context Summarization Works and What Your Agent Forgets This article was written with the assistance of AI, under human supervision and review. Most Claude Code session failures stem from a single misunderstanding: developers treat the 200K context window as infinite storage when it is actually a rolling buffer with aggressive summarization. The agent hits the limit mid-conversation, compacts its history into a lossy summary, and continues executing with critical context missing. The failure mode here is subtle but expensive: your agent produces syntactically correct code that violates constraints it learned 50 messages ago but forgot during compaction. When Claude Code reaches approximately 160K tokens (80% of the 200K window), the runtime automatically triggers context summarization. The system preserves the most recent exchanges and system prompt, condenses the middle conversation into a prose summary, and discards the original messages. This process happens silently. No error surfaces. The agent continues responding, but the detailed reasoning chains, rejected approaches, and discovered edge cases from earlier in the session vanish. The correct approach anchors critical context outside the conversation buffer. Developers who treat Claude Code sessions as append-only logs lose state during compaction. Engineers who externalize constraints, decisions, and open tasks into persistent artifacts maintain continuity across compaction boundaries. The difference shows up in production: one pattern produces agents that drift after long conversations, the other maintains coherence through unlimited exchanges. Key Takeaways - Claude Code auto-compacts at ~160K tokens (80% of 200K window), summarizing middle conversation into prose and discarding original messages without warning. - Compaction preserves system prompt, recent exchanges, and explicit artifacts; ephemeral reasoning chains, rejected approaches, and discovered edge cases vanish. - Externalizing constraints into persistent artifacts (decision logs, constraint manifests) maintains continuity across compaction boundaries. - Manual compaction gives control over what survives; forcing early summaries with explicit retention rules prevents silent context loss. - Token discipline (concise system prompts, artifact-based state, pruning dead branches) delays or eliminates compaction in most sessions. How Context Summarization Actually Works Under the Hood Context summarization operates as a three-phase pipeline: retention selection, summary generation, and buffer reconstruction. When the session token count crosses the compaction threshold, the runtime partitions the conversation history into three segments. The system prompt and configuration directives occupy the first segment and survive untouched. The most recent N exchanges (typically 10-15 turns) occupy the third segment and also survive intact. The middle segment, containing the bulk of the conversation, feeds into the summarization model. The summarization model produces a condensed prose version of the middle segment. This summary aims to preserve factual outcomes: what files were modified, what errors were resolved, what dependencies were added. The summary does not preserve the reasoning process that led to those outcomes. A conversation where the agent tried four approaches before finding the correct one compacts into "implemented authentication using JWT" with no record of the three rejected strategies or why they failed. The reconstructed buffer contains: original system prompt, generated summary, recent exchanges. The agent continues from this state with no indication that compaction occurred. Total token count drops significantly, allowing the conversation to continue. The implication here is that the agent's "memory" of earlier conversation becomes a high-level narrative rather than a detailed transcript. Summarization quality varies with conversation structure. Linear conversations where each exchange builds on the previous one produce coherent summaries. Branching conversations where the agent explores multiple parallel tracks produce summaries that collapse those branches into a single narrative, losing the distinctions between approaches. Conversations with explicit artifact creation (decision documents, constraint lists) produce summaries that reference those artifacts, effectively externalizing the critical state. The runtime uses a smaller model for summarization than for the main conversation. This creates a semantic compression bottleneck: subtle distinctions the main model understood may not survive the summarization model's interpretation. A constraint phrased as "prefer functional patterns except in performance-critical paths" might summarize to "use functional patterns" with the exception clause lost. What Your Agent Forgets During Compaction (And What Survives) Compaction destroys detailed reasoning chains first. When the agent walks through a complex type inference problem, explains why approach A fails, tries approach B, discovers a TypeScript limitation, and finally succeeds with approach C, the summary collapses this to "resolved type inference issue." The exploration process vanishes. The agent cannot reference "the problem we encountered with approach B" in later conversation because approach B no longer exists in context. Rejected approaches disappear entirely. If the agent proposed using Redis for caching, the team rejected it due to operational constraints, and the conversation moved to an in-memory solution, compaction summarizes "implemented in-memory caching" with no record of the Redis discussion. Later in the session, if a new problem surfaces that Redis would solve, the agent may propose Redis again, unaware of the earlier rejection. Edge cases discovered during implementation survive only if they resulted in code changes. A conversation where the agent identifies "null handling breaks for empty arrays" and adds a guard clause will summarize "added null handling." But if the agent identifies the edge case, determines it cannot occur in the current architecture, and documents this conclusion in a comment without changing logic, the summary may not mention it. Later refactoring might reintroduce the vulnerability because the agent forgot the analysis. Constraint interpretations often get lost. When a human says "keep bundles under 200KB" and the agent asks "do you mean 200KB gzipped or uncompressed?" and the human clarifies "gzipped", that clarification exists as an exchange in the middle segment. After compaction, the summary says "optimized bundle size" with no record of the gzip requirement. The agent reverts to its default assumption (usually uncompressed) in subsequent work. Explicit artifacts survive compaction because the agent stores them as distinct context items rather than conversation history. A decision document created with "create a file called DECISIONS.md documenting our approach" persists across compaction. The agent can reference and update this file in later exchanges. This distinction is critical: ephemeral conversation compacts away, named artifacts persist. System prompt directives survive untouched. If your system prompt includes "always use strict null checks" that directive remains active after compaction. Configuration passed as conversation context ("for this session, assume PostgreSQL 15") may or may not survive depending on where it appears in the conversation timeline. Recent exchanges survive intact. The last 10-15 turns remain in full detail, creating a sliding window of recent context. This means the agent maintains strong coherence for immediate follow-up work but loses long-term context. A feature implemented 100 messages ago exists only as a summary, while work from the last 10 messages remains detailed. Reading Compaction Events: Debugging What Got Summarized Away Claude Code emits compaction events through its streaming API when summarization occurs. These events appear in the conversation metadata stream with type context.compaction . The event payload includes the original token count, post-compaction token count, and the number of messages summarized. Monitoring these events reveals when compaction happens and how much context collapses. interface CompactionEvent { type: "context.compaction"; timestamp: string; preCompactionTokens: number; postCompactionTokens: number; messagesSummarized: number; summaryTokens: number; } function monitorCompaction(eventStream: AsyncIterable ) { for await (const event of eventStream) { if (event.type === "context.compaction") { console.warn( Compaction at ${event.timestamp}: ${event.messagesSummarized} messages + (${event.preCompactionTokens} → ${event.postCompactionTokens} tokens) ); const compressionRatio = event.preCompactionTokens / event.postCompactionTokens; if (compressionRatio > 3.0) { console.error( "High compression ratio detected. Significant context loss likely." ); } } } } The compression ratio indicates summarization aggressiveness. A ratio above 3.0 means the summary is less than one-third the size of the original content, suggesting substantial information loss. Ratios below 2.0 indicate gentler summarization where more detail survives. Debugging context loss requires comparing the generated summary against the original conversation. The API does not expose the summary text directly, but developers can reconstruct it by examining the assistant's responses immediately after compaction. The first response following a compaction event often includes phrases like "as discussed earlier" or "building on our previous implementation" that reference summarized content. These references reveal what the agent believes it remembers. interface ConversationMessage { role: "user" | "assistant"; content: string; tokenCount: number; timestamp: string; } interface ContextSnapshot { messages: ConversationMessage[]; totalTokens: number; compactionHistory: