Skip to content

Feature: Hierarchical Long-Term Memory for Squad Agents #1184

Closed

Description

@idangutman

Feature: Hierarchical Long-Term Memory for Squad Agents

Problem

Squad's memory has gaps that worsen as projects grow:

  1. history.md is chronological, not structural — agents know what happened but not how the system works. Architecture knowledge is scattered across summarized sessions.
  2. No hierarchical loading — all context loads at once. A small bug fix gets the same context payload as a major refactor.
  3. Coordinator has no memory — re-discovers user preferences, workflows, and project layout every session.
  4. No ownership boundaries — any agent can read/write any file, risking mental model corruption across domains.

Solution

A two-tier structured memory layer alongside existing files (history.md and decisions.md remain unchanged):

Tier File Size Limit Loaded
1 — Index memory.md ≤10KB Always at spawn
2 — Topics memory-{topic}.md ≤20KB each On demand per task

Index contains: quick reference, architecture overview, core interfaces, topic index, cross-cutting patterns, key decisions, user preferences.

Topic files contain deep knowledge per subsystem (e.g., memory-detection-engines.md, memory-keel.md, memory-kusto-queries.md).

Key Design Decisions

  • Agent ownership — each agent reads/writes only its own memory. Coordinator never writes to agent memory directly; it spawns the owning agent instead.
  • Coordinator memory — separate memory.md at .squad/ level for workflow patterns, user preferences, routing rules.
  • Human override — "Remember that…" / "Forget that…" / "Load memory" commands route through ownership rules.
  • Markdown over database — human-readable, git-versionable, works across all Copilot surfaces (CLI, VS Code, GitHub.com).
  • Purely additive — no changes to history.md, decisions.md, Scribe, progressive summarization, or any existing behavior.

Changes Required

  • Templates: new memory.md and coordinator-memory.md templates, ## Memory section in charter
  • Init/spawn flows: create and load memory files
  • Coordinator: handle remember/forget/load-memory intents, read/write own memory
  • Scribe: read-only access to memory for state preservation
  • Documentation updates

📎 Full RFC: long-term-memory-rfc.md | Integration guide: long-term-memory-install.md

Activity

  1. bradygaster commented on Jun 9, 2026

    @bradygaster
    Collaborator

    Thanks for this! Tiered/hierarchical memory is tracked in #600, #595, and #686 which cover the hot/cold/wiki layer architecture. Closing as duplicate — please follow those issues for updates.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions