rubicanjr/session-compression

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: [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