Chapter 6 · Context Compaction and Context Files

Chapter goals: Understand why pi needs context compaction; master the触发 and工作原理 of auto/manual compaction;掌握 Context Files (AGENTS.md) loading层级 and system prompt定制方法.

6.1 Why Compaction Is Needed

An LLM's context window is有限; and coding sessions天然"eat" context: every file read, every command run, tool results进入 the对话历史. A session持续重构半小时 easily占掉几十万 tokens from read and bash outputs. This brings two问题:

• 硬限制: requests直接失败 after exceeding the model window;
• 软成本: even without exceeding,冗长的历史推高 each request's费用 and延迟.

pi's解法是compaction: summarize earlier conversations into a structured摘要, preserving only the recent messages'原文. It also配有 a配套机制——Context Files (e.g. AGENTS.md) — letting you inject项目级 instructions at极小的固定成本.

6.2 Auto and Manual Triggers

The auto-compaction trigger condition is a simple不等式 (from the official doc compaction.md):

contextTokens > contextWindow - reserveTokens

i.e.立即 compress when "当前上下文 token 数超过 模型窗口 − 预留空间". reserveTokens defaults to 16384, leaving space for the model's reply; you can also adjust in settings (see below). Additionally, when a轮 fails due to exceeding the limit, pi先 compress then retry (overflow recovery).

Manual triggering is typing /compact in interactive mode, with optional instructions to聚焦摘要重点:

# In interactive mode:
/compact                          # Summarize全部旧内容 per the default structure
/compact Focus on: DB migration decisions and unfinished test list

Disabling Auto-Compaction

Setting compaction.enabled to false in settings.json disables auto-compaction; the /compact manual command仍可用. Turning it off during long sessions容易撞上窗口上限; generally not recommended.

6.3 How Compaction Works

Understanding the原理 lets you预判 "what info will be lost". The official流程分五步:

1. Find the cut point: accumulate tokens backwards from the most recent message until reaching keepRecentTokens (default 20000); that position is the cut point;
2. Extract messages: all messages before the cut point (up to the previous compaction boundary) enter the待总结集合;
3. Generate the summary: call the LLM to summarize per a固定结构化格式; if a previous summary exists, pass it as迭代上下文;
4. Append the entry: write the summary and firstKeptEntryId into the session's CompactionEntry;
5. Rebuild context: on the next request, what the LLM sees = system prompt + summary + original messages after the cut point.

Change in the LLM's视角 before and after compaction:

Before: [system] [msg1] [msg2] ... [msg8]        ← all original
After:  [system] [summary] [msg7] [msg8]         ← summary replaces msg1~6

Two细节 worth noting:

• The cut point never落在工具结果上 — tool results must stay together with their tool call; otherwise会出现 "有答案没问题"断裂的上下文;
• Tool results are truncated during serialization: max 2000 characters per tool result;超出部分替换为截断标记 to防止总结请求本身撑爆预算.

6.4 Information Loss Tradeoffs and Tuning

Compaction is本质上有损. The structured summary format保证关键信息不丢:

## Goal          ← what the user要完成
## Constraints & Preferences
## Progress      ← Done / In Progress / Blocked
## Key Decisions ← decisions and rationale
## Next Steps
## Critical Context
<read-files>...</read-files>
<modified-files>...</modified-files>

Note the trailing <read-files> / <modified-files>: pi跨多次压缩累积追踪 file operations; so even if the record of having read a某文件 is compressed away, the fact "this file was touched"仍传递下去.

Parameter tuning example —小窗口 models or long tasks can保留更多近况:

// ~/.pi/agent/settings.json or <project>/.pi/settings.json
{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,   // tokens reserved for the reply
    "keepRecentTokens": 40000 //保留更多近期原文; reduce信息损失
  }
}

The权衡关系很直接: larger keepRecentTokens means the summary needs to覆盖 less内容;损失越小; but each request携带的历史也越贵. Another相关机制 is branch summarization during /tree branch navigation: when switching branches pi asks whether to生成 a summary for the离开分支 and注入 the新分支; also using the above format.

6.5 Context Files: AGENTS.md Loading Hierarchy

If compaction is "dynamic context减法", Context Files are "static context加法". At启动 pi loads and拼接s AGENTS.md (or CLAUDE.md) in this order:

~/.pi/agent/AGENTS.md     ← global personal preferences
+ AGENTS.md on the parent chain   ← walk向上 from cwd一路
+ AGENTS.md in the current directory   ← project conventions

<!-- ~/.pi/agent/AGENTS.md: global; suitable for个人习惯 -->
- Reply in Chinese
- Commit messages follow Conventional Commits

<!-- ./AGENTS.md: project root; suitable for项目约定 -->
- Use pnpm as the package manager; do not use npm/yarn
- Test command: pnpm test; lint command: pnpm lint
- src/legacy/ is待下线 code; do not新增功能 there

Two进阶用法:

• Directory-level override: when a directory has AGENTS.override.md, pi loads it and跳过 that directory's AGENTS.md/CLAUDE.md (other directories concat as usual) — suitable for monorepo中个别子包有特殊规则的场景;
• Disable switch: --no-context-files (-nc)完全关闭加载; useful for对比实验.

6.6 System Prompt Customization and Monorepo Practice

The默认 system prompt can also be整体替换 or appended:

.pi/SYSTEM.md            ← project-level;整体替换 the default system prompt
~/.pi/agent/SYSTEM.md    ← global version
APPEND_SYSTEM.md         ← placing in the same目录 only appends; does not replace

Recommended organization for大型 monorepos is "全局薄、项目厚、子包精准":

my-monorepo/
├── AGENTS.md                  #通用约定: language, commit norms,顶层 commands
├── apps/
│   └── web/
│       └── AGENTS.md          #前端专属: component norms, style方案
├── packages/
│   └── core/
│       ├── AGENTS.md          #核心库专属:公共 API changes需评审
│       └── AGENTS.override.md #若此包规则完全独立;覆盖而非叠加
└── .pi/
    ├── settings.json          # Project-level pi settings
    └── SYSTEM.md              # Optional: project-level system prompt

Paired with the compaction tuning in Section 6.4, the long-task workflow is完整了: Context Files保证"常驻知识"永远在; compaction保证"历史过程"不撑爆窗口.

Chapter Summary

• Auto-compaction condition: contextTokens > contextWindow - reserveTokens (default reserve 16384); manual via /compact [instructions];
• Compaction preserves original text for the最近 keepRecentTokens (default 20000) tokens; earlier content summarizes into a fixed structured summary; file read/write records accumulate across compactions;
• Tool results are never单独切断; truncated to 2000 characters per条 during serialization;
• Context Files concat AGENTS.md in the order global → parent chain → current directory; AGENTS.override.md can覆盖 the所在目录;
• .pi/SYSTEM.md replaces the system prompt; APPEND_SYSTEM.md only appends.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the trigger condition for pi's auto-compaction?

2. Regarding the compaction cut point, which statement is correct?

3. When both AGENTS.md and AGENTS.override.md exist in the same directory, what does pi do?

4. To提高 "最近保留原文" 的量 from the default to 40000 tokens, how to配置?

🛠️ Hands-on Practice

1. In a test project调成 keepRecentTokens to 5000 and have a超长对话 (let pi反复 read large files); observe the compaction触发时机 and summary content.
2. Write an AGENTS.md for one of your真实 projects (at least包含 build/test/lint three commands and two code conventions); restart pi and验证 the agent complies.
3. Do a带指令的手动 compaction with /compact Focus on API design decisions;对比有无指令时摘要的差异.

After completing以上 exercises, proceed to Chapter 7: Settings and Project Trust.