session-compression

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

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