context-compression

Context Compression for Long Sessions

Over a long session the context window fills with finished work, and the assistant starts repeating itself or losing the thread. The fix is to summarize what's done — preserving the decisions, discarding the transcript — so attention stays on what's still active.

Overview

Extended sessions (roughly 30+ turns) degrade: earlier work fades, suggestions repeat, decisions get forgotten. Compressing completed phases as you go keeps the window focused on live work.

Payoff: reclaiming on the order of 5,000–15,000 tokens in a long session by swapping bulky tool output for tight semantic summaries.

---

When to Compress

Signal	Response
Past ~20 turns	Consider compressing proactively
Suggestions start repeating	Window is saturated — compress now
User notes "we covered this already"	Compress right away
Moving into a new phase	Summarize the phase you're leaving
A tool dumps 500+ lines	Compact that output on the spot

---

Three Levels

Level 1 — Compact a Tool Output

Shrink a single noisy result down to its meaning.

Before — raw search dump (~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 {
... (and so on)

After — the gist (~5 lines, ~100 tokens):
Searched "jwt": 8 files, 42 hits. Core: src/auth/jwt.ts (JWT logic),
src/middleware/auth.ts (guard), src/api/login.ts (issues tokens).
Validation lives at jwt.ts:23-40, error handling at 42-55, secret read from env at line 8.

Level 2 — Summarize a Phase

Collapse a whole stretch of exploration into its conclusions.

Before — full research trail (~3,000 tokens):
[turn 1] read package.json
[turn 2] read src/index.ts
[turn 3] searched "auth"
... (a dozen more exploration turns)

After — phase summary (~200 tokens):
## Research done
- Stack: Next.js 15 app, JWT-based auth
- Auth code: 8 files across src/auth, src/middleware, src/api
- Flow: login -> mint JWT -> httpOnly cookie -> verified in middleware
- Defect: src/auth/jwt.ts:45 — expiry test uses `<` where it needs `<=`
- Plan: fix the operator, add a boundary test