feat(memory): tiered-memory runtime (hot / cold / wiki + Scribe promotion + tier-aware spawn) — v0.11 candidate #1309

Background

The v0.10 stabilisation set (#1292) added a tiered-memory skill to MANIFEST_SKILL_NAMES and shipped its SKILL.md, but the skill itself is design-only — no runtime backing. The shipped skill file explicitly says so in its Validation Status section (we tightened that wording in #1292 specifically because the original draft overclaimed).

If we don't follow through with runtime work, the skill is just a doc — agents read it, nothing changes about how memory actually gets stored, retrieved, or pruned.

Scope (3 sub-tracks)

Track 1 — Storage layer: hot / cold / wiki tiers

• Hot tier = current shape, write-through to .squad/memory/local/ (or the orphan branch under two-layer backend). Bounded by recency: keep last N entries, evict older to cold.
• Cold tier = compressed archive of evicted hot entries. New file: .squad/memory/cold/{YYYY-MM-DD}.jsonl per day; entries are not deleted, just demoted.
• Wiki tier = curated, agent-readable summary of cold-tier content. Scribe-promoted. Format: one Markdown file per topic at .squad/memory/wiki/{topic-slug}.md. Topic-slug derived from semantic clustering of cold entries.

Implementation pieces:

• New StorageProvider methods: promoteToCold(entry), promoteToWiki(topic, summary, sourceIds[]), readByTier(tier, filter).
• New .squad/config.json settings: memory.hotMaxEntries (default 500), memory.coldRetentionDays (default 365), memory.wikiPromotionThreshold (default 5 cold entries on the same topic).
• Migration path for existing .squad/memory/ directories (treat all existing entries as hot, promote to cold on first run when over threshold).

Track 2 — Scribe promotion daemon

• Extend Scribe agent's existing watch loop with a promoteMemoryTiers() step that runs on a configurable cadence (default: end-of-session + every 100 hot writes).
• Promotion algorithm:
  1. Hot → Cold: anything older than hotMaxAge (default 7 days) OR pushing over hotMaxEntries (LRU eviction).
  2. Cold → Wiki: when ≥ wikiPromotionThreshold cold entries share a semantic cluster (use existing embedding infra from packages/squad-sdk/src/memory/embeddings.ts if present; otherwise simple keyword TF-IDF).
• New squad memory tiers CLI subcommand: report current tier sizes, last promotion run, surface manual --promote-now action.

Track 3 — Tier-aware spawn template

• Spawn prompts currently inline the entire agent history + relevant decisions. With tiered memory, default behaviour should be:
  1. Always inline hot tier (small, recent).
  2. Inline cold tier ONLY when relevant to the routing-table hit (use the agent's domain + the user prompt's keywords to filter).
  3. Inline wiki tier ALWAYS — it's the curated long-term knowledge; small by construction.
• New spawn-template directive: {{memory tier=hot|cold|wiki filter=...}} so prompt authors can be explicit.
• Update .squad-templates/squad.agent.md and packages/squad-cli/templates/spawn-reference.md to reference the new tiers.

Out of scope (separate follow-ups)

• Semantic embedding model selection (use whatever the SDK already ships; if nothing, simple TF-IDF clustering).
• Cross-squad shared wiki (peer squads sharing wiki tier via cross-squad-communication Pattern 2 — too speculative for v0.11).
• Differential privacy / PII scrubbing on promotion (separate concern; handle via existing RAI policy hooks).

Tests / validation

• Unit: promoteToCold, promoteToWiki storage methods, tier-aware filter.
• Integration: end-to-end "init → make 600 hot writes → trigger promotion → verify counts in each tier → restart session → verify spawn template uses tiered context".
• Smoke: re-run the hello-squad smoke test from v0.10.0-insider.1 and verify no behaviour regression.

Why now / why not

Why now: tiered-memory skill is shipping in v0.10-insider.1 as design-only. Every agent that reads it and tries to act on it will hit the gap. Better to make the skill real or remove it from the manifest.

Why hold: Genuinely multi-week project (3 tracks × ~1 week each + integration). Should be scheduled as a v0.11 feature, not snuck into a stabilisation pass.

Recommendation

File subtasks (one per track) and schedule for v0.11. Don't try to land it as a single mega-PR.