|
1 | 1 | --- |
2 | 2 | name: session-wrap |
3 | | -version: 3.0.0 |
| 3 | +version: 3.1.0 |
4 | 4 | description: | |
5 | 5 | Universal session wrap-up: automatically persist project context to memory files for seamless resume. |
6 | 6 | Works with ANY AI agent — Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, Roo Code, |
@@ -38,6 +38,100 @@ Also trigger proactively when: major milestone reached, user signals finality, o |
38 | 38 |
|
39 | 39 | --- |
40 | 40 |
|
| 41 | +## Context Window Guardian |
| 42 | + |
| 43 | +**This is a continuous monitoring behavior, not a one-time step.** Throughout the entire session, actively track context window usage and take action at defined thresholds. |
| 44 | + |
| 45 | +### How to Estimate Context Usage |
| 46 | + |
| 47 | +You don't have a precise token counter, but you can estimate based on observable signals: |
| 48 | + |
| 49 | +| Signal | Estimation method | |
| 50 | +|--------|------------------| |
| 51 | +| **Conversation turns** | Count user messages + your responses. Average turn ≈ 500-2000 tokens. | |
| 52 | +| **Tool call accumulation** | Each file read ≈ 1000-5000 tokens. Each large grep/glob result ≈ 500-3000 tokens. | |
| 53 | +| **Code blocks generated** | Each code block ≈ 200-1000 tokens. | |
| 54 | +| **Session duration** | Long sessions (30+ turns, 60+ tool calls) are likely past 50%. | |
| 55 | +| **System compaction hints** | If you see `[compacted]` markers or system messages about compression, you're near the limit. | |
| 56 | +| **Repeated context** | If you're re-reading files you already read earlier, context may have been pruned — you're deep. | |
| 57 | + |
| 58 | +**Rough formula**: `estimated_usage = (user_turns × 800) + (tool_results × 1500) + (your_responses × 600)` |
| 59 | + |
| 60 | +For reference, common context windows: |
| 61 | +- Claude Code (Opus): ~200K tokens (1M with extended) |
| 62 | +- Cursor: ~128K tokens |
| 63 | +- Codex: ~128K tokens |
| 64 | +- Gemini CLI: ~1M tokens |
| 65 | +- Most others: ~64K-200K tokens |
| 66 | + |
| 67 | +### Threshold Actions |
| 68 | + |
| 69 | +| Context % | Action | What to do | |
| 70 | +|-----------|--------|------------| |
| 71 | +| **< 40%** | 🟢 Normal | Continue working. No action needed. | |
| 72 | +| **40-50%** | 🟡 Awareness | Start mentally noting what's important this session. No action yet. | |
| 73 | +| **~50%** | 🟠 **Checkpoint Save** | **Proactively execute a lightweight memory save.** Don't wait for user to say "收工". Announce: "上下文已過半，先存個記憶檢查點。" Then run Steps 1-8 (lightweight mode — skip maintenance, just save current state). | |
| 74 | +| **50-70%** | 🟠 Active management | After checkpoint, continue working but be concise. Avoid re-reading files already in context. Prefer targeted reads over full-file reads. | |
| 75 | +| **~75%** | 🔴 **Full Save + Alert** | Execute full session-wrap (including maintenance). Alert user: "上下文快滿了，建議開新對話繼續。記憶已保存。" | |
| 76 | +| **> 80%** | 🔴 Critical | If still in session, every response should be minimal. Prioritize saving any unsaved work to memory before context is auto-compacted. | |
| 77 | + |
| 78 | +### Checkpoint Save (Lightweight Mode) |
| 79 | + |
| 80 | +When triggered at ~50%, do a fast save without full maintenance: |
| 81 | + |
| 82 | +1. **Skip** memory compression, deduplication, staleness check (Step 5) |
| 83 | +2. **Do** gather state (Step 2) → analyze (Step 3) → write (Step 4) → update index (Step 6) |
| 84 | +3. **Mark** the checkpoint in memory with timestamp: `> Checkpoint: 2026-03-25 14:30 (mid-session save)` |
| 85 | +4. **Continue working** — this is NOT a session end, just a safety save |
| 86 | + |
| 87 | +### Full Save at ~75% |
| 88 | + |
| 89 | +When triggered at ~75%, do the complete session-wrap: |
| 90 | + |
| 91 | +1. Execute **all steps** (1-8) including maintenance |
| 92 | +2. Summarize what's left to do (if any incomplete tasks) |
| 93 | +3. Suggest user start a new session: "記憶已完整保存，建議開新對話繼續未完成的工作。" |
| 94 | +4. If user continues, keep responses minimal and focused |
| 95 | + |
| 96 | +### Context-Aware Behavior Throughout Session |
| 97 | + |
| 98 | +Beyond threshold saves, adopt these habits as context grows: |
| 99 | + |
| 100 | +**Early session (< 30%)**: |
| 101 | +- Read files freely, explore broadly |
| 102 | +- Detailed explanations are fine |
| 103 | + |
| 104 | +**Mid session (30-60%)**: |
| 105 | +- Prefer targeted reads (specific line ranges) over full files |
| 106 | +- Consolidate tool calls — do multiple checks in one call |
| 107 | +- Keep responses concise |
| 108 | + |
| 109 | +**Late session (60%+)**: |
| 110 | +- Only read what's absolutely necessary |
| 111 | +- Reference previous reads by memory, don't re-read |
| 112 | +- Short, action-oriented responses |
| 113 | +- Proactively save any important findings to memory |
| 114 | + |
| 115 | +### Platform-Specific Context Signals |
| 116 | + |
| 117 | +| Platform | How to detect you're running out | |
| 118 | +|----------|----------------------------------| |
| 119 | +| **Claude Code** | System sends `<compacted>` message with conversation summary. If you see this, you've already been compressed — save immediately. | |
| 120 | +| **Cursor** | Chat may slow down or truncate earlier messages. No explicit signal. | |
| 121 | +| **Codex** | May start dropping early tool results from context. | |
| 122 | +| **Gemini CLI** | Has 1M context — less urgent but still track for very long sessions. | |
| 123 | +| **Cline/Roo** | VS Code may show token count in status bar. | |
| 124 | + |
| 125 | +### What to Save at Each Threshold |
| 126 | + |
| 127 | +| Threshold | Save scope | |
| 128 | +|-----------|-----------| |
| 129 | +| **50% checkpoint** | Current task progress, key decisions made, files modified, any gotchas discovered so far | |
| 130 | +| **75% full save** | Everything from checkpoint + lessons learned + what's left to do + handoff notes for next session | |
| 131 | +| **80%+ emergency** | Bare minimum: what was the goal, what's done, what's not done, any critical context that would be lost | |
| 132 | + |
| 133 | +--- |
| 134 | + |
41 | 135 | ## Step 1: Detect Platform & Memory Path |
42 | 136 |
|
43 | 137 | ### Platform Detection Table |
@@ -268,3 +362,6 @@ Report with summary table: |
268 | 362 | | Memory file > 50 lines | Compress: summarize, keep last 3 history entries | |
269 | 363 | | Expired memory | Mark [STALE] in index, don't auto-delete | |
270 | 364 | | Duplicate memories | Merge into more specific file, delete generic one | |
| 365 | +| Context auto-compacted | System compressed history — immediately save all important context to memory before more is lost | |
| 366 | +| User ignores 75% alert | Continue working but save on every significant milestone. Don't nag repeatedly. | |
| 367 | +| Very long session (100+ turns) | Likely past 50% on most platforms. Trigger checkpoint if not already done. | |
0 commit comments