Claude Code 记忆系统

Claude Code 记忆系统

涵盖 Claude Code 的所有记忆类型、存储机制和使用方法

概览

Claude Code 拥有多层记忆系统，从临时会话上下文到永久化存储，形成完整的知识积累和检索机制。

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code 记忆系统                      │
├─────────────────────────────────────────────────────────────┤
│  会话记忆 (临时)                                             │
│  ├─ 对话历史                                                 │
│  ├─ 代码文件内容                                             │
│  └─ git 状态                                                │
├─────────────────────────────────────────────────────────────┤
│  项目记忆 (永久)                                             │
│  ├─ CLAUDE.md 指令                                          │
│  ├─ .claude/rules/ 规则                                     │
│  └─ Auto Memory                                             │
├─────────────────────────────────────────────────────────────┤
│  用户记忆 (永久)                                             │
│  ├─ ~/.claude/CLAUDE.md                                     │
│  ├─ ~/.claude/memory/                                       │
│  └─ settings.json 配置                                      │
├─────────────────────────────────────────────────────────────┤
│  Agent 记忆 (隔离/永久)                                      │
│  ├─ Subagent 独立上下文                                      │
│  ├─ Agent Memory (持久化)                                    │
│  └─ Worktree 隔离记忆                                       │
├─────────────────────────────────────────────────────────────┤
│  技能与计划 (永久)                                           │
│  ├─ Skills (可重用工作流)                                    │
│  └─ Plans (实现计划)                                         │
└─────────────────────────────────────────────────────────────┘

1. 会话记忆 (Session Memory)

特点

• 作用域: 单会话
• 持久性: 临时（会话结束后清除）
• 存储位置: 当前上下文窗口

内容组成

压缩机制

当上下文接近容量限制时：

• 自动压缩早期消息
• 保留 CLAUDE.md 内容（重新加载）
• 可通过 /compact 手动触发

2. 项目记忆 (Project Memory)

2.1 CLAUDE.md 指令文件

作用域层级

加载规则

当前工作目录 (CWD)
    ↓
向上遍历目录树
    ↓
加载所有 CLAUDE.md 文件
    ↓
子目录的 CLAUDE.md 按需加载

导入语法

# 项目说明
@README

# 构建指令
@docs/build-guide.md

# 个人偏好
@~/.claude/my-preferences.md

2.2 .claude/rules/ 规则系统

目录结构

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主项目指令
│   └── rules/
│       ├── code-style.md   # 代码风格指南
│       ├── testing.md      # 测试约定
│       └── frontend/       # 子目录
│           └── react-rules.md

路径特定规则

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---

# API 开发规则

- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式

作用域优先级

1. 项目级规则: .claude/rules/
2. 用户级规则: ~/.claude/rules/

2.3 Auto Memory（自动记忆）

存储位置

~/.claude/projects/<project-id>/memory/
├── MEMORY.md          # 主索引（前200行自动加载）
├── debugging.md       # 调试模式笔记
├── patterns.md        # 代码模式记录
└── api-conventions.md # API 设计决策

触发条件

管理命令

# 查看和管理记忆
/memory

# 禁用自动记忆
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

3. 用户记忆 (User Memory)

存储位置

~/.claude/
├── CLAUDE.md           # 用户全局指令
├── memory/
│   └── MEMORY.md       # 用户全局记忆
├── settings.json       # 用户设置
└── settings.local.json # 本地设置

跨项目共享

用户级记忆和配置在所有项目中共享：

• 全局编码偏好
• 个人工具快捷方式
• 跨项目的工作流习惯

4. 配置记忆 (Configuration Memory)

Settings 文件层级

配置类型

权限配置

{
  "permissions": {
    "allow": ["npm", "git"],
    "deny": ["Agent(Explore)"],
    "sandbox": {
      "enabled": true
    }
  }
}

环境变量

{
  "env": {
    "NODE_ENV": "development",
    "API_KEY": "${USER_API_KEY}"
  }
}

Hooks（自动化行为）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Running command'"
          }
        ]
      }
    ]
  }
}

5. Agent 记忆系统

5.1 Subagent 上下文隔离

内置 Subagent 类型

记忆隔离特点

• 独立上下文窗口: 每个 subagent 拥有独立对话历史
• 无项目记忆继承: 不会自动访问项目 auto memory
• 结果传递: 通过返回值传递给主 agent

5.2 Agent 持久化记忆

配置方式

---
name: code-reviewer
memory: user  # 可选: user | project | local
---

存储位置

自动注入

启用持久化记忆后：

• 自动注入前 200 行 MEMORY.md 到 agent 上下文
• 自动启用 Read, Write, Edit 工具
• 包含记忆管理指令

5.3 后台任务记忆

任务生命周期

# 创建后台任务
Agent(task, description="...", run_in_background=true)

# 获取输出
TaskOutput(task_id)

# 停止任务
TaskStop(task_id)

记忆特点

• 任务 ID 追踪
• 输出缓存直到主动读取
• 完成后自动通知主会话

5.4 Worktree 隔离记忆

主会话上下文
    ↓
EnterWorktree → 创建临时目录
    ↓
Subagent 在 worktree 中运行
    ↓
独立文件系统 + 独立上下文
    ↓
ExitWorktree → 返回原目录

上下文重置

退出 worktree 时清除：

• CWD 缓存
• 系统提示段落
• 计划目录

6. 技能与计划 (Skills & Plans)

6.1 Skills 记忆

存储位置

~/.claude/skills/           # 用户级技能
.claude/skills/             # 项目级技能

特点

• 可重用的代码片段和工作流
• 按需加载，不自动注入
• 支持参数传递

6.2 Plans 记忆

存储位置

.claude/plans/[plan-name].md

阶段

7. 记忆层级关系

┌─────────────────────────────────────────────┐
│           全局 User (最高优先级)              │
│  ~/.claude/CLAUDE.md + settings.json        │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│           项目 Project                       │
│  ./CLAUDE.md + .claude/rules/ + auto memory │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│        会话 Session (临时)                   │
│  对话历史 + 当前上下文                       │
└─────────────────────────────────────────────┘

优先级规则

1. 会话上下文 > 项目记忆 > 用户记忆 > 默认行为
2. 具体 CLAUDE.md > 通用 CLAUDE.md
3. 用户级 settings > 项目级 settings

8. 记忆系统完整类型总结

9. 实用命令

查看和管理记忆

# 查看所有加载的指令文件
/memory

# 查看当前配置
/settings

# 查看可用的 subagents
/agents

# 初始化项目 CLAUDE.md
/init

# 压缩会话上下文
/compact

环境变量

# 禁用自动记忆
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

# 自定义记忆目录
export CLAUDE_CODE_MEMORY_DIR="~/custom-memory"

# 禁用后台任务
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

# 自动压缩阈值
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

10. 最佳实践

CLAUDE.md 编写

1. 保持简洁: 目标少于 200 行
2. 具体明确: "使用 2 空格缩进" 而非 "格式化代码"
3. 结构清晰: 使用 markdown 标题分组

Auto Memory 管理

1. 定期审查: 使用 /memory 检查保存内容
2. 主动纠正: 发现错误时立即纠正
3. 组织主题: 将详细笔记移至主题文件

Subagent 记忆

1. 明确范围: 选择合适的 memory 作用域
2. 主动更新: 要求 agent 完成任务后更新记忆
3. 检查记忆: 定期查看 agent 学到的内容

组织管理

1. 托管策略: 使用 /etc/claude-code/ 部署组织标准
2. 项目规则: 通过 .claude/rules/ 共享团队约定
3. 版本控制: 提交项目级 CLAUDE.md 和规则