tiered-memory

name: tiered-memory description: Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn domain: memory-management, performance 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. 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

Situation	Hot	Cold	Wiki
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

Integration with Scribe Agent (design — not yet implemented)

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

End of session: Compress Hot → Cold summary (target: ~10% of session verbosity)
Aged cold entries: Promote Cold → Wiki for decisions/facts that aged into stable knowledge
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

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 rolling TTL

References

Tracking issue: bradygaster/squad#1264 — installation gap + runtime status
Original design spike: bradygaster/squad#686 — tiered memory implementation plan
Related: bradygaster/squad#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 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: .squad/memory/cold/{agent-name}.md

Include when:

Resuming interrupted work
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/