核心内容：让 AI 记住该记住的，忘记该忘记的

前面我们学习了上下文工程学，知道如何让 AI 在当前会话中准确理解项目。但有一个根本挑战始终存在：Claude Code 的每次会话都是无状态的——新对话开始时上下文窗口是空白的，前一个会话中建立的认知、确认的决策、积累的经验，全都消失了。本集将深入探讨如何管理跨会话状态，让 AI “记住该记住的，忘记该忘记的”。

1. 问题的本质：会话无状态与记忆需求

1.1 每次对话都是从零开始

会话 1（周一上午）：

你：我们的用户认证逻辑在 src/services/auth.ts，请修复 token 刷新 Bug

AI：[读取 auth.ts，理解了整个认证流程，花 15 分钟定位并修复了 Bug]

你：太好了，这个修复方案我们确认了，用的是 refreshToken 轮换策略

会话 2（周一下午）：

你：继续上午的工作，请给认证模块添加 OAuth 支持

AI：让我先了解一下项目的认证逻辑...[重新读取 auth.ts，重新理解认证流程]

[又花了 10 分钟重新建立上下文]

[不知道你们上午确认了 refreshToken 轮换策略]

[提出与上午决策冲突的方案]

你：不对，我们上午不是说好用 refreshToken 轮换吗？

AI：抱歉，我没有那个对话的上下文...

1.2 哪些信息需要跨会话保留？

信息类型	示例	重要性
架构决策	确认使用 refreshToken 轮换策略	�� 关键
任务进度	重构进度：已完成模块 A，正在处理模块 B	�� 关键
已知问题	API 限流问题待解决，已提交工单 #4567	�� 重要
待办事项	下周需要升级 Drizzle ORM 到最新版本	�� 重要
对话细节	上一次你是怎么向我解释这个 Bug 的	�� 可选
中间推理	AI 在定位问题时排除了哪些可能性	�� 可选

1.3 记忆持久化的核心原则

记忆系统的目标不是“记住一切”，而是“在该记住的时候记住对的东西”。过度记忆和完全失忆一样危险。

完全失忆：

每次对话从零开始 → 重复建立上下文 → 浪费时间 → 决策不一致

过度记忆：

记住所有对话细节 → 上下文窗口被历史填满 → 新任务空间不足 → 信息噪音化

理想状态：

记住架构决策和任务进度 → 忘记对话细节和中间推理 → 新会话精准衔接

2. CLAUDE.md 的 @import 语法：模块化记忆管理

2.1 什么是 @import？

CLAUDE.md 支持使用@path/to/file语法引用其他文件，被引用的文件会在加载时内联展开。这让你可以将项目规范按模块拆分，主文件只保留索引。

主 CLAUDE.md（索引）：

@.claude/rules/tech-stack.md

@.claude/rules/code-style.md

@.claude/rules/architecture.md

加载时自动展开为：

[tech-stack.md 的内容]

[code-style.md 的内容]

[architecture.md 的内容]

2.2 配置方式

主 CLAUDE.md：

# 项目：电商平台

索引

详细规范请参考以下文件：

@.claude/rules/tech-stack.md

@.claude/rules/code-style.md

@.claude/rules/architecture.md

@.claude/rules/testing.md

全局约束

• YOU MUST 使用 pnpm，禁止 npm 或 yarn
• YOU MUST NOT 使用 any 类型
• 所有 API 端点返回{ data, error, meta }格式

被引用的文件（.claude/rules/tech-stack.md）：

# 技术栈规范

核心技术

• Next.js 15 App Router + React 19
• TypeScript 5.7（strict 模式）
• Tailwind CSS 4
• Drizzle ORM + PostgreSQL

包管理器

• 强制使用 pnpm
• 禁止 npm install 或 yarn add

运行时

• Node.js 20+
• 部署平台：Vercel

2.3 @import 的关键规则

规则	说明
最大递归深度	5 层（引用文件可引用其他文件，最多嵌套 5 层）
路径解析	相对于当前 CLAUDE.md 文件所在目录
循环引用	自动检测并中断，不会无限循环
加载时机	会话启动时一次性展开，不延迟加载

2.4 使用场景

场景	配置方式
大型 Monorepo	主 CLAUDE.md 包含全局约束 + 引用各 package 的规范
多团队协作	每个团队维护自己的规范文件，主文件只做索引
长期项目	按领域拆分（前端、后端、数据库、测试），便于独立维护
新人入职	主文件保持简洁，新人按索引逐步了解各模块规范

2.5 @import 的局限性

局限	说明	解决方式
一次性展开	引用的文件在启动时全部加载，不按需	用.claude/rules/+paths实现按需加载
静态内容	只能引用静态文件，无法动态生成	动态上下文用 Hooks 注入
无法记录运行时状态	不能记录“今天上午我们决定用什么方案”	用 Hooks 实现运行时状态持久化

3. Hooks 记忆法：实战验证的跨会话状态管理

3.1 三种关键 Hook 的记忆职责

这是经过大量实践验证的记忆管理方案，通过三个关键 Hook 覆盖会话生命周期的记忆需求：

┌─────────────────────────────────────────────────────────┐

│ 会话生命周期 │

│ │

│ SessionStart → 加载记忆 → 恢复上下文 │

│ ↓ │

│ [AI 在工作中...] │

│ ↓ │

│ PreCompact → 保存状态 → 防止压缩时丢失关键信息 │

│ ↓ │

│ [AI 继续工作...] │

│ ↓ │

│ Stop → 持久化记忆 → 记录经验、决策、未完成任务 │

│ │

│ 下次 SessionStart → 加载上次 Stop 保存的记忆 │

└─────────────────────────────────────────────────────────┘

3.2 PreCompact Hook：防止压缩时丢失关键信息

上下文压缩（/compact）会精简对话历史，可能丢失重要信息。PreCompact Hook 在压缩前自动保存关键状态。

配置（.claude/settings.json）：

{

"hooks": {

"PreCompact": [

{

"matcher": "",

"hooks": [

{

"type": "command",

"command": "/bin/bash .claude/hooks/save-state.sh"

}

]

}

]

}

}

保存状态脚本（.claude/hooks/save-state.sh）：

#!/bin/bash

# 在上下文压缩前，保存当前任务状态

STATE_DIR=".claude/state"

mkdir -p "$STATE_DIR"

从 stdin 获取当前会话信息

INPUT=$(cat)

SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

让 AI 总结当前状态并保存

注意：这个脚本在压缩前运行，此时 AI 还有完整上下文

cat > "$STATE_DIR/last-state.md" << 'SAVEPOINT'

会话状态快照

保存时间：$

当前任务

[AI 会在压缩前自动填充当前正在执行的任务和进度]

已确认的决策

[AI 会记录本次会话中确认的架构决策]

待解决的问题

[AI 会记录尚未解决、需要继续跟进的问题]

关键上下文

[AI 会记录后续任务需要的上下文信息]

SAVEPOINT

echo "State saved before compaction"

触发流程：

AI 检测到上下文即将压缩

↓

PreCompact Hook 触发

↓

AI 将当前任务进度、已确认决策、待解决问题写入 .claude/state/last-state.md

↓

压缩执行

↓

压缩后的 AI 读取 last-state.md 恢复关键上下文

3.3 Stop Hook：会话结束时持久化记忆

Stop Hook 在 AI 完成响应、会话即将结束时触发，自动持久化学到的经验和未完成任务清单。

配置：

{

"hooks": {

"Stop": [

{

"matcher": "",

"hooks": [

{

"type": "command",

"command": "/bin/bash .claude/hooks/persist-memory.sh"

}

]

}

]

}

}

持久化记忆脚本（.claude/hooks/persist-memory.sh）：

#!/bin/bash

# 在会话结束时，持久化关键记忆

MEMORY_DIR=".claude/memory"

mkdir -p "$MEMORY_DIR"

INPUT=$(cat)

SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

TIMESTAMP=$

保存本次会话的记忆文件

cat > "$MEMORY_DIR/session-$TIMESTAMP.md" << 'MEMORY'

会话记忆 — $TIMESTAMP

完成的任务

[AI 会在结束前自动填充]

学到的经验

[AI 会记录本次会话中发现的项目特性和注意事项]

未完成的任务

[AI 会列出需要后续会话继续处理的任务]

下次会话建议

[AI 会给下一个会话的提示]

MEMORY

更新汇总记忆文件

cat "$MEMORY_DIR"/session-*.md > "$MEMORY_DIR/summary.md" 2>/dev/null

echo "Memory persisted for session $SESSION_ID"

实际效果：

会话结束时的输出：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

�� 正在持久化会话记忆...

✅ 已保存到 .claude/memory/session-20260609-143000.md

本次会话摘要：

• 完成：实现了用户邮箱验证功能
• 决策：确认使用 resend.com 作为邮件服务商
• 经验：src/services/email.ts 的模板系统使用 Handlebars
• 待办：需要补充邮件发送失败的重试逻辑（Issue #4568）
• 提示：下次继续开发时，注意 resend API 有速率限制（10封/秒）

下次启动 Claude Code 时，这些信息将自动加载。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3.4 SessionStart Hook：新会话无缝续接

SessionStart Hook 在新会话开始时自动加载之前的上下文摘要，实现“就像 AI 从未离开过”的无缝体验。

配置：

{

"hooks": {

"SessionStart": [

{

"matcher": "",

"hooks": [

{

"type": "command",

"command": "/bin/bash .claude/hooks/load-memory.sh"

}

]

}

]

}

}

加载记忆脚本（.claude/hooks/load-memory.sh）：

#!/bin/bash

# 在新会话开始时，加载上次的记忆

MEMORY_DIR=".claude/memory"

if [ -f "$MEMORY_DIR/summary.md" ]; then

echo "�� 检测到之前的会话记忆："

echo "---"

输出最近一次会话的记忆（最后 3 个记忆块）

grep -A 50 "## 下次会话建议" "$MEMORY_DIR/summary.md" | tail -3

echo "---"

echo "这些信息将被注入到当前会话的上下文中。"

fi

无缝续接体验：

新会话开始：

�� 检测到之前的会话记忆：

上次会话时间：2026-06-09 14:30 UTC

完成：实现了用户邮箱验证功能

决策：确认使用 resend.com 作为邮件服务商

待办：补充邮件发送失败的重试逻辑（Issue #4568）

提示：注意 resend API 有速率限制（10封/秒）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

你：继续开发邮件验证功能

AI：根据上次会话的记忆，我们已经完成了基础的用户邮箱验证功能，

使用 resend.com 作为邮件服务商。

当前的待办事项是补充邮件发送失败的重试逻辑（Issue #4568）。

我知道 resend API 有 10封/秒的速率限制，会在实现中考虑。

    

请确认：是否开始实现重试逻辑？

你：对，开始吧

[AI 直接开始，无需重新解释项目背景、技术栈、之前的决策]

3.5 Hooks 记忆法的完整配置

将三个 Hook 组合使用：

{

"hooks": {

"SessionStart": [

{

"matcher": "",

"hooks": [

{

"type": "command",

"command": "/bin/bash .claude/hooks/load-memory.sh"

}

]

}

],

"PreCompact": [

{

"matcher": "",

"hooks": [

{

"type": "command",

"command": "/bin/bash .claude/hooks/save-state.sh"

}

]

}

],

"Stop": [

{

"matcher": "",

"hooks": [

{

"type": "command",

"command": "/bin/bash .claude/hooks/persist-memory.sh"

}

]

}

]

}

}

目录结构：

myproject/

├── .claude/

│ ├── settings.json

│ ├── hooks/

│ │ ├── load-memory.sh # SessionStart：加载记忆

│ │ ├── save-state.sh # PreCompact：保存状态

│ │ └── persist-memory.sh # Stop：持久化记忆

│ ├── memory/ # 自动生成的记忆文件目录

│ │ ├── session-20260609-143000.md

│ │ ├── session-20260609-170000.md

│ │ └── summary.md # 汇总（加入 .gitignore 或提交均可）

│ └── state/

│ └── last-state.md # 压缩前状态快照

4. 动态系统提示注入：按场景切换上下文

4.1 关注点分离原则

不同场景需要不同的上下文。开发场景不需要代码审查标准，研究场景不需要部署配置。这是上下文管理的关注点分离原则。

❌ 错误方式：把所有上下文塞进一个 CLAUDE.md

- 开发时加载了审查标准（无关）

- 审查时加载了构建命令（无关）

- 研究时加载了部署配置（无关）

→ 每次会话都浪费 30% Token 在无关上下文上

✅ 正确方式：按场景加载不同的上下文文件

• 开发场景 → 只加载技术栈、构建命令、代码规范
• 审查场景 → 只加载审查清单、安全标准
• 研究场景 → 只加载架构文档、技术调研模板

→ 每次会话的上下文 100% 相关

4.2 创建场景上下文文件

开发场景（~/.claude/contexts/dev.md）：

# 开发场景上下文

角色

你是全栈开发专家，专注于功能实现和代码质量。

项目技术栈

• Next.js 15 App Router + React 19 + TypeScript 5.7
• 状态管理：Zustand
• 样式：Tailwind CSS 4
• 数据库：PostgreSQL + Drizzle ORM
• 测试：Vitest + Playwright
• 包管理器：pnpm（强制）

工作流

1. 任何修改前先在 Plan 模式输出方案
2. 方案确认后开始实现
3. 每完成一个子任务立即运行测试
4. 所有代码必须通过 lint 和 typecheck

常用命令

• pnpm dev（端口 3001）
• pnpm test:unit --run
• pnpm typecheck
• pnpm lint

审查场景（~/.claude/contexts/review.md）：

# 代码审查场景上下文

角色

你是严格的代码审查专家。只进行分析和审查，不修改文件。

审查清单

• 安全漏洞：XSS、SQL 注入、认证绕过、敏感信息泄漏
• 逻辑错误：边界条件、空值处理、异常路径完整性
• 性能问题：N+1 查询、不必要的重渲染、内存泄漏
• 代码规范：命名约定、类型安全、架构约定
• 测试覆盖：新代码是否有对等测试

输出格式

结构化审查报告，包含：

• �� Critical：必须修复才能合并
• �� Warning：建议修复
• �� Suggestion：可选优化
• ✅ Positive：做得好的地方

约束

• 不允许执行 Edit/Write 操作
• 不确定的问题标注为“需要人工判断”

研究场景（~/.claude/contexts/research.md）：

# 技术研究场景上下文

角色

你是技术研究员，专注于技术选型分析和方案对比。

工作方式

1. 深度分析各种方案
2. 多假设推演
3. 给出对比表格（优劣、成本、风险）
4. 推荐最佳方案并说明理由

输出格式

• 方案对比矩阵
• 推荐方案及详细理由
• 风险与限制
• 实施建议（如果采用）

约束

• 只分析不实现
• 不确定的地方标注假设
• 所有建议必须引用数据或文档来源

4.3 配置终端别名

在 shell 配置文件中添加别名，实现一键切换场景上下文：

# 在 ~/.bashrc 或 ~/.zshrc 中添加

场景化 Claude Code 启动别名

alias claude-dev='claude --system-prompt "$(cat/.claude/contexts/dev.md)"'

alias claude-review='claude --system-prompt "$(cat/.claude/contexts/review.md)"'

alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'

配合 Worktree 的场景化别名

alias cldev='cd/myproject-feat && claude-dev'

alias clrev='cd/myproject-review && claude-review'

alias clres='cd ~/myproject-research && claude-research'

4.4 使用效果

# 开发新功能

$ cldev

�� 加载开发场景上下文...

角色：全栈开发专家

技术栈：Next.js 15 + React 19 + TypeScript 5.7

> 帮我实现用户个人资料编辑页面

审查代码

$ clrev

�� 加载审查场景上下文...

角色：严格代码审查专家

工具：仅 Read、Grep（无写入权限）

审查 feat/user-profile 分支的变更

技术研究

$ clres

�� 加载研究场景上下文...

角色：技术研究员

模式：只分析不实现

对比 React Query、SWR 和 RTK Query 的适用场景

5. 版本控制策略：什么该提交，什么不该提交

5.1 配置文件分类

正确的版本控制策略是团队协作的基础。以下是完整的配置分类：

文件	Git状态	原因	内容示例
CLAUDE.md	✅提交	团队共享的核心规范	技术栈、编码规范、架构说明
.claude/settings.json	✅提交	基础权限和团队配置	allow/deny 规则、MCP 配置
.claude/commands/	✅提交	团队统一的工作流指令	部署流程、发布检查清单
.claude/skills/	✅提交	团队共享的专业技能	代码审查、测试生成、部署
.claude/rules/	✅提交	按需加载的场景规则	API 设计规范、数据库规范
.claude/hooks/	✅提交	团队共享的自动化 Hook 脚本	Pre-commit lint、Pre-push test
.claudeignore	✅提交	上下文免疫系统配置	排除 node_modules、dist 等
.claude/settings.local.json	❌禁止提交	个人 API Key 和私密路径	API Token、本地代理设置
.claude/memory/	⚠️按需	会话记忆（可提交作为团队知识库，也可忽略）	上次会话的决策和待办
~/.claude/CLAUDE.md	❌不在项目中	用户全局个人偏好	跨项目的通用习惯
~/.claude/contexts/	❌不在项目中	个人场景上下文配置	开发/审查/研究场景定义

5.2 .gitignore 配置

# .gitignore

Claude Code — 个人私密配置

.claude/settings.local.json

.claude/CLAUDE.local.md

Claude Code — 运行时状态（可选）

.claude/state/last-state.md

如果你选择不提交会话记忆（个人决策记录）

.claude/memory/

5.3 团队配置的提交建议

# 团队共享配置的推荐提交方式

git add CLAUDE.md

git add .claude/settings.json

git add .claude/commands/

git add .claude/skills/

git add .claude/rules/

git add .claude/hooks/

git add .claudeignore

git commit -m "chore: update Claude Code team configuration

• Add API design rules for src/api/ paths
• Update code review checklist in skills
• Add pre-commit lint hook
• Update .claudeignore to exclude build artifacts"

6. 记忆管理的三大原则

6.1 原则一：记忆应该分层

层级 1 — 永久记忆（CLAUDE.md + @import）：

技术栈、编码规范、架构约定

→ 永远需要，每次加载

层级 2 — 场景记忆（.claude/rules/ + paths）：

API 设计规范、数据库规范、前端规范

→ 特定场景需要，按需加载

层级 3 — 会话记忆（Hooks 管理）：

任务进度、架构决策、经验教训

→ 跨会话需要，自动持久化和恢复

6.2 原则二：记忆应该可遗忘

不是所有信息都值得跨会话保留。以下信息应该主动遗忘：

应该遗忘的	原因
AI 的中间推理过程	占用空间，不影响最终决策
已解决的简单问题	没有复用价值
对话中的试探性提问	可能误导后续会话
过时的项目信息	过时记忆比没有记忆更危险

6.3 原则三：记忆应该可验证

# 定期检查记忆的有效性

cat .claude/memory/summary.md

清理过时的记忆

rm .claude/memory/session-2026-01-*.md # 删除半年前的记忆

验证 CLAUDE.md 的引用是否完整

claude

检查 .claude/rules/ 目录下的所有文件是否都被正确引用

7. 避坑提示

场景	问题	解决方案
@import 循环引用	文件 A 引用文件 B，文件 B 引用文件 A	Claude Code 自动检测并中断循环；设计时避免双向引用
记忆膨胀	.claude/memory/ 越来越大	定期清理超过 30 天的会话记忆
状态文件冲突	多人同时开发，last-state.md 互相覆盖	将 state/ 加入 .gitignore，每个人本地维护
Hook 脚本权限问题	Hook 脚本没有执行权限	chmod +x .claude/hooks/*.sh
场景别名未生效	修改 .bashrc 后未重新加载	source ~/.bashrc或重新打开终端
过度记忆	保留太多会话细节，新会话上下文膨胀	只保留决策、待办、经验，忘记推理过程

8. 学习要点总结

通过本集的学习，你应该掌握：

1. ✅会话无状态问题的本质：每次对话从零开始，关键信息需要跨会话保留
2. ✅@import 语法：最多 5 级递归引用，按模块拆分 CLAUDE.md
3. ✅PreCompact Hook：上下文压缩前自动保存任务状态，防止关键信息丢失
4. ✅Stop Hook：会话结束时自动持久化决策、经验和未完成任务
5. ✅SessionStart Hook：新会话开始时自动加载记忆，实现无缝续接
6. ✅动态系统提示注入：按场景（开发/审查/研究）加载不同上下文，关注点分离
7. ✅版本控制策略：共享配置提交，私密配置 gitignore
8. ✅记忆管理三原则：分层、可遗忘、可验证

本文档基于 Claude Code 官方文档及技术社区公开资料整理，信息截止日期 2026 年 6 月。