tiered-memory · diff

git:20260328.e11b5d3 to git:20260613.89a1b96

31 added, 44 removed. Audit A to A.

---

name: tiered-memory

- description: Three-tier agent memory model (hot/cold/wiki) for 20-55% context reduction per spawn

+ description: Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn

domain: memory-management, performance

- confidence: high

- source: earned (production measurements in tamirdresher/tamresearch1, 34-74KB baseline payloads)

+ confidence: design (runtime not yet implemented)

+ source: design proposal

---

# Skill: Tiered Agent Memory

+ > **Status (v0.10.0):** This skill describes a **design proposal**, not a shipped runtime. Skill files install via `squad init`/`upgrade`, but the underlying tier scaffolding (`.squad/memory/hot/`, `cold/`, `wiki/`), Scribe promotion logic, and spawn-template tier-aware reads are tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264). Until those land, agents continue to load full `history.md` + `decisions.md` on every spawn.

## Overview

- 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.

+ Squad agents today load their full context history on every spawn, which grows unboundedly across sessions. The Tiered Agent Memory model proposes a three-tier separation so agents only load the bytes that are actually relevant to the current task, with older context kept available on demand.

---

## Memory Tiers

### 🔥 Hot Tier — Current Session Context

- - **Size target:** ~2–4KB

+ - **Size target:** keep small (~2–4KB typical)

- **Load policy:** Always loaded. Every spawn includes hot memory by default.

- **Contents:** Current task description, active decisions made this session, immediate blockers, last 3–5 actions taken, who you are talking to right now.

- **Lifetime:** Current session only. Discarded after session ends (Scribe promotes relevant parts to Cold).

- **Purpose:** Provide immediate task context without any latency or load decision.

### ❄️ Cold Tier — Summarized Cross-Session History

- - **Size target:** ~8–12KB

+ - **Size target:** larger summary, not full transcript (~8–12KB typical)

- **Load policy:** Load on demand. Include only when the task explicitly needs history.

- **Contents:** Summarized past sessions (compressed by Scribe), cross-session decisions, recurring patterns, unresolved issues from prior work.

- - **Lifetime:** 30 days rolling window. After 30 days, Scribe promotes to Wiki tier.

+ - **Lifetime:** Rolling window (default proposal: 30 days). Eligible entries are then promoted to Wiki.

- **Purpose:** Answer "what have we tried before?" and "what was decided?" without replaying full transcripts.

- **How to include:** Pass `--include-cold` in spawn template or add `## Cold Memory` section.

### 📚 Wiki Tier — Durable Structured Knowledge

- **Size target:** variable, structured reference docs

- **Load policy:** Async write, selective read. Load only when task requires domain knowledge.

- **Contents:** Architecture decisions (ADRs), agent charters, routing rules, stable conventions, external API contracts, known platform constraints.

- **Lifetime:** Permanent until explicitly deprecated.

- **Purpose:** Authoritative reference. Not history — structured facts.

- **How to include:** Pass `--include-wiki` or reference specific wiki doc paths in spawn template.

---

## When to Load Each Tier

|-----------|-----|------|------|

| New task, no prior context needed | ✅ | ❌ | ❌ |

| Resuming interrupted work | ✅ | ✅ | ❌ |

| Debugging a recurring issue | ✅ | ✅ | ❌ |

| Implementing against a spec/ADR | ✅ | ❌ | ✅ |

| Onboarding to unfamiliar subsystem | ✅ | ❌ | ✅ |

| Post-incident review | ✅ | ✅ | ✅ |

---

## Spawn Template Pattern

The default spawn prompt should include **Hot tier only**:

```

## Memory Context

### Hot (current session)

{hot_context}

```

Add `--include-cold` when the task needs history:

```

## Memory Context

### Hot (current session)

{hot_context}

### Cold (summarized history — load on demand)

See: .squad/memory/cold/{agent-name}.md

```

Add `--include-wiki` when the task needs domain knowledge:

```

## Memory Context

### Hot (current session)

{hot_context}

### Wiki (durable reference)

See: .squad/memory/wiki/{topic}.md

```

---

- ## Measurement Data

- Baseline measurements from tamirdresher/tamresearch1 production runs (June 2025):

- |-------|--------------|-------------|---------------|---------|

- | Picard (Lead) | 74KB / 18.5K tokens | 96% | ~3KB | 55% |

- | Scribe | 52KB / 13K tokens | 91% | ~4KB | 48% |

- | Data | 43KB / 10.7K tokens | 88% | ~3.5KB | 42% |

- | Ralph | 38KB / 9.5K tokens | 85% | ~3KB | 38% |

- | Worf | 34KB / 8.5K tokens | 82% | ~3KB | 20% |

- **Average savings: 20–55% per spawn** with Hot-only loading. Cold + Wiki on-demand adds ~2–8KB when needed, still well below current baselines.

- ---

- ## Integration with Scribe Agent

+ ## Integration with Scribe Agent (design — not yet implemented)

- Scribe is the memory coordinator for this system. It automates tier promotion:

+ Scribe is the proposed memory coordinator for this system. Once the runtime lands, Scribe will:

- 1. **End of session:** Scribe compresses Hot → Cold summary (keeps ~10% of session verbosity)

- 2. **After 30 days:** Scribe promotes Cold → Wiki for decisions/facts that aged into stable knowledge

- 3. **On-demand wiki writes:** Any agent can request Scribe to write a wiki entry mid-session using `scribe:wiki-write`

+ 1. **End of session:** Compress Hot → Cold summary (target: ~10% of session verbosity)

+ 2. **Aged cold entries:** Promote Cold → Wiki for decisions/facts that aged into stable knowledge

+ 3. **On-demand wiki writes:** Any agent can request Scribe to write a wiki entry mid-session

- See Scribe charter: `.squad/agents/scribe/charter.md`

+ Until then, see the Scribe charter for current behavior: `.squad/agents/scribe/charter.md`

---

- ## Implementation Checklist

+ ## Implementation Checklist (tracked in #1264)

- [ ] Scribe writes Hot context file at session start (`.squad/memory/hot/{agent}.md`)

- [ ] Scribe compresses and writes Cold summary at session end

- [ ] Spawn templates default to Hot-only

- [ ] Coordinators add `--include-cold` / `--include-wiki` flags as needed

- [ ] Wiki entries stored in `.squad/memory/wiki/`

- - [ ] Cold entries stored in `.squad/memory/cold/` with 30-day TTL

+ - [ ] Cold entries stored in `.squad/memory/cold/` with rolling TTL

---

## References

- - Upstream issue: bradygaster/squad#600

- - Production data: tamirdresher/tamresearch1 (June 2025)

+ - Tracking issue: [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — installation gap + runtime status

+ - Original design spike: [bradygaster/squad#686](https://github.com/bradygaster/squad/issues/686) — tiered memory implementation plan

+ - Related: [bradygaster/squad#600](https://github.com/bradygaster/squad/issues/600) — context payload growth

---

## Spawn Template

# Spawn Template: Agent with Tiered Memory

Use this template when spawning any Squad agent. By default it loads **Hot tier only**. Add optional sections as needed.

---

## Task

{task_description}

## WHY

{why_this_matters}

## Success Criteria

- [ ] {criterion_1}

- [ ] {criterion_2}

---

## Memory Context

### 🔥 Hot (always included)

- > Paste current session context here (2–4KB max):

+ > Paste current session context here (~2–4KB target):

```

Current task: {task_description}

Active decisions: {decisions_this_session}

Last actions: {last_3_to_5_actions}

Blockers: {current_blockers_or_none}

Talking to: {current_interlocutor}

```

---

### ❄️ Cold (include when task needs history — add `--include-cold`)

> Load on demand. Do not inline unless specifically needed.

- Summarized cross-session history is at:

+ Summarized cross-session history is at:

`.squad/memory/cold/{agent-name}.md`

Include when:

- Resuming interrupted work

- - Debugging a recurring issue

+ - Debugging a recurring issue

- "What have we tried before?"

**To load cold memory, add this section and fetch the file before spawning:**

```

## Cold Memory Summary

{contents_of_.squad/memory/cold/{agent-name}.md}

```

---

### 📚 Wiki (include when task needs domain knowledge — add `--include-wiki`)

> Load on demand. Reference specific wiki docs by path.

Wiki entries are at: `.squad/memory/wiki/`

Include when:

- Implementing against an ADR or spec

- Onboarding to unfamiliar subsystem

- Need stable conventions or API contracts

**To load wiki, add this section and reference the specific doc:**

```

## Wiki Reference

{contents_of_.squad/memory/wiki/{topic}.md}

```

---

## Escalation

If blocked or uncertain:

- - Architecture questions → @picard

- - Security concerns → @worf

- - Infrastructure/deployment → @belanna

- - Memory/history questions → @scribe

+ - Architecture questions → @picard

+ - Security concerns → @worf

+ - Infrastructure/deployment → @belanna

+ - Memory/history questions → @scribe

---

## Notes

- - Hot tier is always included and should stay under 4KB

- - Cold adds ~8–12KB; only include when history is relevant

+ - Hot tier is always included; keep it focused

+ - Cold adds a summary; only include when history is relevant

- Wiki adds variable size; only include specific relevant docs

- - See `skills/tiered-memory/SKILL.md` for full tier reference

- - See `docs/tiered-memory-guide.md` for wiring instructions

+ - Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn