| name | session-compression |
| description | Lossless session context compression for token efficiency. Extracts entities, decisions, and state into compact format before context window fills. 10-30x reduction in context size while preserving all actionable information. |
Session Compression
Compress session context without losing actionable information. Use before context window fills up or when handing off between sessions.
Why Compress
| Metric | Raw Context | Compressed |
|---|
| Token count | ~50K | ~3-5K |
| Decision count | Scattered | Indexed |
| File references | Buried in prose | Listed |
| Error history | Verbose stack traces | Root cause + fix |
| Reduction | 1x | 10-30x |
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: jsonwebtoken@9.0.0, express-rate-limit@7.0.0
- APIs: POST /auth/login, POST /auth/refresh, GET /auth/me
When to Compress
- Pre-compact: Before context window compression (auto via hook)
- Session handoff: When switching between sessions on same project
- Agent delegation: When handing complex task to another agent
- 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:
- Scans recent tool calls for file paths -> E section
- Extracts decisions from conversation -> D section
- Lists completed/pending tasks -> A section
- 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
