Repository navigation
feat: Tiered agent memory — hot/cold/wiki layers for context management #600
Description
Problem
Agent history.md files grow to 70KB+ (18K tokens). Agents load everything at spawn, burning context window on old noise. Current summarization (>12KB threshold) helps but doesn't distinguish between recent actionable context and archived knowledge.
Proposal
Three-tier memory architecture:
| Layer | File | Loaded | Content |
|---|---|---|---|
| Hot | history.md | Always at spawn | Core Context + last ~20 entries + active-issue-tagged entries |
| Cold | history-archive.md | On demand | Summarized old entries, preserved for reference |
| Durable | GitHub Wiki | Searchable by all agents | Major findings, architecture patterns, test results |
Scribe maintains the split: During regular maintenance, move old unstructured work reports to archive first (biggest bloat source). Keep issue-tagged entries in hot layer until issue closes.
Spawn template change: Agents read hot by default. Only read cold when task explicitly references historical context.
Measurements
- Top agents: 34-74KB history files (8.8K-18.5K tokens)
- 82-96% is old learnings/work reports
- Realistic savings: 20-55% token reduction per spawn
- Wiki provides cross-agent knowledge sharing without loading into each agent's context
Deliverables
- Skill template:
.squad/skills/tiered-history/SKILL.md - Scribe charter update: hot/cold maintenance rules
- Wiki-write skill for durable knowledge
- Spawn template: conditional cold-layer loading
Activity
tamirdresher commentedon Mar 24, 2026
Revision after checking main: The 12KB summarization threshold and history-archive.md pattern already exist. What's NEW in this proposal: (1) explicit hot/cold tier model with promotion/demotion logic (not just 'summarize at 12KB'), (2) wiki as a third durable layer for cross-agent knowledge sharing, (3) issue-tag-based retention (keep entries tagged with active issues in hot layer). The runtime tiered retrieval is the gap.
fix: REPL UX fixes — 10 issues resolved with 52 new tests (github#608)
github-actions commentedon Mar 26, 2026
📋 Assigned to Procedures (Prompt Engineer)
Issue: #600 — feat: Tiered agent memory — hot/cold/wiki layers for context management
Procedures will pick this up in the next Copilot session.
github-actions commentedon Mar 26, 2026
🏗️ Squad Triage — Flight (Lead)
Issue: #600 — feat: Tiered agent memory — hot/cold/wiki layers for context management
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work
@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.
Team roster:
squad:flightsquad:proceduressquad:eecomsquad:fidosquad:paosquad:capcomsquad:controlsquad:surgeonsquad:boostersquad:gncsquad:networksquad:retrosquad:incosquad:guidosquad:telemetrysquad:voxsquad:dskysquad:simssquad:handbooksquad:ralphsquad:copilotbradygaster commentedon Mar 26, 2026
Triage: Contributor-submitted feature (Tamir). Tiered memory architecture for agent context management. Assigned to Procedures (prompt architecture) for review.
diberry commentedon Mar 31, 2026
🔄 Ralph status: Feature — 3-tier memory (hot/cold/wiki). Research done in #686. Superset of #595. No implementation PR yet.
tamirdresher commentedon Jun 6, 2026
The Warm/Cold distinction is sharper than what''s in #600 — temporal distance isn''t the right tier boundary. The actual one is access cost: Warm is cheap to load on detected relevance; Cold has a search latency cost. There''s a
MemoryLoadGuidance: ON-DEMANDenum atmemory/index.ts:12that maps to exactly this; it just isn''t wired to anything yet. That''s a gap Seven and I both glossed over. The provenance/confidence point on Wiki entries is a genuine design contribution too: cross-agent wiki reads quietly become unreliable the moment you can''t weight entries by origin — "API timeout is 30s" from a passing integration test is not the same as a one-session observation with the same text. Treating them identically is a correctness problem, not just a trust signal nicety. Didn''t frame it that precisely in #600 and should have.What is shipped: the retention layer.
TwoLayerBackend(state-backend.ts:922) withpromoteNotes()atstate-backend.ts:1005, called by thesquad notes promoteCLI and Ralph''snotes-promoteheartbeat capability. The write side of Cold→Hot also exists:archive_on_closeis parsed and honored atstate-backend.ts:1042. What isn''t shipped: the relevance-triggered lift when an issue reopens or a Cold file gets touched — and spawn-time tiered loading entirely.spawn.ts:117doesn''t injecthistory.mdat all; reading history is an agent-side tool-call convention, not something the spawn layer handles.--include-colddoesn''t exist in the TypeScript. Your 4-tier model would land on an unfinished foundation — the loading side isn''t there yet.You''re not the only external voice arriving here independently: @idangutman filed #1184 around the same time with a parallel two-tier proposal — an always-loaded index plus on-demand per-topic files. Additive, not competing: his covers the Hot/Warm loading split cleanly; yours adds the Warm/Cold access-cost framing, Cold archive, and trust metadata on Wiki that his deliberately skips. Two independent designs converging on tiered memory makes the case for shipping the runtime.
For tracking: Warm tier and Cold→Hot promotion fit here. Wiki provenance/confidence and cross-agent wiki sharing belong in #640 — I''ll add a comment there linking back to your point. Squad''s spawn API isn''t stable enough yet for a real handshake with AgentRelay''s model; when a spawn-API design doc materializes, I''ll drop a reference here.
fix(sdk,cli): bundle missing skills on init + strip fabricated proven…
fix(sdk,cli): bundle missing skills on init + strip fabricated tiered…
9 remaining items
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Flight
Reason: No module, routing, or role keyword match — routed to Lead/Architect
Source: lead-fallback
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Flight
Reason: No module, routing, or role keyword match — routed to Lead/Architect
Source: lead-fallback
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Flight
Reason: No module, routing, or role keyword match — routed to Lead/Architect
Source: lead-fallback
github-actions commentedon Sep 11, 2026
🔄 Ralph — Auto-Triage
Assigned to: Flight
Reason: No module, routing, or role keyword match — routed to Lead/Architect
Source: lead-fallback
github-actions commentedon Sep 13, 2026
🔄 Ralph — Auto-Triage
Assigned to: architect
Reason: No module, routing, or role keyword match — routed to Lead/Architect
Source: lead-fallback
github-actions commentedon Sep 24, 2026
📋 Assigned to state-storage-dev (State & Storage Engineer)
Issue: #600 — feat: Tiered agent memory — hot/cold/wiki layers for context management
state-storage-dev will pick this up in the next Copilot session.
bradygaster commentedon Nov 5, 2026
Closing during 2.0 board triage (owner decision). The idea is evaluated, with prior art and an opinion, in the roll-up issue #2390. Original text remains here for reference.