AGENT SKILL

tiered-memory

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

License 许可
MIT
所属仓库
microsoft/waza
最近更新
2026-11-15
Stars
★ 1.5k
Forks
101

01 前言 Front Matter

name
tiered-memory
domain
memory-management, performance
source
design proposal
confidence
design (runtime not yet implemented)
description
Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn

03 SKILL.md 正文

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:

  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


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


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/

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 → current architecture owner from routing.md
  • Security concerns → current security owner from routing.md
  • Infrastructure/deployment → current delivery owner from routing.md
  • Memory/history questions → current memory owner from routing.md

Notes

  • 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
  • Runtime backing is tracked in bradygaster/squad#1264 — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn

04 同仓库更多 Skills

microsoft
microsoft/waza

waza-runner

Run evaluations on Agent Skills to measure their effectiveness. USE FOR: "run skill evals", "evaluate my skill", "test skill quality", "check skill triggers", "skill compliance check", "measure skill performance", "run evals on [skill-name]", "grade skill execution". DO NOT USE FOR: writing skills (use skill-authoring), improving frontmatter (use sensei), or general testing unrelated to skills.

测试与质量Skill与智能体开发
★ 1.5k
microsoft
microsoft/waza

waza

**WORKFLOW SKILL** - Evaluate AI agent skills using structured benchmarks with YAML specs, fixture isolation, and pluggable validators. USE FOR: run waza, waza help, run eval, run benchmark, evaluate skill, test agent, generate eval suite, init eval, compare results, score agent, agent evaluation, skill testing, cross-model comparison. DO NOT USE FOR: improving skill frontmatter (use waza dev), creating new skills from scratch (use skill-creator), token counting or budget checks (use waza tokens). INVOKES: Copilot SDK executor, mock engine, code/regex validators. FOR SINGLE OPERATIONS: use waza run directly for a single benchmark.

测试与质量Skill与智能体开发
★ 1.5k
microsoft
microsoft/waza

waza-interactive

Interactive workflow partner for creating, testing, and improving AI agent skills with waza. USE FOR: run my evals, check my skill, compare models, create eval suite, debug failing tests, is my skill ready, ship readiness, interpret results, improve score. DO NOT USE FOR: general coding, non-skill work, writing skill content (use skill-authoring), improving frontmatter only (use sensei).

开发工程师内容创作者Skill与智能体开发
★ 1.5k
microsoft
microsoft/waza

code-explainer

Explains code snippets in plain English, breaking down what the code does step by step. Perfect for learning, code reviews, or documentation.

开发工程师
★ 1.5k
microsoft
microsoft/waza

compatibility-skill

Read fixture status and report whether it is ready.

★ 1.5k
microsoft
microsoft/waza

evidence-judge

Read a supplied report and summarize its recorded status and numeric items.

★ 1.5k