Coihuin Compress

Coihuin Compress

Context compression at natural breakpoints, not reactive to token limits.

Workflow

Session 1 (new work):
  → "checkpoint" → creates new checkpoint
  → chkcc current <checkpoint> → set as current

Session 2+ (continuing):
  → Read checkpoint file
  → chkcc current <checkpoint> → set as current
  → work + continuous maintenance
  → "archive" when done

Continuous Maintenance

This is the core principle. Don't wait for "delta" commands. Update the checkpoint as you work:

Update immediately, not in batches. Small, frequent updates keep the checkpoint alive in your working memory.

Checkpoint States

chkcc current <checkpoint>  # Set as current
chkcc current               # Show current
chkcc current --clear       # Clear current
chkcc status                # Show all active with summaries

Operations

Checkpoint

Create new state snapshot.

Trigger: "checkpoint", "create checkpoint"

How:

1. Read checkpoint-format.md for structure
2. Extract "What Must Survive" from conversation
3. Generate checkpoint following the format
4. Save to checkpoints/active/<name>.md
5. Update checkpoints/active/INDEX.md

Delta (Explicit)

Force a structured update when you want visibility into what changed.

Trigger: "delta", "update checkpoint"

How:

1. Add ## Delta: <timestamp> section to checkpoint
2. Summarize what changed since last delta
3. Update main sections with current state

Note: With continuous maintenance, explicit deltas are less necessary. Use when you want a clear marker of progress.

Archive

Complete work and move to historical storage.

Trigger: "archive"

How:

1. Capture outcome from user:

   What was achieved? Any learnings worth preserving?

2. Add ## Completion section with status, outcome, learnings, date
3. Move to checkpoints/archive/
4. Update checkpoints/active/INDEX.md
5. Learnings auto-extracted to checkpoints/LEARNINGS.md

Validation: Cannot archive checkpoints with active children (use --force to override).

Fork Detection

When work diverges into parallel streams, offer options:

Strong signals (any one suggests fork):

• User says work is unrelated
• Different issue/ticket involved
• Fundamental context switch

Weak signals (two+ together suggest fork):

• Working in entirely different files
• Scope expanding beyond original intent
• New dependencies unrelated to current work

When detected, present options:

• A) Create separate checkpoint (sets parent for lineage)
• B) Continue with current (expand scope)
• C) Set aside divergent work

Not a fork: Trivial fixes, config changes, supporting changes for main work.

Directory Structure

checkpoints/
├── active/
│   ├── INDEX.md
│   └── chk-*.md
├── archive/
│   └── chk-*.md
└── LEARNINGS.md          # Accumulated insights from archives

Reference Files

Priority Hierarchy (token pressure)

1. Must Keep: Problem, session intent, decisions, current state, next actions
2. Should Keep: Recent artifacts, recent play-by-play, technical context, breadcrumbs
3. Can Summarize: Older play-by-play, completed artifacts, historical decisions

Quality Self-Check

Before finalizing updates, verify:

1. Problem Clarity: Could a fresh agent understand without the conversation?
2. Decision Rationale: Is the "why" captured, not just the "what"?
3. State Specificity: Concrete progress, not vague status?
4. Action Actionability: Can someone execute Next Actions immediately?
5. Fresh Agent Test: Loading this cold, would you know exactly what to do?