[STUDY] Context compression — learn from Claude Code's compact system #155

New Issue

ezra · 2026-03-31T16:30:06Z

ezra commented

2026-03-31 16:30:06 +00:00

Parent Epic: #154

Maps to: #92 (context compression)

Source Files

src/services/compact/compact.ts (60,755 bytes) — the main compaction engine
src/services/compact/autoCompact.ts — automatic compaction triggers
src/services/compact/grouping.ts — how messages get grouped for compaction
src/services/compact/microCompact.ts — lightweight compaction variant
src/services/compact/sessionMemoryCompact.ts — memory-aware compaction
src/services/compact/postCompactCleanup.ts — cleanup after compaction
src/services/compact/prompt.ts — the prompt sent to the compaction model

Key Patterns to Study

Forked agent compaction — they fork a subagent that shares the parent's prompt cache, have it summarize, then insert a compact boundary message. The parent's cache prefix stays warm.
Partial compaction — they can compact part of the history while preserving recent messages.
File state cache — after compaction, they regenerate file attachment context so the model doesn't lose track of what files look like.
Boundary messages — special message type that marks where compaction happened, so the model knows history was compressed.

What to Document

How do they decide WHEN to compact? (token threshold? turn count?)
How do they decide WHAT to preserve vs summarize?
How do they handle tool results during compaction? (tool outputs can be huge)
What's the prompt they send to the compaction model?

Acceptance Criteria

Read all 11 files in services/compact/
Document the compaction decision logic
Document the forked-agent pattern
Write a 1-page design doc adapting this for Hermes/Python
Post findings as comment on #92

## Parent Epic: #154 ## Maps to: #92 (context compression) ### Source Files - `src/services/compact/compact.ts` (60,755 bytes) — the main compaction engine - `src/services/compact/autoCompact.ts` — automatic compaction triggers - `src/services/compact/grouping.ts` — how messages get grouped for compaction - `src/services/compact/microCompact.ts` — lightweight compaction variant - `src/services/compact/sessionMemoryCompact.ts` — memory-aware compaction - `src/services/compact/postCompactCleanup.ts` — cleanup after compaction - `src/services/compact/prompt.ts` — the prompt sent to the compaction model ### Key Patterns to Study 1. **Forked agent compaction** — they fork a subagent that shares the parent's prompt cache, have it summarize, then insert a compact boundary message. The parent's cache prefix stays warm. 2. **Partial compaction** — they can compact part of the history while preserving recent messages. 3. **File state cache** — after compaction, they regenerate file attachment context so the model doesn't lose track of what files look like. 4. **Boundary messages** — special message type that marks where compaction happened, so the model knows history was compressed. ### What to Document - How do they decide WHEN to compact? (token threshold? turn count?) - How do they decide WHAT to preserve vs summarize? - How do they handle tool results during compaction? (tool outputs can be huge) - What's the prompt they send to the compaction model? ### Acceptance Criteria - [ ] Read all 11 files in `services/compact/` - [ ] Document the compaction decision logic - [ ] Document the forked-agent pattern - [ ] Write a 1-page design doc adapting this for Hermes/Python - [ ] Post findings as comment on #92

Timmy was assigned by ezra

2026-03-31 16:30:06 +00:00

Timmy added this to the Claude Code Study milestone 2026-03-31 16:58:30 +00:00

Timmy added the study label 2026-03-31 16:58:30 +00:00

Timmy referenced this issue

2026-03-31 16:59:16 +00:00

[EPIC] Claude Code Source Study — Reference Architecture for Grand Timmy #154

Timmy referenced this issue

2026-04-05 12:31:25 +00:00

[ROADMAP] Claw Code — clean-room build plan from Claude Code study + Magic Context #408

allegro referenced this issue

2026-04-05 12:34:31 +00:00