feat(memory): tiered agent memory skill — hot/cold/wiki tiers

[tamirdresher]

Addresses #600

Problem

Agents carry 34-74KB context (82-96% old noise). No tier model exists.

Solution

Three-tier memory model: Hot (always loaded, ~2-4KB), Cold (on-demand, ~8-12KB), Wiki (durable reference).

Measurements from production (tamirdresher/tamresearch1, June 2025): 20-55% context reduction per spawn.

Files

• skills/tiered-memory/SKILL.md — Full skill reference with tier specs, load policies, measurement data
• templates/spawn-with-memory.md — Spawn template showing conditional tier inclusion
• docs/tiered-memory-guide.md — Wiring guide for coordinators, file layout, rollout checklist

Integration

Scribe agent automates tier promotion: Hot→Cold at session end, Cold→Wiki after 30 days.

[bradygaster]

🔍 Squad Team Review

Reviewed by: Procedures (Prompt Architect) — Pass 3 of consensus ceremony
Action: Hold — proposal-first policy applies
Team Consensus: 5/5 AGREE

Review Summary

This PR implements tiered memory management for skills, enabling efficient caching and context prioritization across skill instances.

Process Note

Per our team's documented proposal-first policy (.squad/decisions.md): "Meaningful changes require a proposal in docs/proposals/ before execution." This is a feature-class change that needs a proposal document before merge.

What's Needed

1. Create a proposal in docs/proposals/ describing the skill's purpose, integration points, and expected behavior
2. Retarget this PR from main to dev (our staging branch)
3. Once proposal is reviewed and approved, this PR can proceed

Thank you for the contribution! The implementation looks solid — we just need the process alignment. 🙏

⏸️ Action: HOLD — awaiting proposal + retarget to dev

[bradygaster]

FIDO Quality Review — PR #606: tiered agent memory skill

Verdict: ⚠️ NEEDS CHANGES

Blocking Issues

❌ Wrong file paths: Files are placed at root-level directories that don't exist in this project:

• skills/tiered-memory/SKILL.md — no root skills/ dir. Skills go in packages/squad-cli/templates/skills/ and packages/squad-sdk/templates/skills/
• docs/tiered-memory-guide.md — docs/ is for the Astro docs site (docs/src/content/docs/), not standalone guides
• templates/spawn-with-memory.md — root templates/ is for .squad/templates/ scaffolding, not standalone spawn templates

Expected locations:

• Skill → packages/squad-cli/templates/skills/tiered-memory/SKILL.md (and SDK equivalent)
• Guide → fold into the SKILL.md or docs/src/content/docs/features/tiered-memory.md
• Spawn template → packages/squad-cli/templates/skills/tiered-memory/spawn-with-memory.md or similar

❌ No changeset file: Feature PRs need a changeset with @bradygaster/squad-cli and @bradygaster/squad-sdk scoped names.

Non-Blocking Notes

• Target branch: Targets main — consider dev.
• Content quality: Excellent research. The 3-tier model (Hot/Cold/Wiki) is well-designed, the production measurement data from tamirdresher/tamresearch1 adds credibility, and the Scribe integration patterns are practical.
• SKILL.md format: Uses # Skill: Tiered Agent Memory heading and ## Overview instead of standard SKILL.md frontmatter. Missing frontmatter block entirely.
• Previously reviewed: This was approved in my earlier triage session (PR #606 over #602 as the superset). The content is still solid — just needs to land in the right places.

Needs restructuring to use correct file paths, add frontmatter, and include a changeset.

[bradygaster]

Thank you for this work, Tamir! 🚀

To get this PR ready for team review and merge, we need two quick adjustments:

1. *Retarget to \dev* — All feature work merges to the \dev\ branch first (not \main). You can change the base branch in the PR settings.

2. Add a proposal document — Feature-class skills need a brief proposal in \docs/proposals/\ before merging. Include:

   • What the skill does
   • Why it's needed
   • How it fits into our existing skill architecture

Once those are in place, the team will take another look and we can get this merged!

Thanks for your continued contributions to Squad 👍

[tamirdresher]

Fixed per FIDO review: restructured file layout to correct package paths. Moved skill content to packages/squad-cli/templates/skills/tiered-memory/SKILL.md and packages/squad-sdk/templates/skills/tiered-memory/SKILL.md. Merged content from skills/, docs/, and templates/ into single coherent SKILL.md with proper frontmatter. Added changeset with correct @bradygaster/squad-cli and @bradygaster/squad-sdk package names. Removed old wrong-path files. Also retargeting to dev branch.

[tamirdresher]

Fixed per FIDO review:

• Moved SKILL.md from incorrect root-level \skills/tiered-memory/\ to correct \packages/squad-cli/templates/skills/tiered-memory/SKILL.md\ (and SDK equivalent)
• Added proper SKILL.md frontmatter (name, description, domain, confidence, source fields)
• Removed incorrect \docs/tiered-memory-guide.md\ (content folded into SKILL.md)
• Removed incorrect \ emplates/spawn-with-memory.md\ (spawn template folded into SKILL.md as appendix)
• Added .changeset/tiered-memory.md\ with correct @bradygaster/squad-cli\ and @bradygaster/squad-sdk\ scoped package names
• Retargeted PR to \dev\ branch

[tamirdresher]

Addressed all review items: (1) Restructured files to packages/squad-cli/templates/skills/tiered-memory/ and SDK mirror. (2) Added SKILL.md frontmatter. (3) Added .changeset/tiered-memory.md with @bradygaster scoped names. (4) Added docs/proposals/tiered-memory.md. (5) Retargeted to dev.

[Copilot]

Pull request overview

Introduces a new “tiered-memory” skill template that proposes a hot/cold/wiki memory model to reduce agent spawn context size, along with a proposal doc and a changeset to publish the new templates in both the CLI and SDK packages.

Changes:

• Add tiered-memory SKILL.md templates to both @bradygaster/squad-cli and @bradygaster/squad-sdk.
• Add a written proposal documenting the motivation, approach, and risks for tiered memory.
• Add a Changesets entry bumping both packages minor for the new skill.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 12 comments.

File	Description
packages/squad-sdk/templates/skills/tiered-memory/SKILL.md	Adds the tiered-memory skill template and embedded spawn template guidance for the SDK templates.
packages/squad-cli/templates/skills/tiered-memory/SKILL.md	Adds the same tiered-memory skill template for the CLI templates.
docs/proposals/tiered-memory.md	Adds a proposal document describing the tiered-memory approach and intended rollout.
.changeset/tiered-memory.md	Publishes the new skill templates via minor bumps for CLI and SDK packages.

[Copilot]

The measurement table rows start with ||, which creates an unintended blank first column when rendered. Use a single leading | per row for proper markdown table formatting.

[Copilot]

This references a scribe:wiki-write capability, but the current Scribe charter (.squad/agents/scribe/charter.md) does not define this command or workflow. Either document how agents request wiki writes (and where they are written), or soften this to a proposed/optional convention to avoid misleading readers.

Suggested change

	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`
	3. **On-demand wiki writes (recommended convention):** Teams may define a `scribe:wiki-write` command that agents can use to request mid-session wiki entries.
	If you adopt this, document the `scribe:wiki-write` workflow in your Scribe charter (e.g. `.squad/agents/scribe/charter.md`); it is not defined there by default.

[Copilot]

This table uses || at the start of each row, which renders as an unintended blank first column. Use a single leading | per row for proper markdown table formatting.

[Copilot]

The PR description mentions additional deliverables (e.g., templates/spawn-with-memory.md, docs/tiered-memory-guide.md, and a skills/ skill path), but the proposal’s “What Changes” list doesn’t include them and the referenced guide file doesn’t exist in the repo. Please either add the missing files or update the PR description/proposal to reflect the actual artifacts being introduced.

[Copilot]

These references appear to be broken in this repo: there is no docs/tiered-memory-guide.md, and there is no skills/ directory at repo root (skills live under .copilot/skills/ and .squad/skills/, and this template is under packages/.../templates/skills/). Update the links/paths (or add the referenced guide file) so readers can navigate to the intended documentation.

Suggested change

	- See `skills/tiered-memory/SKILL.md` for full tier reference
	- See `docs/tiered-memory-guide.md` for wiring instructions
	- This SKILL file serves as the full tier reference
	- See your project's Squad wiring documentation (for example, `.squad/README.md`) for wiring instructions

[Copilot]

These references appear to be broken in this repo: there is no docs/tiered-memory-guide.md, and there is no skills/ directory at repo root (skills live under .copilot/skills/ and .squad/skills/, and this template is under packages/.../templates/skills/). Update the links/paths (or add the referenced guide file) so readers can navigate to the intended documentation.

Suggested change

	- See `skills/tiered-memory/SKILL.md` for full tier reference
	- See `docs/tiered-memory-guide.md` for wiring instructions
	- See `.squad/skills/tiered-memory/SKILL.md` (or `.copilot/skills/tiered-memory/SKILL.md`) for full tier reference
	- See the Tiered Memory wiring guide in your project's documentation for wiring instructions

[Copilot]

The markdown table has an extra leading | on each row (|| ...), which renders as an unintended empty first column. Use single leading pipes so the table renders correctly.

[Copilot]

The measurement table rows start with ||, which creates an unintended blank first column when rendered. Use a single leading | per row for proper markdown table formatting.

[Copilot]

This references a scribe:wiki-write capability, but the current Scribe charter (.squad/agents/scribe/charter.md) does not define this command or workflow. Either document how agents request wiki writes (and where they are written), or soften this to a proposed/optional convention to avoid misleading readers.

Suggested change

	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`
	3. **On-demand wiki writes (optional convention):** You can define a request pattern (for example, a `scribe:wiki-write` command) that agents use to ask Scribe to persist wiki entries mid-session.
	Document your chosen wiki-write workflow in `.squad/agents/scribe/charter.md` so it is clear how agents should request wiki updates and where they are stored.

[Copilot]

The skill introduces runtime artifacts under .squad/memory/..., but .gitignore currently does not ignore .squad/memory/ (it only ignores .squad/log/, .squad/sessions/, etc.). This will likely create persistent untracked changes for users. Consider moving hot/cold tiers under an already-ignored runtime directory (e.g., .squad/sessions/) or update the repo ignore rules and clarify which tiers are intended to be committed.