Session Compression

Compress session context without losing actionable information. Use before context window fills up or when handing off between sessions.

Why Compress

Compression Format

ACDE Format (Actions, Context, Decisions, Entities)

## A: Actions Completed
- [x] Refactored auth middleware (auth.ts, middleware.ts)
- [x] Added rate limiting (api/limiter.ts)
- [ ] Pending: Write tests for rate limiter

## C: Context
- Project: my-app (Next.js 16, TypeScript)
- Branch: feat/auth-refactor (3 commits ahead of main)
- Blockers: None

## D: Decisions
- D1: JWT over sessions (stateless, mobile-friendly)
- D2: 100 req/min rate limit (based on load test)
- D3: Rejected Redis session store (overkill for current scale)

## E: Entities
- Files: auth.ts:42, middleware.ts:15, api/limiter.ts (new)
- Deps: [email protected], [email protected]
- APIs: POST /auth/login, POST /auth/refresh, GET /auth/me

When to Compress

1. Pre-compact: Before context window compression (auto via hook)
2. Session handoff: When switching between sessions on same project
3. Agent delegation: When handing complex task to another agent
4. Milestone reached: After completing a significant piece of work

Compression Rules

What to Keep (Lossless)

• All decisions with reasoning (D1, D2, D3...)
• File paths and line numbers of changes
• Unresolved blockers or pending items
• Error root causes (not full stack traces)
• External constraints

What to Drop (Safe)

• Exploratory reads that didn't lead anywhere
• Redundant confirmations ("yes that looks good")
• Intermediate debugging steps (keep only root cause)
• Tool output that was just for verification
• Repeated context that's already in CLAUDE.md

Entity Coding

Replace verbose references with short codes:

"the authentication middleware in src/middleware/auth.ts" -> "auth.ts"
"the user requested that we use JWT tokens" -> "D1: JWT"
"the PostgreSQL database running on port 5432" -> "pg:5432"

Integration

Pre-Compact Hook

The session-compressor hook automatically generates ACDE format before context compression:

1. Scans recent tool calls for file paths -> E section
2. Extracts decisions from conversation -> D section
3. Lists completed/pending tasks -> A section
4. Summarizes project state -> C section

With Memory Palace

Compressed sessions feed into the palace:

• Decisions -> stored as drawers in appropriate rooms
• Entities -> indexed for cross-session search
• Actions -> tracked in thoughts/PROGRESS.md

With Compass Agent

Compass uses ACDE format for "where were we?" recovery:

Last session compressed:
A: 3 done, 1 pending (rate limiter tests)
D: JWT auth, 100rpm limit
E: auth.ts, middleware.ts, limiter.ts