| 1 | --- |
| 2 | name: tiered-memory |
| 3 | description: Three-tier agent memory model (hot/cold/wiki) for 20-55% context reduction per spawn |
| 4 | domain: memory-management, performance |
| 5 | confidence: high |
| 6 | source: earned (production measurements in tamirdresher/tamresearch1, 34-74KB baseline payloads) |
| 7 | --- |
| 8 | |
| 9 | # Skill: Tiered Agent Memory |
| 10 | |
| 11 | ## Overview |
| 12 | |
| 13 | Squad agents currently load their full context history on every spawn, resulting in 34–74KB payloads per agent (8,800–18,500 tokens). Measurement shows 82–96% of that context is "old noise" — information that is no longer relevant to the current task. The Tiered Agent Memory skill introduces a three-tier memory model that eliminates this bloat, achieving 20–55% context reduction per spawn in production. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## Memory Tiers |
| 18 | |
| 19 | ### 🔥 Hot Tier — Current Session Context |
| 20 | - **Size target:** ~2–4KB |
| 21 | - **Load policy:** Always loaded. Every spawn includes hot memory by default. |
| 22 | - **Contents:** Current task description, active decisions made this session, immediate blockers, last 3–5 actions taken, who you are talking to right now. |
| 23 | - **Lifetime:** Current session only. Discarded after session ends (Scribe promotes relevant parts to Cold). |
| 24 | - **Purpose:** Provide immediate task context without any latency or load decision. |
| 25 | |
| 26 | ### ❄️ Cold Tier — Summarized Cross-Session History |
| 27 | - **Size target:** ~8–12KB |
| 28 | - **Load policy:** Load on demand. Include only when the task explicitly needs history. |
| 29 | - **Contents:** Summarized past sessions (compressed by Scribe), cross-session decisions, recurring patterns, unresolved issues from prior work. |
| 30 | - **Lifetime:** 30 days rolling window. After 30 days, Scribe promotes to Wiki tier. |
| 31 | - **Purpose:** Answer "what have we tried before?" and "what was decided?" without replaying full transcripts. |
| 32 | - **How to include:** Pass `--include-cold` in spawn template or add `## Cold Memory` section. |
| 33 | |
| 34 | ### 📚 Wiki Tier — Durable Structured Knowledge |
| 35 | - **Size target:** variable, structured reference docs |
| 36 | - **Load policy:** Async write, selective read. Load only when task requires domain knowledge. |
| 37 | - **Contents:** Architecture decisions (ADRs), agent charters, routing rules, stable conventions, external API contracts, known platform constraints. |
| 38 | - **Lifetime:** Permanent until explicitly deprecated. |
| 39 | - **Purpose:** Authoritative reference. Not history — structured facts. |
| 40 | - **How to include:** Pass `--include-wiki` or reference specific wiki doc paths in spawn template. |
| 41 | |
| 42 | --- |
| 43 | |
| 44 | ## When to Load Each Tier |
| 45 | |
| 46 | | Situation | Hot | Cold | Wiki | |
| 47 | |-----------|-----|------|------| |
| 48 | | New task, no prior context needed | ✅ | ❌ | ❌ | |
| 49 | | Resuming interrupted work | ✅ | ✅ | ❌ | |
| 50 | | Debugging a recurring issue | ✅ | ✅ | ❌ | |
| 51 | | Implementing against a spec/ADR | ✅ | ❌ | ✅ | |
| 52 | | Onboarding to unfamiliar subsystem | ✅ | ❌ | ✅ | |
| 53 | | Post-incident review | ✅ | ✅ | ✅ | |
| 54 | |
| 55 | --- |
| 56 | |
| 57 | ## Spawn Template Pattern |
| 58 | |
| 59 | The default spawn prompt should include **Hot tier only**: |
| 60 | |
| 61 | ``` |
| 62 | ## Memory Context |
| 63 | |
| 64 | ### Hot (current session) |
| 65 | {hot_context} |
| 66 | ``` |
| 67 | |
| 68 | Add `--include-cold` when the task needs history: |
| 69 | ``` |
| 70 | ## Memory Context |
| 71 | |
| 72 | ### Hot (current session) |
| 73 | {hot_context} |
| 74 | |
| 75 | ### Cold (summarized history — load on demand) |
| 76 | See: .squad/memory/cold/{agent-name}.md |
| 77 | ``` |
| 78 | |
| 79 | Add `--include-wiki` when the task needs domain knowledge: |
| 80 | ``` |
| 81 | ## Memory Context |
| 82 | |
| 83 | ### Hot (current session) |
| 84 | {hot_context} |
| 85 | |
| 86 | ### Wiki (durable reference) |
| 87 | See: .squad/memory/wiki/{topic}.md |
| 88 | ``` |
| 89 | |
| 90 | --- |
| 91 | |
| 92 | ## Measurement Data |
| 93 | |
| 94 | Baseline measurements from tamirdresher/tamresearch1 production runs (June 2025): |
| 95 | |
| 96 | | Agent | Total Context | Old Noise % | Hot-Only Size | Savings | |
| 97 | |-------|--------------|-------------|---------------|---------| |
| 98 | | Picard (Lead) | 74KB / 18.5K tokens | 96% | ~3KB | 55% | |
| 99 | | Scribe | 52KB / 13K tokens | 91% | ~4KB | 48% | |
| 100 | | Data | 43KB / 10.7K tokens | 88% | ~3.5KB | 42% | |
| 101 | | Ralph | 38KB / 9.5K tokens | 85% | ~3KB | 38% | |
| 102 | | Worf | 34KB / 8.5K tokens | 82% | ~3KB | 20% | |
| 103 | |
| 104 | **Average savings: 20–55% per spawn** with Hot-only loading. Cold + Wiki on-demand adds ~2–8KB when needed, still well below current baselines. |
| 105 | |
| 106 | --- |
| 107 | |
| 108 | ## Integration with Scribe Agent |
| 109 | |
| 110 | Scribe is the memory coordinator for this system. It automates tier promotion: |
| 111 | |
| 112 | 1. **End of session:** Scribe compresses Hot → Cold summary (keeps ~10% of session verbosity) |
| 113 | 2. **After 30 days:** Scribe promotes Cold → Wiki for decisions/facts that aged into stable knowledge |
| 114 | 3. **On-demand wiki writes:** Any agent can request Scribe to write a wiki entry mid-session using `scribe:wiki-write` |
| 115 | |
| 116 | See Scribe charter: `.squad/agents/scribe/charter.md` |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | ## Implementation Checklist |
| 121 | |
| 122 | - [ ] Scribe writes Hot context file at session start (`.squad/memory/hot/{agent}.md`) |
| 123 | - [ ] Scribe compresses and writes Cold summary at session end |
| 124 | - [ ] Spawn templates default to Hot-only |
| 125 | - [ ] Coordinators add `--include-cold` / `--include-wiki` flags as needed |
| 126 | - [ ] Wiki entries stored in `.squad/memory/wiki/` |
| 127 | - [ ] Cold entries stored in `.squad/memory/cold/` with 30-day TTL |
| 128 | |
| 129 | --- |
| 130 | |
| 131 | ## References |
| 132 | |
| 133 | - Upstream issue: bradygaster/squad#600 |
| 134 | - Production data: tamirdresher/tamresearch1 (June 2025) |
| 135 | |
| 136 | --- |
| 137 | |
| 138 | ## Spawn Template |
| 139 | |
| 140 | # Spawn Template: Agent with Tiered Memory |
| 141 | |
| 142 | Use this template when spawning any Squad agent. By default it loads **Hot tier only**. Add optional sections as needed. |
| 143 | |
| 144 | --- |
| 145 | |
| 146 | ## Task |
| 147 | |
| 148 | {task_description} |
| 149 | |
| 150 | ## WHY |
| 151 | |
| 152 | {why_this_matters} |
| 153 | |
| 154 | ## Success Criteria |
| 155 | |
| 156 | - [ ] {criterion_1} |
| 157 | - [ ] {criterion_2} |
| 158 | |
| 159 | --- |
| 160 | |
| 161 | ## Memory Context |
| 162 | |
| 163 | ### 🔥 Hot (always included) |
| 164 | |
| 165 | > Paste current session context here (2–4KB max): |
| 166 | |
| 167 | ``` |
| 168 | Current task: {task_description} |
| 169 | Active decisions: {decisions_this_session} |
| 170 | Last actions: {last_3_to_5_actions} |
| 171 | Blockers: {current_blockers_or_none} |
| 172 | Talking to: {current_interlocutor} |
| 173 | ``` |
| 174 | |
| 175 | --- |
| 176 | |
| 177 | ### ❄️ Cold (include when task needs history — add `--include-cold`) |
| 178 | |
| 179 | > Load on demand. Do not inline unless specifically needed. |
| 180 | |
| 181 | Summarized cross-session history is at: |
| 182 | `.squad/memory/cold/{agent-name}.md` |
| 183 | |
| 184 | Include when: |
| 185 | - Resuming interrupted work |
| 186 | - Debugging a recurring issue |
| 187 | - "What have we tried before?" |
| 188 | |
| 189 | **To load cold memory, add this section and fetch the file before spawning:** |
| 190 | |
| 191 | ``` |
| 192 | ## Cold Memory Summary |
| 193 | {contents_of_.squad/memory/cold/{agent-name}.md} |
| 194 | ``` |
| 195 | |
| 196 | --- |
| 197 | |
| 198 | ### 📚 Wiki (include when task needs domain knowledge — add `--include-wiki`) |
| 199 | |
| 200 | > Load on demand. Reference specific wiki docs by path. |
| 201 | |
| 202 | Wiki entries are at: `.squad/memory/wiki/` |
| 203 | |
| 204 | Include when: |
| 205 | - Implementing against an ADR or spec |
| 206 | - Onboarding to unfamiliar subsystem |
| 207 | - Need stable conventions or API contracts |
| 208 | |
| 209 | **To load wiki, add this section and reference the specific doc:** |
| 210 | |
| 211 | ``` |
| 212 | ## Wiki Reference |
| 213 | {contents_of_.squad/memory/wiki/{topic}.md} |
| 214 | ``` |
| 215 | |
| 216 | --- |
| 217 | |
| 218 | ## Escalation |
| 219 | |
| 220 | If blocked or uncertain: |
| 221 | - Architecture questions → @picard |
| 222 | - Security concerns → @worf |
| 223 | - Infrastructure/deployment → @belanna |
| 224 | - Memory/history questions → @scribe |
| 225 | |
| 226 | --- |
| 227 | |
| 228 | ## Notes |
| 229 | |
| 230 | - Hot tier is always included and should stay under 4KB |
| 231 | - Cold adds ~8–12KB; only include when history is relevant |
| 232 | - Wiki adds variable size; only include specific relevant docs |
| 233 | - See `skills/tiered-memory/SKILL.md` for full tier reference |
| 234 | - See `docs/tiered-memory-guide.md` for wiring instructions |