Memory System Improvements — Feedback Welcome #63

Summary

We're making improvements to Squad's memory system in upcoming releases. Some users have noticed issues with how memory scales as projects mature — this issue tracks the planned changes and invites community feedback.

If you've noticed anything off with Squad's memory behavior (decisions getting lost, context seeming stale, agents forgetting things they should know, or context windows feeling bloated), please comment here. Your observations will directly inform the implementation.

What We've Heard

• Memory files (decisions.md, history.md) can grow large as projects mature, consuming significant context window space
• Stale decisions and one-time planning artifacts accumulate without cleanup
• History summarization thresholds may need tuning
• No visibility into how much context budget memory consumes at spawn time

Planned Changes

Phase 1 — Scribe Memory Maintenance (v0.5.x)

• Decisions pruning: Scribe actively identifies and archives stale decision blocks (completed sprints, one-time planning, superseded decisions) to decisions-archive.md
• History compression threshold: Tune the 12KB/~3,000 token threshold for history.md summarization — may need adjustment based on real usage
• Context budget awareness: Track and log how much of the context window memory files consume at spawn time
• Docs update: docs/features/memory.md will be updated alongside every memory system change

Phase 2 — Schema & Self-Healing (v0.5.x)

• team.md schema validation: Parsers that accept multiple header formats (already shipped in PR fix: make team.md member parsing resilient to header variations #60 for ## Members / ## Team Roster)
• Self-healing parsers: Graceful degradation when memory files have unexpected formats rather than hard failures
• Spawn-time memory cap: Target ~25KB max for memory loaded at agent spawn time

Phase 3 — Docs & Validation (v0.6.x)

• Memory health dashboard: Quick way to see memory file sizes, decision count, staleness metrics
• Automated validation: CI check that memory files stay within budget

Phase 4 — Future (v0.7.0+)

• Semantic search: Vector embeddings for decisions and history, so agents find relevant context instead of loading everything
• Per-agent context budgets: Different roles get different memory allocations based on their needs

What We Want Feedback On

1. Have you noticed memory-related issues? Agents forgetting things, decisions seeming stale, or context feeling bloated?
2. How large is your .ai-team/ directory? If you've been using Squad for a while, what does your decisions.md look like size-wise?
3. What matters most to you? Agents remembering everything vs. agents staying fast and focused?
4. Any features you'd want? Memory search, manual pruning tools, visibility into what agents "know"?

Principles

These guide all memory system changes:

• Never lose information — archiving, not deleting. Originals always preserved.
• Memory docs stay in sync — every memory system change includes a docs/features/memory.md update
• Transparency — users should be able to see and understand what their agents remember
• Backward compatible — existing .ai-team/ directories should work without migration

Filed by the Squad team. cc @bradygaster