Claude Code 记忆系统详解

发表于 分类于

Claude Code 的记忆系统分为 三层，分别解决不同层面的问题。理解这三层的区别与关系，是高效使用 Claude Code 的前提。

一、三层架构概览

层级 存储位置 解决问题 跨项目共享？
全局配置 ~/.claude/settings.json 所有项目共享的权限、插件、环境变量 ✅ 是
项目配置 {project}/.claude/ 该项目专属的权限、钩子 ❌ 否
项目记忆 ~/.claude/projects/<path>/memory/ 该项目的用户偏好、工作约定 ❌ 否

二、全局配置层

所有项目共享的配置，定义 Claude Code 的全局行为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "env": {
    "ANTHROPIC_MODEL": "MiniMax-M2.7"
  },
  "permissions": {
    "allow": [
      "Bash(uv sync *)",
      "Bash(git log --oneline -20)"
    ]
  },
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true,
    "remember@claude-plugins-official": true
  }
}

核心配置项包括：

  • env — API key、全局默认模型
  • permissions — 所有项目都允许的 Shell 命令
  • enabledPlugins — 全局启用的插件

三、项目配置层

单个项目专属的配置，通常与项目代码一起版本控制：

1
2
3
tender-info/
└── .claude/
    └── settings.local.json
1
2
3
4
5
6
7
8
9
{
  "permissions": {
    "allow": [
      "Bash(uv sync *)",
      "Bash(uv venv *)",
      "Bash(git -C /Volumes/hai/code/tender-info log --oneline -5)"
    ]
  }
}

项目配置文件的作用是记录该项目额外允许的 Shell 命令权限，避免每次操作都弹出权限提示。

四、项目记忆层

严格按项目路径隔离的记忆系统，存放项目相关的持久上下文：

1
2
3
~/.claude/projects/-Volumes-hai-code-tender-info/memory/
├── MEMORY.md
└── python-dependency-management.md

4.1 记忆文件类型

类型 用途 关键字段
user 用户角色、偏好、工作方式 name, description, type, originSessionId
feedback 指导规则（什么该做/不该做） 含 Why: 和 How to apply:
project 项目状态、目标、截止日期 含 Why: 和 How to apply:
reference 外部系统指针（Linear、Grafana 等） 链接 + 用途说明

4.2 记忆格式

每条记忆为独立 Markdown 文件，含 frontmatter：

1
2
3
4
5
6
7
8
9
10
11
12
---
name: python-dependency-management
description: 用户级Python依赖管理原则
type: user
originSessionId: 46dcfe60-6dcb-4824-850e-41e8ccc11b8f
---

## 具体内容

用户使用 **uv** 管理 Python 项目：
1. uv sync：主要命令
2. uv run：直接运行脚本

MEMORY.md 作为索引文件，每次会话自动加载；具体记忆文件在上下文相关时自动应用。

五、remember 插件 — 会话交接机制

remember 插件是记忆系统的补充机制，解决「跨时间连续性」问题。

5.1 与 memory/ 的区别

维度 memory/ 记忆系统 remember 插件
位置 ~/.claude/projects/<path>/memory/ {project}/.remember/remember.md
内容 项目偏好、规则、约定 会话交接、进度、下一步
触发 自动加载 手动调用 /remember
生命周期 跨会话持久 下次会话后可能被覆盖
语义 「这个项目是什么样的」 「上次我做到哪了」

5.2 文件格式

1
2
3
4
5
6
7
8
9
10
# Handoff

## State
{已完成什么、未完成什么。文件、MR 号、决策。最多 2-4 行。}

## Next
{接下来要做什么。按优先级排列。1-3 项。}

## Context
{非显而易见的坑、阻碍、本次偏好。如无内容可省略。}

5.3 使用规则

规则 说明
总行数 < 20 简洁，避免长篇大论
具体 包含文件路径、MR 号、分支名
前瞻性 下一会话只关心「接下来干嘛」
无内容时 直接写 “No active work.”

六、三层关系全景图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
~/.claude/
├── settings.json              ← 【全局】所有项目共享
│   ├── env (API key, 模型)
│   ├── permissions (允许的命令)
│   └── enabledPlugins
│
├── projects/                  ← 【记忆】按项目路径隔离
│   └── -Volumes-hai-code-tender-info/
│       └── memory/
│           ├── MEMORY.md       ← 索引
│           └── *.md            ← 具体记忆
│
tender-info/                   ← 【项目】
├── .claude/
│   └── settings.local.json    ← 项目级权限
├── .remember/
│   └── remember.md            ← 会话交接（remember 插件）
└── ...项目文件

七、设计思想

层次 解决的问题 关键词
全局配置 「所有项目通用」 权限、插件、模型
项目配置 「这个项目能做什么」 权限、钩子
项目记忆 「用户想要什么方式工作」 偏好、反馈、约定
remember 「上次做到哪了」 交接、进度、连续性

三层设计体现了关注点分离原则：全局配置、项目配置、项目记忆三者职责清晰不混淆。memory/ 和 remember 解决不同维度的问题——前者是「项目画像」，后者是「时间线快照」。

理解这四层的区别，就能理解为什么没有一个「跨项目全局记忆」——因为全局配置（settings.json）解决的是工具能力，而非项目上下文。