Skip to content

Docs say history is summarized at ~12 KB; the code uses 15 KB and squad nap archives without summarizing #2323

Closed

Description

@joslat

The docs describe history compaction with the wrong size and the wrong mechanism.

Size. concepts/memory-and-knowledge.md:43 and :166 and features/memory.md:120 say a history.md is compacted at "~12KB". The code and prompts use 15 KB: HISTORY_THRESHOLD = 15 * 1024 in packages/squad-cli/src/cli/core/nap.ts:49, 15,360 bytes in after-agent-reference.md, "exceed 15KB" in the nap skill, and 15KB in features/tiered-memory.md:12. "12 KB" doesn't appear anywhere in code.

Mechanism. The same pages say older entries "get archived into a summary section", with recent entries detailed and older ones condensed. That's not what happens:

  • squad nap is the only code that shrinks a history, and it only runs when someone runs it.
  • It doesn't summarize. It keeps the text before the first ##, the ## Core Context section and the last 5 other ## sections (3 with --deep), and moves the older ## sections word for word to history-archive.md (nap.ts:160-249).
  • Agents don't load history-archive.md at spawn.

features/context-hygiene.md adds a few more mismatches:

  • It says a nap "summarizes accumulated work" and is "the same as running /compact in the CLI" (:24). /compact is Copilot CLI's own command for shortening the chat session, and it doesn't touch .squad/ files.
  • It says that when you tell the team to "take a nap", each agent compresses its entries into summaries (:26-30). No built-in rule maps that phrase to squad nap.
  • It describes --deep as "recursive descent" (:48). It only keeps 3 sections instead of 5.

The log rows in the memory table also say logs are never edited and archived. In fact squad nap deletes log files older than 7 days (nap.ts:51).

Suggested fix

Docs only: correct the threshold to 15 KB, describe what squad nap actually does (history trim, log pruning, inbox merge, decision archival) and that it's manual, separate it from asking an agent to summarize, and fix the --deep description and the cli.md tree.

I have a PR with the docs changes.

Activity

  1. added a commit that references this issue on Oct 28, 2026
    423c43e
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