Tiered Memory

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. Until those land, agents continue to load full history.md + decisions.md on every spawn.

Overview

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

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

Integration with Scribe Agent (design — not yet implemented)

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

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

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