docs: 更新文档

2026-06-15 12:55:51 +00:00 · 2026-04-01 16:11:37 +08:00
parent 503a40f46b
commit 7d5271e63e
8 changed files with 1139 additions and 259 deletions
--- a/docs/context/compaction.mdx
+++ b/docs/context/compaction.mdx
@@ -1,68 +1,239 @@
 ---
-title: "上下文压缩 - Compaction 优雅遗忘机制"
-description: "详解 Claude Code 上下文压缩策略：当对话 token 接近 200K 上限时，如何通过 Compaction 机制智能压缩历史消息，保留关键信息。"
-keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩", "上下文窗口"]
+title: "上下文压缩 - Compaction 三层策略与边界机制"
+description: "深度解析 Claude Code 上下文压缩的完整实现：Session Memory 压缩、传统 API 摘要压缩、MicroCompact 局部压缩三层策略，以及 CompactBoundary 消息、工具对保持、PTL 紧急降级等关键机制。"
+keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩", "上下文窗口", "MicroCompact"]
 ---

-{/* 本章目标：解释 Compaction 机制的设计和策略 */}
+{/* 本章目标：从源码层面剖析压缩的三层策略、边界机制和关键常量 */}

-## 为什么需要压缩
+## 压缩的触发时机

-每次 API 调用的 token 有上限（通常 200K）。一场长时间的编程对话可能产生：
+上下文压缩不是单一操作，而是**三层递进**的策略系统，对应不同的触发条件和严重程度：

- 大量的文件内容（AI 读了几十个文件）
- 长篇的命令输出（构建日志、测试结果）
- 往返的对话历史
+| 层级 | 触发条件 | 实现位置 | 是否需要 API 调用 |
+|------|---------|---------|:---:|
+| **MicroCompact** | 单个工具输出过长 | `microCompact.ts` | 否 |
+| **Session Memory Compact** | 自动压缩触发（需 feature flag） | `sessionMemoryCompact.ts` | 否 |
+| **传统 API 摘要** | 手动 `/compact` 或 SM 不可用时的自动回退 | `compact.ts` | 是 |

-不压缩的话，很快就会撞到 token 上限，对话被迫终止。
+### 压缩入口的优先级链

-<Frame caption="上下文压缩前后对比">
-  <img src="/docs/images/compaction.png" alt="上下文压缩示意图" />
-</Frame>
+源码路径：`src/commands/compact/compact.ts`

-## 压缩的策略
+当用户执行 `/compact` 或系统触发自动压缩时，压缩命令按以下优先级尝试：

-Claude Code 提供了多层压缩机制：
+```typescript
+// compact.ts:55-99 — 简化后的优先级链
+if (!customInstructions) {
+  const sessionMemoryResult = await trySessionMemoryCompaction(messages, ...)
+  if (sessionMemoryResult) return sessionMemoryResult      // 优先：SM 压缩
+}

-<AccordionGroup>
-  <Accordion title="自动压缩">
-    当 token 接近上限时，系统自动触发压缩。AI 生成一份当前对话的**摘要**，替换掉早期的详细消息。效果就像人类的"记忆"——记住要点，忘记细节。
-  </Accordion>
-  <Accordion title="手动压缩">
-    用户可以随时通过 `/compact` 命令主动触发压缩。可以附带提示语（如 `/compact 聚焦在认证模块的修改上`），引导 AI 保留特定信息。
-  </Accordion>
-  <Accordion title="Micro Compact">
-    更细粒度的局部压缩——不是压缩整个对话，而是压缩某些特别长的工具输出（比如一个 5000 行的测试日志）。
-  </Accordion>
-</AccordionGroup>
+if (reactiveCompact?.isReactiveOnlyMode()) {
+  return await compactViaReactive(messages, ...)            // 次选：Reactive 压缩
+}

-## 压缩边界
-
-压缩后，系统在消息历史中插入一个"边界标记"。后续的 API 调用只发送边界之后的消息：
-
-```
-[早期的 50 条消息] ← 被压缩
-[压缩摘要边界] ← 一段浓缩的摘要
-[后续的 10 条消息] ← 正常发送
+// 兜底：传统 API 摘要
+const microcompactResult = await microcompactMessages(messages, context)
+const messagesForCompact = microcompactResult.messages
+// → 调用 AI 模型生成摘要
 ```

-这个设计保证了：
- 压缩后的摘要为 AI 提供了历史上下文
- 新的对话不受旧消息的 token 负担
- 用户无感知——对话继续自然进行
+注意：SM 压缩不支持自定义指令（`/compact 聚焦在认证模块`），有自定义指令时直接走传统路径。

-## 压缩前后的 Hooks
+## 第一层：MicroCompact — 局部压缩

-压缩是一个可能丢失信息的操作，因此系统允许用户在压缩前后执行自定义脚本：
+源码路径：`src/services/compact/microCompact.ts`

- **Pre-compact Hook**：压缩前执行，可以标记"这些信息不能丢"
- **Post-compact Hook**：压缩后执行，可以验证关键信息是否保留
+MicroCompact 不压缩整个对话，而是**清除旧工具输出的内容**。它维护一个白名单：

-## 什么信息会被保留
+```typescript
+const COMPACTABLE_TOOLS = new Set([
+  'Read',      // 文件读取
+  'Bash',      // 命令输出
+  'Grep',      // 搜索结果
+  'Glob',      // 文件列表
+  'WebSearch', // 搜索结果
+  'WebFetch',  // 网页内容
+  'Edit',      // 编辑输出
+  'Write',     // 写入输出
+])
+```

-压缩不是简单的截断，AI 会智能地决定保留什么：
+替换策略：将超过时间窗口的工具输出内容替换为 `[Old tool result content cleared]`。这不是简单的截断——原始内容仍保留在 JSONL transcript 中，只是不再发送给 API。

- 用户的核心需求和目标
- 重要的决策和原因
- 当前工作的状态（改了哪些文件、做到哪一步）
- 之前犯过的错误（避免重蹈覆辙）
+MicroCompact 还有一个**时间衰减配置**（`timeBasedMCConfig.ts`）：越旧的工具输出越容易被清除，最近的优先保留。
+
+### 图片和文档的特殊处理
+
+```typescript
+const IMAGE_MAX_TOKEN_SIZE = 2000
+```
+
+图片 block 如果超过 2000 token 估算值，也会被 MicroCompact 清除。PDF document block 同理。
+
+## 第二层：Session Memory Compact — 无 API 调用的压缩
+
+源码路径：`src/services/compact/sessionMemoryCompact.ts`
+
+当 `tengu_session_memory` + `tengu_sm_compact` 两个 feature flag 启用时，系统优先使用 Session Memory 进行压缩——**不需要调用摘要模型**，直接使用已经提取好的 Session Memory 作为对话摘要。
+
+### 保留窗口的计算
+
+```typescript
+// sessionMemoryCompact.ts:324-397
+export function calculateMessagesToKeepIndex(messages, lastSummarizedIndex) {
+  const config = getSessionMemoryCompactConfig()
+  // 默认: minTokens=10K, minTextBlockMessages=5, maxTokens=40K
+
+  let startIndex = lastSummarizedIndex + 1
+  // 从 lastSummarizedIndex 向前扩展，直到满足两个下限或命中上限
+  for (let i = startIndex - 1; i >= floor; i--) {
+    totalTokens += estimateMessageTokens([msg])
+    if (hasTextBlocks(msg)) textBlockMessageCount++
+    startIndex = i
+    if (totalTokens >= config.maxTokens) break
+    if (totalTokens >= config.minTokens && textBlockMessageCount >= config.minTextBlockMessages) break
+  }
+  return adjustIndexToPreserveAPIInvariants(messages, startIndex)
+}
+```
+
+这个算法确保压缩后保留的消息窗口满足：
+- 至少 10,000 token（有上下文深度）
+- 至少 5 条包含文本的消息（有对话连续性）
+- 最多 40,000 token（不会太大又触发下一次压缩）
+
+### 工具对完整性保护
+
+`adjustIndexToPreserveAPIInvariants()` 是压缩中一个**关键的正确性保证**：
+
+API 要求每个 `tool_result` 都有对应的 `tool_use`，反之亦然。如果压缩恰好切在一条 `tool_result` 消息处，会导致 API 报错。
+
+```typescript
+// sessionMemoryCompact.ts:232-314
+// Step 1: 向前扫描，找到所有被保留消息中 tool_result 引用的 tool_use
+// Step 2: 向前扫描，找到与被保留 assistant 消息共享 message.id 的 thinking block
+// 两种情况都需要将 startIndex 向前移动
+```
+
+流式传输会将一个 assistant 消息拆分为多条存储记录（thinking、tool_use 等各有独立 uuid 但共享 `message.id`），这增加了边界情况的复杂度。
+
+## 第三层：传统 API 摘要压缩
+
+源码路径：`src/services/compact/compact.ts`
+
+当 SM 压缩不可用时，系统回退到传统方式：调用 AI 模型生成对话摘要。
+
+### 压缩前处理
+
+发送给摘要模型之前，消息会经过多层预处理：
+
+```typescript
+// compact.ts:147-202
+const stripped = stripImagesFromMessages(messages)   // 图片→[image] 文字标记
+const stripped2 = stripReinjectedAttachments(stripped) // 移除会被重新注入的附件
+```
+
+图片被替换为 `[image]` 标记，防止摘要 API 调用本身也触发 prompt-too-long 错误。
+
+### 压缩后的重新注入
+
+压缩后，系统会从摘要中**重新注入关键上下文**：
+
+```typescript
+// compact.ts:124-132
+export const POST_COMPACT_TOKEN_BUDGET = 50_000          // 总预算
+export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5        // 最多恢复 5 个文件
+export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000     // 每文件 5K token
+export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000    // 每技能 5K token
+export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000    // 技能总预算 25K
+```
+
+这 50K token 的重新注入预算用于：
+1. 恢复最近读取的文件内容（最多 5 个文件，每个截断到 5K token）
+2. 恢复已激活的技能指令（每个技能截断到 5K token，总计 25K）
+3. 重新注入 CLAUDE.md 内容
+4. 恢复 MCP 工具发现结果
+
+## CompactBoundary：压缩的边界标记
+
+源码路径：`src/utils/messages.ts`（`createCompactBoundaryMessage`）
+
+每次压缩后，系统在消息流中插入一条 `SystemCompactBoundaryMessage`：
+
+```typescript
+type SystemCompactBoundaryMessage = {
+  type: 'system'
+  message: {
+    type: 'compact_boundary'
+    compactMetadata: {
+      compactType: 'auto' | 'manual' | 'micro'
+      preCompactTokenCount: number
+      lastUserMessageUuid: string
+      preCompactDiscoveredTools?: string[]
+    }
+  }
+}
+```
+
+后续所有操作只处理**最后一条 boundary 之后**的消息：
+
+```typescript
+// messages.ts
+export function getMessagesAfterCompactBoundary(messages: Message[]): Message[] {
+  const lastBoundary = messages.findLastIndex(m => isCompactBoundaryMessage(m))
+  return lastBoundary >= 0 ? messages.slice(lastBoundary + 1) : messages
+}
+```
+
+### Preserved Segment 注解
+
+boundary 消息上还附加了 `preservedSegment` 注解，记录哪些消息被保留而非压缩：
+
+```typescript
+// compact.ts — annotateBoundaryWithPreservedSegment
+boundaryMarker.compactMetadata.preservedSegment = {
+  summaryMessageUuid: string
+  preservedMessageUuids: string[]
+}
+```
+
+这在会话恢复时帮助加载器正确重建消息链，避免重复压缩已保留的消息。
+
+## PTL 紧急降级：Prompt Too Long
+
+当压缩后仍然超出 token 限制（`PROMPT_TOO_LONG` 错误），系统会进入紧急降级路径：
+
+1. **Reactive Compact**：`reactiveCompactOnPromptTooLong()` 尝试更激进的压缩
+2. **截断重试**：如果 reactive 也失败，`truncateHeadForPTLRetry()` 直接截断最早的消息
+3. 放弃并报错
+
+Reactive Compact 目前在反编译版本中是 stub（`isReactiveOnlyMode() → false`），表明这是 Anthropic 内部的实验性功能。
+
+## 压缩的 Hook 机制
+
+压缩前后可以执行自定义 Hook：
+
+- **Pre-compact Hook**（`executePreCompactHooks`）：在压缩前执行，可以注入"必须保留"的标记
+- **Post-compact Hook**（`executePostCompactHooks`）：在压缩后执行，可以验证关键信息是否保留
+- **Session Start Hook**（`processSessionStartHooks('compact')`）：SM 压缩使用此 Hook 恢复 CLAUDE.md 等上下文
+
+Hook 结果以 `HookResultMessage` 的形式附加到压缩结果中，确保用户的自定义逻辑在压缩过程中被尊重。
+
+## Snip Compact（实验性）
+
+源码路径：`src/services/compact/snipCompact.ts`（stub）
+
+Snip Compact 是另一种实验性压缩策略，在反编译版本中为空壳实现。从 stub 的类型签名推断：
+
+```typescript
+snipCompactIfNeeded(messages, options?: { force?: boolean }) → {
+  messages: Message[]
+  executed: boolean
+  tokensFreed: number
+  boundaryMessage?: Message
+}
+```
+
+它似乎是一种**更细粒度的消息级裁剪**（snip = 剪切），可能是对单条消息的进一步压缩，而非整个对话。`shouldNudgeForSnips()` 和 `SNIP_NUDGE_TEXT` 暗示它可能会提示用户触发。
--- a/docs/context/project-memory.mdx
+++ b/docs/context/project-memory.mdx
@@ -1,59 +1,226 @@
 ---
-title: "项目记忆系统 - AI 跨对话记忆机制"
-description: "解析 Claude Code 项目记忆系统：CLAUDE.md 文件、用户偏好存储和上下文缓存如何让 AI 跨对话记住项目特性和个人偏好。"
-keywords: ["项目记忆", "CLAUDE.md", "AI 记忆", "跨对话", "上下文缓存"]
+title: "项目记忆系统 - 文件级跨对话记忆架构"
+description: "深度解析 Claude Code 记忆系统：基于文件的持久化存储、MEMORY.md 索引结构、四类型分类法、Sonnet 智能召回、Session Memory 压缩集成。"
+keywords: ["项目记忆", "MEMORY.md", "AI 记忆", "跨对话", "自动记忆", "memdir"]
 ---

-{/* 本章目标：解释记忆系统如何让 AI 变得'有记忆' */}
+{/* 本章目标：从源码层面剖析记忆系统的存储架构、召回机制和注入链路 */}

-## AI 的记忆困境
+## 记忆系统的存储架构

-大语言模型没有真正的记忆。每次新对话，它都是一张白纸。用户不得不反复解释"我的项目用 Bun 不用 Node"、"commit 消息用中文"。
+源码路径：`src/memdir/paths.ts`、`src/memdir/memdir.ts`

-## 记忆系统的解决方案
+Claude Code 的记忆系统是**纯文件**的——没有数据库、没有向量存储，只有 Markdown 文件和目录结构。

-Claude Code 通过一个基于文件的持久化记忆系统来模拟"跨会话记忆"：
+### 目录布局

-<CardGroup cols={2}>
-  <Card title="用户记忆" icon="user">
-    关于用户的信息：角色、偏好、技术背景
-  </Card>
-  <Card title="反馈记忆" icon="message">
-    用户对 AI 行为的纠正和肯定
-  </Card>
-  <Card title="项目记忆" icon="folder">
-    项目中的非代码信息：谁负责什么、截止日期
-  </Card>
-  <Card title="参考记忆" icon="link">
-    外部资源的位置：Issue tracker、Dashboard URL
-  </Card>
-</CardGroup>
+```
+~/.claude/projects/<sanitized-git-root>/memory/
+├── MEMORY.md                    ← 入口索引（每次对话加载）
+├── user_role.md                 ← 用户记忆
+├── feedback_testing.md          ← 反馈记忆
+├── project_mobile_release.md    ← 项目记忆
+├── reference_linear_ingest.md   ← 参考记忆
+└── logs/                        ← KAIROS 模式：每日日志
+    └── 2026/
+        └── 04/
+            └── 2026-04-01.md
+```

-## 记忆的读写时机
+路径解析链路（`getAutoMemPath()`）：
+1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` 环境变量（Cowork SDK 全路径覆盖）
+2. `autoMemoryDirectory` 设置（仅限 `policySettings`/`localSettings`/`userSettings`——**故意排除** `projectSettings`，防止恶意仓库将记忆路径指向 `~/.ssh`）
+3. 默认：`<memoryBase>/projects/<sanitized-git-root>/memory/`

-| 时机 | 动作 |
-|------|------|
-| 每次对话开始 | 加载记忆索引（MEMORY.md），相关记忆注入 System Prompt |
-| 用户纠正 AI | AI 自动判断是否值得记住，写入反馈记忆 |
-| 用户说"记住这个" | 立即保存到对应类型的记忆文件 |
-| 用户说"忘掉这个" | 找到并删除对应的记忆条目 |
-| 记忆可能过期时 | 使用前先验证（文件还在？函数还存在？），过期则更新或删除 |
+同一个 Git 仓库的所有 worktree 共享一个记忆目录（通过 `findCanonicalGitRoot()` 找到真正的 `.git` 根）。

-## 记忆 vs 代码注释 vs CLAUDE.md
+### MEMORY.md 索引

-| | 记忆 | 代码注释 | CLAUDE.md |
-|---|---|---|---|
-| 存储位置 | `~/.claude/` 目录 | 代码文件中 | 项目目录中 |
-| 谁能看到 | 只有当前用户 | 所有开发者 | 所有使用 Claude Code 的人 |
-| 适合存什么 | 个人偏好、非公开的上下文 | 代码逻辑解释 | 项目约定、开发指南 |
-| 跨项目 | 是 | 否 | 否 |
+`MEMORY.md` 是记忆的入口索引，每次对话都完整加载到上下文中：

-## 不该存什么
+```typescript
+// memdir.ts:35-38
+export const ENTRYPOINT_NAME = 'MEMORY.md'
+export const MAX_ENTRYPOINT_LINES = 200
+export const MAX_ENTRYPOINT_BYTES = 25_000
+```

-记忆系统明确规定了不应存储的内容：
+索引有**双重上限**：200 行 AND 25KB。超过任何一条都会被 `truncateEntrypointContent()` 截断并追加警告。设计原因：p97 的索引文件用 200 行就能覆盖，但有些索引条目特别长（p100 观测到 197KB/200 行），字节上限捕捉这种长行异常。

- 代码结构和架构（读代码就知道）
- git 历史（`git log` 就能查）
- 调试方案（修复已在代码中）
- CLAUDE.md 里已有的内容（避免重复）
- 临时性任务状态（用任务系统）
+索引条目格式：
+```markdown
+- [Title](file.md) — one-line hook
+```
+
+每条一行，~150 字符以内。`MEMORY.md` 本身没有 frontmatter——它只是一个链接列表，不是记忆内容。
+
+## 四类型分类法
+
+源码路径：`src/memdir/memoryTypes.ts`
+
+记忆被约束为一个**封闭的四类型系统**，每种类型有明确的 `<when_to_save>`、`<how_to_use>` 和 `<body_structure>` 规范：
+
+| 类型 | 存储内容 | 典型触发 |
+|------|---------|---------|
+| **user** | 用户角色、偏好、技术背景 | "我是数据科学家"、"我写了十年 Go" |
+| **feedback** | 用户对 AI 行为的纠正和确认 | "别 mock 数据库"、"单 PR 更好" |
+| **project** | 非代码可推导的项目上下文 | "合并冻结从周四开始"、"auth 重写是合规要求" |
+| **reference** | 外部系统指针 | "pipeline bugs 在 Linear INGEST 项目" |
+
+关键设计约束：**只存储无法从当前项目状态推导的信息**。代码架构、文件路径、git 历史都可以实时获取，不需要记忆。
+
+### 反馈类型的双通道捕获
+
+`feedback` 类型的 `when_to_save` 指令特别强调：
+
+> Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.
+
+这意味着 AI 不仅在用户说"不要这样做"时保存，也在用户说"对，就是这样"时保存。后一种更难捕捉，但同等重要——它防止 AI 的行为随时间漂移。
+
+### 每条记忆的 Frontmatter 格式
+
+```markdown
+---
+name: {{memory name}}
+description: {{one-line description — 用于未来判断相关性}}
+type: {{user, feedback, project, reference}}
+---
+
+{{memory content — feedback/project 类型建议包含 **Why:** 和 **How to apply:** 行}}
+```
+
+`description` 字段是关键：它不是给人读的摘要，而是给 AI 召回系统做相关性判断的搜索关键词。
+
+## 智能召回机制
+
+源码路径：`src/memdir/findRelevantMemories.ts`、`src/memdir/memoryScan.ts`
+
+不是所有记忆都适合每次对话。系统使用一个**轻量级 Sonnet 侧查询**来筛选最相关的记忆。
+
+### 召回流程
+
+```
+用户消息 → findRelevantMemories(query, memoryDir)
+  ├── scanMemoryFiles() — 扫描所有记忆文件的 frontmatter
+  ├── selectRelevantMemories() — Sonnet 侧查询，从清单中选出 ≤5 条
+  └── 返回 [{path, mtimeMs}, ...]
+```
+
+核心是 `selectRelevantMemories()` 函数，它调用 `sideQuery()`（一个独立的轻量 API 调用）：
+
+```typescript
+// findRelevantMemories.ts:98-121
+const result = await sideQuery({
+  model: getDefaultSonnetModel(),  // 用 Sonnet 做筛选（非主模型）
+  system: SELECT_MEMORIES_SYSTEM_PROMPT,
+  messages: [{
+    role: 'user',
+    content: `Query: ${query}\n\nAvailable memories:\n${manifest}${toolsSection}`
+  }],
+  max_tokens: 256,
+  output_format: { type: 'json_schema', schema: { ... } },
+})
+```
+
+### 近期工具去噪
+
+当 AI 正在使用某个工具时，召回该工具的使用文档是噪音（对话中已有工作上下文）。`recentTools` 参数让召回系统跳过这些记忆：
+
+```typescript
+// findRelevantMemories.ts:92-95
+const toolsSection = recentTools.length > 0
+  ? `\n\nRecently used tools: ${recentTools.join(', ')}`
+  : ''
+```
+
+System Prompt 明确指示："如果已提供最近使用的工具列表，不要选择该工具的使用参考或 API 文档。**仍然要选择**关于这些工具的警告、陷阱或已知问题——这正是使用时最关键的信息。"
+
+### 已展示去重
+
+`alreadySurfaced` 参数过滤之前轮次已展示过的文件路径，让 Sonnet 的 5 槽预算花在新的候选上，而不是重复召回同一文件。
+
+## 记忆注入 System Prompt 的链路
+
+源码路径：`src/memdir/memdir.ts` → `src/context.ts`
+
+`loadMemoryPrompt()` 是记忆注入的入口，每会话调用一次（通过 `systemPromptSection('memory', ...)` 缓存）：
+
+```typescript
+// memdir.ts:419-507
+export async function loadMemoryPrompt(): Promise<string | null> {
+  // 优先级：KAIROS 日志模式 → TEAMMEM 组合模式 → 纯自动记忆
+  if (feature('KAIROS') && autoEnabled && getKairosActive()) {
+    return buildAssistantDailyLogPrompt(skipIndex)
+  }
+  if (feature('TEAMMEM') && teamMemPaths!.isTeamMemoryEnabled()) {
+    return teamMemPrompts!.buildCombinedMemoryPrompt(...)
+  }
+  if (autoEnabled) {
+    return buildMemoryLines('auto memory', autoDir, ...).join('\n')
+  }
+  return null
+}
+```
+
+注入时机：`context.ts` 中 `getSystemContext()` 调用时，记忆 Prompt 作为 system prompt 的一个 section 被组装。`MEMORY.md` 的内容作为 **user context message** 注入（而非 system prompt），这样可以利用 Prompt Cache 的 prefix 共享。
+
+## KAIROS 模式：每日日志
+
+源码路径：`src/memdir/memdir.ts`（`buildAssistantDailyLogPrompt`）
+
+长期运行的 assistant 会话使用不同的记忆策略：
+
+- **标准模式**：AI 维护 `MEMORY.md` 作为实时索引 + 独立记忆文件
+- **KAIROS 模式**：AI 只往日期文件追加日志（`logs/YYYY/MM/YYYY-MM-DD.md`），不做重组
+
+```typescript
+// 日志路径模式（非字面路径——因为 Prompt 被缓存）
+const logPathPattern = join(memoryDir, 'logs', 'YYYY', 'MM', 'YYYY-MM-DD.md')
+```
+
+一个独立的夜间 `/dream` 技能负责将日志蒸馏为主题文件 + `MEMORY.md` 索引。
+
+## 记忆漂移防御
+
+源码路径：`src/memdir/memoryTypes.ts`（`TRUSTING_RECALL_SECTION`）
+
+记忆可能过期。系统在 Prompt 中设置了一个专门的 section "Before recommending from memory"：
+
+```
+A memory that names a specific function, file, or flag is a claim
+that it existed *when the memory was written*. It may have been
+renamed, removed, or never merged. Before recommending it:
+
+- If the memory names a file path: check the file exists.
+- If the memory names a function or flag: grep for it.
+```
+
+这个 section 的标题经过 A/B 测试验证："Before recommending from memory"（行动导向）比 "Trusting what you recall"（抽象描述）效果好（3/3 vs 0/3）。
+
+### 忽略记忆的严格语义
+
+```
+If the user says to *ignore* or *not use* memory:
+proceed as if MEMORY.md were empty.
+Do not apply remembered facts, cite, compare against,
+or mention memory content.
+```
+
+这解决了 AI 的一个常见反模式：用户说"忽略关于 X 的记忆"，AI 虽然正确识别了代码但仍然加上"不像记忆中说的 Y"——这不是"忽略"，而是"承认然后覆盖"。
+
+## Session Memory 与压缩的联动
+
+源码路径：`src/services/compact/sessionMemoryCompact.ts`
+
+记忆系统与上下文压缩有深度集成。当 `tengu_session_memory` 和 `tengu_sm_compact` 两个 feature flag 同时开启时，压缩优先使用 Session Memory 而非传统摘要：
+
+```typescript
+// sessionMemoryCompact.ts:57-61
+const DEFAULT_SM_COMPACT_CONFIG = {
+  minTokens: 10_000,           // 压缩后至少保留 10K token
+  minTextBlockMessages: 5,     // 至少保留 5 条文本消息
+  maxTokens: 40_000,           // 最多保留 40K token
+}
+```
+
+SM-compact 不调用压缩 API（没有摘要模型），而是直接使用已有的 Session Memory 作为摘要——更快、更便宜、且不会丢失信息。