Claude Code Memory 功能深度解析：CLAUDE.md、Auto Memory 与跨会话上下文管理实战

手把手教你掌握 Claude Code 的记忆系统，从 CLAUDE.md 配置到 Auto Memory 自动记忆，构建让 AI 真正"记住"你项目的完整上下文管理方案。

前言

在日常使用 Claude Code 时，你是否遇到过这样的情况：每次新开一个会话，Claude 就"忘记"了你的项目规范、代码风格偏好和之前的调试经验？你需要反复告诉它"用 TypeScript"、"测试用 Vitest"、"API 响应格式遵循 RFC 7807"……

Claude Code 的 Memory 功能正是为解决这个痛点而设计。2026 年 7 月，Anthropic 进一步推出了 Auto Memory 功能，让 Claude 能够自动学习并记住你的项目上下文、调试模式和偏好方法，在后续会话中自动调用，无需手动维护。

本文将从原理到实战，完整拆解 Claude Code 的记忆系统，帮你构建一套高效的跨会话上下文管理方案。

---

一、Claude Code 记忆系统的三层架构

Claude Code 的记忆并非单一机制，而是由三个递进层次构成：

层次	机制	作用域	设置方式
第一层	CLAUDE.md 文件	项目级 / 全局级	手动编写
第二层	Auto Memory	用户级 / 项目级	自动学习
第三层	项目记忆持久化	跨会话	Hooks + 外部存储

1.1 CLAUDE.md：项目上下文的"宪法"

CLAUDE.md 是一个 Markdown 格式的配置文件，Claude Code 在每次会话启动时会自动读取并将其内容注入上下文窗口。它相当于项目的"宪法"——定义了 Claude 在这个项目中必须遵守的规则。

1.2 Auto Memory：自动学习的长期记忆

Auto Memory 是 2026 年新增的功能。当你与 Claude Code 交互时，它会自动识别值得记住的信息（如你的代码风格偏好、常用调试方法、项目特有的命名约定），并在后续会话中自动应用。

1.3 项目记忆持久化：跨会话状态管理

通过 Hooks 机制和外部存储（如文件系统、数据库），你可以实现更复杂的记忆持久化，让 Claude 在多次会话间保持项目状态。

---

二、CLAUDE.md 实战配置

2.1 文件层级与加载顺序

~/.claude/CLAUDE.md          # 全局配置（所有项目生效）
项目根目录/CLAUDE.md           # 项目配置（最高优先级）
项目根目录/.claude/CLAUDE.md   # 项目配置（等价于根目录）
子目录/CLAUDE.md              # 目录级配置（进入该目录时加载）

后加载的文件会覆盖先加载的同名配置，项目级配置优先于全局配置。

2.2 完整 CLAUDE.md 模板

# 项目：电商订单管理系统

## 技术栈
- 后端：Python 3.12 + FastAPI + SQLAlchemy 2.0
- 前端：React 18 + TypeScript + Tailwind CSS
- 数据库：PostgreSQL 16 + Redis 7
- 测试：pytest + Vitest
- 部署：Docker + Kubernetes

## 代码规范
- Python 代码使用 `ruff` 格式化，行宽 100
- TypeScript 代码使用 ESLint + Prettier，2 空格缩进
- API 响应统一遵循 RFC 7807 错误格式
- 所有公开函数必须有类型注解和 docstring
- 前端组件使用函数式组件 + Hooks，禁止使用 class 组件

## 命名约定
- Python 文件：snake_case
- React 组件文件：PascalCase
- API 路由：/api/v1/resource-name（kebab-case）
- 数据库表名：snake_case，复数形式

## 项目结构
- src/api/        — API 路由层
- src/models/     — 数据模型
- src/services/   — 业务逻辑层
- src/utils/      — 工具函数
- tests/          — 测试文件，镜像 src/ 结构
- frontend/src/components/ — React 组件

## 禁止事项
- 不要修改 src/legacy/ 目录下的代码（正在废弃中）
- 不要使用 print() 调试，使用 logger
- 不要直接操作数据库，必须通过 Repository 层
- 不要在组件中直接调用 fetch，使用 src/api/client.ts 封装的方法

## 常用命令
- 运行测试：`make test`
- 启动开发服务器：`make dev`
- 数据库迁移：`make migrate`
- 代码检查：`make lint`

# 启动 Claude Code 后，输入以下命令检查已加载的配置
claude> /context

# 输出示例：
# Loaded CLAUDE.md files:
#   1. ~/.claude/CLAUDE.md (global, 45 lines)
#   2. ./CLAUDE.md (project, 52 lines)
# Total context tokens: 3,247

---

三、Auto Memory 自动记忆实战

3.1 启用 Auto Memory

# 检查当前版本
claude --version

# 启用 Auto Memory（如果未默认开启）
claude config set auto_memory true

# 查看当前配置
claude config list

3.2 Auto Memory 的工作原理

Auto Memory 会在你的交互过程中自动识别以下类型的信息并存储：

代码风格偏好：例如你总是要求使用 async/await 而非 .then()

调试模式：例如你习惯先写测试再写实现（TDD 流程）

项目约定：例如你总是用 zod 做运行时类型校验

环境信息：例如你的开发环境是 macOS + Docker Desktop

这些记忆存储在 ~/.claude/memories/ 目录下，以 JSON 格式组织。

# 列出所有自动记忆
claude memory list

# 输出示例：
# [project: order-system] Prefers async/await over Promise chains
# [project: order-system] Uses zod for runtime validation
# [global] Development environment: macOS, Docker Desktop
# [global] Prefers Vitest over Jest for new projects

# 删除特定记忆
claude memory remove <memory-id>

# 清除项目级所有记忆
claude memory clear --project

# 导出记忆供备份
claude memory export > my-memories.json

3.4 Auto Memory 与 CLAUDE.md 的协同

CLAUDE.md    → 团队共享的硬性规则（代码规范、架构约定）
Auto Memory  → 个人工作习惯（调试方式、工具偏好）

---

四、用 Hooks 实现高级记忆持久化

当 CLAUDE.md 和 Auto Memory 无法满足复杂场景时，你可以通过 Hooks 机制实现自定义的记忆持久化。

4.1 Hooks 配置

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/scripts/save_context.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/scripts/update_memory.py"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
"""save_context.py - 在 Claude Code 每次编辑文件前保存当前上下文"""
import json
import os
from datetime import datetime
from pathlib import Path

MEMORY_DIR = Path(".claude/project_memory")
MEMORY_DIR.mkdir(parents=True, exist_ok=True)

def save_context():
    """保存当前项目状态快照"""
    snapshot = {
        "timestamp": datetime.now().isoformat(),
        "git_branch": os.popen("git branch --show-current 2>/dev/null").read().strip(),
        "git_status": os.popen("git status --porcelain 2>/dev/null").read().strip()[:500],
        "recent_commits": os.popen("git log --oneline -5 2>/dev/null").read().strip(),
    }
    
    snapshot_file = MEMORY_DIR / f"snapshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
    snapshot_file.write_text(json.dumps(snapshot, ensure_ascii=False, indent=2))
    
    # 只保留最近 50 个快照
    snapshots = sorted(MEMORY_DIR.glob("snapshot_*.json"))
    if len(snapshots) > 50:
        for old in snapshots[:-50]:
            old.unlink()

if __name__ == "__main__":
    save_context()

#!/usr/bin/env python3
"""update_memory.py - 编辑后提取关键信息更新项目记忆"""
import json
import re
from pathlib import Path
from datetime import datetime

MEMORY_FILE = Path(".claude/project_memory/persistent_memory.json")

def load_memory():
    if MEMORY_FILE.exists():
        return json.loads(MEMORY_FILE.read_text())
    return {"patterns": [], "last_updated": None}

def save_memory(memory):
    memory["last_updated"] = datetime.now().isoformat()
    MEMORY_FILE.parent.mkdir(parents=True, exist_ok=True)
    MEMORY_FILE.write_text(json.dumps(memory, ensure_ascii=False, indent=2))

def update_memory():
    memory = load_memory()
    
    # 记录最近修改的文件类型分布
    git_diff = __import__("os").popen("git diff --name-only HEAD 2>/dev/null").read().strip()
    if git_diff:
        files = git_diff.split("\n")
        extensions = {}
        for f in files:
            ext = Path(f).suffix or "no_ext"
            extensions[ext] = extensions.get(ext, 0) + 1
        
        pattern = {
            "timestamp": datetime.now().isoformat(),
            "modified_files": len(files),
            "extensions": extensions,
        }
        memory["patterns"].append(pattern)
        memory["patterns"] = memory["patterns"][-100:]  # 保留最近100条
    
    save_memory(memory)

if __name__ == "__main__":
    update_memory()

---

五、实操步骤：从零搭建记忆系统

# 在项目根目录创建 CLAUDE.md
cat > CLAUDE.md << 'EOF'
# 项目名称

## 技术栈
（填写你的技术栈）

## 代码规范
（填写你的代码规范）

## 禁止事项
（填写禁止操作）
EOF

# 验证加载
claude
# 在会话中输入: /context

claude config set auto_memory true

mkdir -p .claude/scripts .claude/project_memory
# 将上文的 hooks.json 和脚本文件放入对应位置
chmod +x .claude/scripts/*.py

cat > ~/.claude/CLAUDE.md << 'EOF'
# 全局偏好

## 通用习惯
- 优先使用 TypeScript 而非 JavaScript
- 测试框架优先选择 Vitest
- 数据库迁移工具优先选择 Alembic
- 日志库优先选择 structlog

## 回答偏好
- 代码示例附带完整类型注解
- 优先给出可运行的完整代码而非伪代码
- 复杂概念用类比解释
EOF

---

六、上下文窗口优化策略

CLAUDE.md 会消耗上下文窗口的 token，因此需要控制其大小：

# 查看当前 CLAUDE.md 消耗的 token 数
wc -c CLAUDE.md  # 字节数（粗略估算：1 token ≈ 3-4 字节英文，1-2 字节中文）

# 建议：CLAUDE.md 控制在 2000 token 以内（约 3000-4000 字符）

6.2 按需加载策略

project/
├── CLAUDE.md                    # 核心规则（< 1000 token）
├── src/
│   ├── api/
│   │   └── CLAUDE.md            # API 层专用规则
│   ├── models/
│   │   └── CLAUDE.md            # 模型层专用规则
│   └── frontend/
│       └── CLAUDE.md            # 前端专用规则

Claude Code 在处理特定目录的文件时，会自动加载该目录的 CLAUDE.md，避免一次性加载所有规则。

# 项目：大型微服务系统

## 核心规范
详见 @docs/coding-standards.md

## API 设计指南
详见 @docs/api-design-guide.md

当 Claude 需要时会自动读取引用的文件，而非在启动时全部加载。

---

七、常见问题 FAQ

Q1: CLAUDE.md 和 .cursorrules 有什么区别？

CLAUDE.md 是 Claude Code 专用的上下文配置文件，支持分层加载、@import 引用和动态目录级加载。.cursorrules 是 Cursor 编辑器的配置文件。两者格式类似但功能不同，Claude Code 不会读取 .cursorrules。

Q2: Auto Memory 会记住敏感信息吗？

Auto Memory 会在存储前进行敏感信息过滤，不会记录 API 密钥、密码等敏感数据。但建议不要在对话中明文输入敏感信息。你可以通过 claude memory list 检查并手动删除不需要的记忆。

Q3: 多人协作时如何共享 CLAUDE.md？

将 CLAUDE.md 提交到 Git 仓库，所有团队成员共享同一份项目配置。个人偏好通过 Auto Memory（存储在本地 ~/.claude/）管理，不会影响他人。全局配置 ~/.claude/CLAUDE.md 也可以通过 dotfiles 仓库管理。

Q4: CLAUDE.md 太长导致上下文溢出怎么办？

采用以下策略：1) 精简核心规则到 1000 token 以内；2) 使用子目录 CLAUDE.md 按需加载；3) 使用 @import 引用外部文档；4) 将示例代码移到单独文件中引用。

Q5: 如何调试 CLAUDE.md 没有生效的问题？

使用 /context 命令查看已加载的配置文件列表和 token 消耗。确保文件名正确（区分大小写），路径在项目根目录或 ~/.claude/ 下。检查是否有语法错误导致解析失败。

---

八、总结

Claude Code 的记忆系统通过三层架构实现了从手动配置到自动学习的完整上下文管理：

CLAUDE.md 提供项目级硬性规则，是团队协作的基础
Auto Memory 自动学习个人偏好，减少重复指令
Hooks 持久化 实现自定义记忆逻辑，应对复杂场景

核心原则是：稳定的规则写进 CLAUDE.md，动态的偏好交给 Auto Memory，复杂的状态用 Hooks 管理。合理配置后，Claude Code 将从"每次从零开始"变为"越用越懂你的项目"。