tamirdresher · Oct 28, 2026 · Oct 25, 2026 · Oct 27, 2026 · Oct 28, 2026
@@ -39,8 +39,13 @@ The first session is always the least capable. Give the team a few sessions to b
 ## Personal Memory: `history.md`
 Each agent has its own history file at `.squad/agents/{name}/history.md`. After every session, agents append what they learned — architecture decisions, conventions, file paths, user preferences.
 **Only that agent reads its own history.** This means each team member builds specialized knowledge about their domain. Kane learns the auth system inside and out. Dallas masters the component library. Lambert memorizes the test infrastructure.
-### Progressive Summarization
-When an agent's `history.md` exceeds ~12KB, older entries get archived into a summary section. Recent entries stay detailed; older entries condense. This keeps files within a useful context budget without losing accumulated knowledge.
+### Keeping history small (15 KB)
+No code shrinks `history.md` on a timer or after each session. A history over 15 KB gets smaller only in these cases:
+
+- **You run `squad nap`.** For each `history.md` over 15 KB, `squad nap` (or `/nap` in the Squad interactive shell, which `squad` with no arguments opens) keeps the text before the first `##` heading, the `## Core Context` section and the last 5 other `##` sections (3 with `--deep`). It moves the older `##` sections, word for word, to the end of `history-archive.md` in the same folder. It does not summarize. It only splits on `##` headings, so entries written as `###` headings under a single `## Learnings` section count as one section and stay in place.
+- **You ask for it.** You can ask the coordinator to summarize one member's history, for example "summarize Kane's history". An AI agent does the work, so the result varies.
+
+Agents do not load `history-archive.md` at spawn.
 
 ---
 ## Shared Decisions: `decisions.md`
@@ -159,18 +164,18 @@ Skills export and import with your team. Move a trained team to a new repo, and
 
 ---
 ## Knowledge persistence
-Not all knowledge in `.squad/` lasts forever. When files grow large, Squad compacts them to keep performance fast. Here's what persists and what gets summarized:
+Not all knowledge in `.squad/` lasts forever. Large files are compacted to keep spawns fast, but only when you run `squad nap` or an agent does it (see Keeping history small, above). Here's what persists and what gets compacted:
 
 | What | File | Compacted? | Where old content goes | Who reads it |
 |------|------|-----------|----------------------|-------------|
-| Personal history | `history.md` | Yes, at ~12 KB | `history-archive.md` (preserved, read-only) | Owning agent |
-| Shared decisions | `decisions.md` | Yes, when large | `decisions-archive.md` (preserved, not loaded) | All agents |
+| Personal history | `history.md` | Only above 15 KB, when you run `squad nap` or an agent summarizes it | `history-archive.md` in the agent's folder (not loaded at spawn) | Owning agent |
+| Shared decisions | `decisions.md` | Above 20 KB, when you run `squad nap` | `decisions-archive.md` (preserved, not loaded) | All agents |
 | Skills | `skills/{name}/SKILL.md` | Never | Grows indefinitely | All agents |
 | Directives | In `decisions.md` | With decisions | Archived with decisions | All agents |
 | Wisdom | `identity/wisdom.md` | Never | Permanent | All agents |
 | Casting registry | `casting/registry.json` | Never | Permanent | Coordinator |
-| Session logs | `log/*.md` | Never edited | Append-only archive | Read-only |
-| Orchestration logs | `orchestration-log/*.md` | Never edited | Append-only archive | Read-only |
+| Session logs | `log/*.md` | Never edited; `squad nap` deletes files older than 7 days | Deleted, not archived | Read-only |
+| Orchestration logs | `orchestration-log/*.md` | Never edited; `squad nap` deletes files older than 7 days | Deleted, not archived | Read-only |
 
 Knowledge that needs to survive compaction belongs in **skills**. Reusable patterns, code conventions, and technical techniques live here because they grow without limits. Team rules and preferences go in directives (stored in `decisions.md`) — they persist through compaction cycles because directives are preserved when decisions get summarized.
 

@@ -21,14 +21,20 @@ Over multiple sessions, Squad's `.squad/` files grow — agent histories, decisi
 
 ## Nap
 
-**What it does:** Summarizes accumulated work into smaller, more efficient memory files. This is the same as running `/compact` in the CLI or `squad nap` from the command line.
+**What it does:** `squad nap` makes `.squad/` files smaller so agents load less at spawn. It moves old content into archive files and deletes old logs. It does not summarize anything. In the Squad interactive shell (`squad` with no arguments), the same command is `/nap`. It is not the same as `/compact` in GitHub Copilot CLI, which shortens the current chat session and does not touch `.squad/` files.
 
-When you tell the team to "take a nap," each agent:
+A nap does four things:
 
-1. Reviews its `history.md` and other state files
-2. Compresses older entries into concise summaries
-3. Archives verbose detail while preserving key decisions and learnings
-4. Reports how much context was reclaimed
+1. **Agent histories.** Each `agents/{name}/history.md` over 15 KB keeps its `## Core Context` section and its last 5 other `##` sections (3 with `--deep`). Older `##` sections move word for word to `history-archive.md` in the same folder. Entries written as `###` headings under one `## Learnings` section count as one section, so they are not moved.
+2. **Logs.** Files in `log/` and `orchestration-log/` older than 7 days are deleted.
+3. **Decision inbox.** Files left in `decisions/inbox/` are appended to `decisions.md` and deleted.
+4. **Decisions.** When `decisions.md` is over 20 KB, entries older than 30 days move to `decisions-archive.md`. If none are that old, the oldest dated entries move until the file fits. Undated entries always stay. Nap skips this step if git ignores the archive file and does not track it, because the move could never be committed.
+
+It then reports how much space it reclaimed.
+
+Summarizing is a separate job that an AI agent does: you can ask the coordinator to summarize a member's history. Scribe doesn't touch histories; its charter limits it to merging decisions. See [Memory & Knowledge](/squad/docs/concepts/memory-and-knowledge/).
+
+"Team, take a nap" in a chat is a plain request to the coordinator. No built-in rule maps that phrase to `squad nap`, so the coordinator decides what to do. For predictable results, run `squad nap` yourself.
 
 ### Nap ≠ Shutting Down
 
@@ -37,19 +43,19 @@ This is the most common misconception:
 | Action | What happens to `.squad/` files |
 |--------|-------------------------------|
 | **Shutting down Squad** (closing the CLI, killing the process) | Files stay exactly as they are. Nothing is summarized or compacted. |
-| **Nap** (`team, take a nap` or `squad nap`) | Files are actively summarized and compacted. Older entries are archived, working context gets leaner. |
+| **Nap** (`squad nap`, or `/nap` in the Squad interactive shell) | Old history sections and old decisions move to archive files, and old logs are deleted. Nothing is summarized. |
 
-Shutting down Squad every night does **not** perform context hygiene. You must explicitly tell the team to take a nap.
+Shutting down Squad every night does **not** perform context hygiene. Nap never runs on its own: run `squad nap` when you want it.
 
 ### CLI equivalents
 
 ```bash
 squad nap              # Standard context hygiene
-squad nap --deep       # Thorough cleanup with recursive descent
+squad nap --deep       # Same, but keep only the last 3 history sections (default 5)
 squad nap --dry-run    # Preview what would be cleaned up
 ```
 
-In the interactive shell, use `/compact` for the same effect.
+In the Squad interactive shell, use `/nap` with the same flags. In GitHub Copilot CLI (`copilot --agent squad`), run `squad nap` from a terminal. Copilot CLI's own `/compact` shortens the chat session, not `.squad/` files.
 
 ---
 
@@ -106,7 +112,7 @@ This runs both behaviors and gives you a report on how much context was reduced
 team, take a nap
 ```
 
-Compacts and summarizes all agent memory files, reclaiming context space.
+Asks the coordinator to tidy the team's memory files. For a predictable result, run `squad nap`.
 
 ```
 team, reskill

@@ -126,9 +126,14 @@ Each agent has its own history file at `.squad/agents/{name}/history.md`. After
 
 After a few sessions, agents stop asking questions they've already answered.
 
-### Progressive summarization
+### Keeping history small (15 KB)
 
-Histories grow over time. When an agent's `history.md` exceeds ~12KB, older entries are archived into a summary section. Recent entries stay detailed; older entries are condensed. This keeps the file within a useful context budget without losing accumulated knowledge.
+Histories grow over time, and no code shrinks them on its own. A `history.md` over 15 KB gets smaller only when:
+
+- **You run `squad nap`** (or `/nap` in the Squad interactive shell). Each `history.md` over 15 KB keeps its `## Core Context` section and its last 5 other `##` sections (3 with `--deep`). Older `##` sections move word for word to `history-archive.md` in the same folder. Nap does not summarize. Entries written as `###` headings under one `## Learnings` section count as one section, so they stay in place.
+- **You ask for a summary.** You can ask the coordinator to summarize a member's history. An AI agent does the work, so the result varies. Scribe doesn't touch histories: its charter limits it to merging decisions.
+
+Agents do not load `history-archive.md` at spawn. See [Memory & Knowledge](/squad/docs/concepts/memory-and-knowledge/) for details.
 
 ---
 

@@ -75,7 +75,7 @@ prerequisites, all supported methods, and update commands.
 | `squad upstream add\|remove\|list\|sync` | Manage upstream Squad sources | Yes |
 | `copilot --agent squad` | Launch interactive shell explicitly | No |
 | `squad nap` | Context hygiene (compress, prune, archive .squad/ state) | Yes |
-| `squad nap --deep` | Thorough cleanup with recursive descent | Yes |
+| `squad nap --deep` | Same as `squad nap`, but keeps only the last 3 `##` history sections (default 5) | Yes |
 | `squad nap --dry-run` | Preview cleanup actions without changes | Yes |
 | `squad scrub-emails [directory]` | Remove email addresses from Squad state files (default: `.squad/`) | No |
 | `squad state-mcp [--experimental-backend]` | Run the `squad_state` stdio MCP server; pass `--experimental-backend` (or `SQUAD_EXPERIMENTAL_BACKEND=1`) to also expose the 11 experimental `squad_backend_*` conversation tools (transcript/event-log only until a harness is registered) | Yes |
@@ -276,12 +276,12 @@ Agent name matching is **case-insensitive** — `@keaton`, `@Keaton`, and `@KEAT
 ├── skills/              # Reusable knowledge (markdown files)
 │   ├── auth-rate-limiting.md
 │   └── ...
-├── agents/
-│   ├── neo/
-│   │   ├── charter.md   # Role definition, expertise, tools
-│   │   └── history.md   # Accumulated knowledge
-│   └── ...
-└── history-archive/     # Archived old session logs
+└── agents/
+    ├── neo/
+    │   ├── charter.md          # Role definition, expertise, tools
+    │   ├── history.md          # Accumulated knowledge
+    │   └── history-archive.md  # Old history sections moved out by squad nap
+    └── ...
 ```
 
 ### `team.md`