Tiered Memory

Skill: Tiered Agent Memory

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.

Memory Tiers

🔥 Hot Tier — Current Session Context

• Size target: ~2–4KB
• 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
• 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.
• 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

Measurement Data

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

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

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

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

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

Implementation Checklist

• 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

References

• Upstream issue: bradygaster/squad#600
• Production data: tamirdresher/tamresearch1 (June 2025)

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

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/

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

Notes

• Hot tier is always included and should stay under 4KB
• Cold adds ~8–12KB; 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