context-compression

Context Compression — Long Session Management

Keep sessions productive by compressing completed work while preserving key decisions.

Overview

Long sessions (30+ turns) cause context degradation — the AI loses track of earlier work, repeats itself, or forgets decisions. Context compression proactively summarizes completed phases so the context window stays focused on active work.

Token Impact: Recovers 5,000-15,000 tokens in long sessions by replacing verbose tool outputs with semantic summaries.

---

When to Compress

Signal	Action
Session has 20+ turns	Consider proactive compression
Agent repeats earlier suggestions	Context is saturated — compress now
User says "we already discussed this"	Compress immediately
Switching to a new phase of work	Compress the completed phase
Large tool output (500+ lines)	Micro-compact the output

---

Compression Levels

Level 1: Micro-Compact (Tool Output)

Compress individual tool outputs while retaining semantic content:

❌ Before (raw grep output — 200 lines, ~4,000 tokens):
src/auth/jwt.ts:15: import { verify } from 'jsonwebtoken'
src/auth/jwt.ts:23: export function validateToken(token: string) {
src/auth/jwt.ts:24:   try {
src/auth/jwt.ts:25:     const decoded = verify(token, SECRET)
... (195 more lines)

✅ After (micro-compact — 5 lines, ~100 tokens):
Grep results for "jwt": Found 8 files, 42 matches.
Key files: src/auth/jwt.ts (main JWT logic), src/middleware/auth.ts (middleware),
src/api/login.ts (token creation). Token validation at jwt.ts:23-40.
Error handling at jwt.ts:42-55. Secret loaded from env at jwt.ts:8.

Level 2: Phase Summary

Replace a completed work phase with a summary:

❌ Before (full research transcript — ~3,000 tokens):
[turn 1] Read package.json...
[turn 2] Read src/index.ts...
[turn 3] Grep for "auth"...
[turn 4] Found 8 files related to auth...
[turn 5] Read src/auth/jwt.ts...
... (10 more turns of exploration)

✅ After (phase summary — ~200 tokens):
## Research Phase Complete
- Project: Next.js 15 app with JWT auth
- Auth files: 8 files in src/auth/, src/middleware/, src/api/
- Token flow: login → create JWT → store in httpOnly cookie → validate in middleware
- Bug location: src/auth/jwt.ts:45 — expiry check uses `<` instead of `<=`
- Decision: Fix the comparison operator, add edge case test