Context Compression Techniques for Long AI Agent Sessions

What Is Context Compression for AI Agents?

Context compression is the practice of reducing the token footprint of the information an AI coding agent is working with — while preserving the decisions, patterns, and knowledge the agent needs to remain effective. When context windows fill, agents degrade. Compression extends sessions, enables fresh starts that aren't actually cold starts, and keeps the most important information in the highest-attention positions.

The goal of compression isn't just fewer tokens — it's better information density. A 200,000-token context full of conversation history, debugging tangents, and file reads isn't as useful as a focused 20,000-token context with the right architectural decisions, current state, and task description.

Why Context Windows Fill So Fast

Understanding what consumes context helps you know where to apply compression.

In a typical 2-hour Claude Code session working on a Next.js feature:

At 200,000 tokens, this session used 19% of the window. After 4 hours, the session might be at 70–80%. At that point, early architectural decisions face truncation or severe attention dilution.

The biggest consumers: conversation history (grows linearly with every exchange) and file reads (which can spike with large files like lock files, generated code, or logs). These are also the primary targets for compression.

Technique 1: /compact — Claude Code's Built-In Compression

The /compact command is Claude Code's primary tool for compressing long sessions. When invoked:

1. Claude Code generates a structured summary of the conversation history
2. The original conversation is replaced with the summary
3. The context window is freed for the rest of the session

How to use it:

/compact

Use proactively — before the session becomes unwieldy, not after it has. When you notice you're 40–50% through a complex session and you have a lot more work ahead, /compact now while context is still high quality produces a better summary than waiting until 90%.

Trade-offs:

• Reduces context significantly (a 30,000-token conversation history might compress to 3,000-token summary)
• Lossy — nuanced reasoning steps, exploratory paths, and specific error messages may be dropped
• The summary focuses on outcomes and decisions, not the path to reach them

Best used when: you have a long session with established decisions and you need to preserve context window capacity for the next phase of work.

Technique 2: /clear — The Session Reset (Lossless for What Matters)

The /clear command resets the conversation history while keeping the session running. The agent's next response starts with only CLAUDE.md as context.

This isn't compression in the traditional sense — it discards the conversation entirely rather than summarizing it. But used strategically, it's the most effective technique, because the information worth keeping is already in CLAUDE.md (decisions) and in the codebase (implementation).

Before using /clear, verify:

• All decisions made in the cleared session are in CLAUDE.md or are visible in the committed code
• The current state of in-progress work is either committed or you've written a state brief

State brief format:

[Before /clear, write:]
Current state: We've completed the Auth0 integration (auth.ts, middleware.ts done and committed).
Currently working on: The session handler in app/api/session/route.ts — basic GET is working,
need to add the refresh token logic (see TODO comment in file).
Next: After refresh token, add the logout endpoint.

After /clear, paste this state brief as your first message: "Read CLAUDE.md. [paste state brief]. Continue with the refresh token logic."

Why /clear is often better than /compact: It starts fresh with full attention on CLAUDE.md, rather than splitting attention between the CLAUDE.md and a compressed summary. For sessions where the work is naturally divisible into phases, /clear between phases produces cleaner subsequent sessions.

Technique 3: Proactive File Selection (Avoid Loading Unnecessary Context)

Most context isn't compressed — it's never added in the first place. Selective context loading keeps the window free for the work that matters.

Specific file references instead of open exploration:

# High context cost (agent reads many files):
"Look at how authentication works in this codebase"

# Low context cost (agent reads one specific file):
"Read src/lib/auth.ts"

Avoid reading files that change rarely: package-lock.json, yarn.lock, generated Prisma client files, and build outputs are enormous (hundreds of thousands of tokens) and rarely need agent attention. If the agent offers to read them, redirect to the summary of what changed instead.

Use .claudeignore to prevent accidental large file reads:

# .claudeignore
node_modules/
.next/
prisma/generated/
*.lock
dist/
build/
*.min.js

With these files ignored, Claude Code won't read them even if asked broadly. This passively prevents the most common sources of context bloat.

Technique 4: Structured Decision Extraction (Lossless Compression at Session End)

The highest-value compression technique isn't about the session in progress — it's about starting the next session with a compressed representation of everything that mattered.

At the end of a session (or when you're about to /clear):

1. Ask the agent: "Summarize the key architectural decisions and patterns we established in this session, formatted as CLAUDE.md entries."
2. Review the output
3. Add the relevant decisions to CLAUDE.md
4. Start the next session fresh — it has lossless access to every decision via CLAUDE.md

This is lossless for what matters (decisions and patterns) and discards what doesn't (the path to reach them). The next session's context starts small and focused.

The important difference from /compact: /compact is a summary of everything in the current context. Structured decision extraction filters to only the decisions worth persisting. The distinction matters when sessions include exploratory paths, debugging tangents, and discarded implementations.

Technique 5: Instruction Compression (More Efficient Task Descriptions)

How you phrase instructions affects token efficiency. Verbose task descriptions consume context that could be used for reasoning.

Before (high token cost):

I need you to look at the authentication system and figure out what's happening with
the session refresh flow. There seems to be an issue where sessions are expiring too
soon. The issue might be in the middleware or in the Auth0 configuration or possibly
in the session storage. Can you investigate and fix it?

After (lower token cost, same intent):

Read middleware.ts and lib/auth.ts. Sessions expire too soon. Find and fix the refresh flow.

This isn't just fewer words — it gives the agent a clear, bounded task rather than an open-ended investigation. Clearer instructions produce better output with fewer back-and-forths, which also reduces context growth.

Technique 6: External Storage for Reference Material

Large reference documents — API documentation, design specs, migration guides — don't belong in the conversation context. The agent doesn't need to read the entire Stripe API documentation to implement a single webhook handler.

Instead of loading large references into context:

• Reference them by URL: "The Stripe webhook spec is at stripe.com/docs/webhooks"
• Load only the relevant section: "Read only the 'webhook signature verification' section"
• Summarize in CLAUDE.md for repeated reference: "Stripe webhooks: verify signature with stripe.webhooks.constructEvent(); use STRIPE_WEBHOOK_SECRET env var"

The CLAUDE.md summary (one line) is infinitely more token-efficient than loading 50 pages of API documentation.

The Compression Priority Hierarchy

When managing context in a long session, apply compression in this order:

1. Proactive file selection (never load unnecessary context in the first place)
2. /clear between phases (fresh session with CLAUDE.md, when work is divisible)
3. Structured decision extraction (save decisions to CLAUDE.md, then /clear)
4. /compact (compress-in-place when /clear isn't appropriate)
5. Instruction compression (more efficient task descriptions going forward)

The techniques earlier in the list produce better results because they're proactive. /compact at the bottom isn't because it's bad — it's because the better options produce cleaner contexts.

The Relationship Between Compression and Context Rot

Context compression is a response to a symptom — long, bloated sessions. The underlying cause is that AI agents have no persistent memory, so everything must live in the context window.

Context rot occurs because the context window is finite and architectural decisions made early in sessions are progressively deprioritized as the window fills. Compression techniques manage this symptom.

The root solution is persistent context management: decisions captured in CLAUDE.md survive session resets and never need to be in the conversation context at all. Compression is then needed only for the working context of the current task — a much smaller and more manageable surface.

For the full architectural approach to managing both within-session and cross-session context, see AI Agent Memory: Short-Term vs Long-Term Explained.

Key Takeaways

• Context windows fill faster than expected: conversation history and file reads are the primary consumers
• /compact: Claude Code's built-in compression; lossy but powerful for extending long sessions
• /clear: discard conversation entirely; lossless when decisions are in CLAUDE.md first — often better than /compact
• Proactive file selection: never add unnecessary context; use .claudeignore to block large files
• Structured decision extraction: extract decisions to CLAUDE.md at session end — the best compression for starting the next session
• Instruction compression: specific, bounded task descriptions produce more with less context
• Structure matters more than size: a focused 5k-token context beats 50k tokens of conversation history
• Compression is a symptom response; persistent CLAUDE.md is the root solution

Related: How LLM Context Windows Actually Work · 7 Signs Your AI Coding Session Has Degraded · How to Persist Architectural Decisions Across AI Sessions