---
created: "2026-03-08 23:30"
type: zettel
tags: [claude-code, memory, persistence, workflow, best-practice]
source: "daily usage + ECC documentation"
---

# Claude Code Memory 日常最佳实践

Claude Code 有 5 层 memory 机制，从自动到手动，每层解决不同问题。

---

## 5 层 Memory 全景

```
层 1: CLAUDE.md (全局人设，每次会话自动加载)
层 2: Auto Memory (~/.claude/projects/*/memory/)    ← 最有用
层 3: Session Persistence (~/.claude/sessions/)      ← 自动运行
层 4: Instincts (~/.claude/homunculus/instincts/)    ← 自动学习
层 5: Project CLAUDE.md (项目根目录)                  ← 团队共享
```

---

## 层 1：~/.claude/CLAUDE.md — 全局人设

每次会话自动加载。放什么：
- 个人偏好（no emoji、文件大小限制、commit 格式）
- 技术栈声明（Python, C#/.NET, Java, TypeScript）
- 工作流规则的索引（指向 rules/ 而不是重复内容）

不放什么：
- 具体项目细节（放项目 CLAUDE.md）
- 临时任务状态（放 Auto Memory）
- 技术文档（放 rules/ 或 skills/）

保持简洁（30 行左右），越短 = 每次加载消耗越少 token。

---

## 层 2：Auto Memory — 项目级持久记忆

位置：`~/.claude/projects/<project-hash>/memory/`

### MEMORY.md 结构模板

```markdown
# 项目名 - Memory Index
> MEMORY.md = index (always loaded, max 200 lines). Details in topic files.

## Environment
- 运行环境、依赖版本、特殊配置

## Key Architecture
- 核心目录结构、关键文件路径
- See [architecture.md](architecture.md) for details

## Workflow Rules
- 这个项目的开发流程

## Active Session State
**Task**: 当前任务描述
**Status**: in_progress / complete
**Plan file**: 计划文件路径

## Known Issues
- 已知的坑、预期的测试失败、临时 workaround

## Topic Files
- [architecture.md](architecture.md)
- [test-locations.md](test-locations.md)
- [debugging.md](debugging.md)
```

### 关键规则

- MEMORY.md 超过 200 行会被截断，保持它是**索引**而不是详情
- 详情拆到 topic file，从 MEMORY.md 链接过去
- 只存**稳定模式**，不存临时信息
- topic file 按主题组织（architecture、debugging、config、test-locations）

---

## 层 3：Session Persistence — 会话自动摘要

位置：`~/.claude/sessions/`

ECC hook 自动运行：
- 会话开始 → 自动加载最近 7 天的 session 文件
- 会话结束 → 自动保存摘要（任务、修改文件、使用工具）

日常操作：
```bash
/sessions list                              # 查看历史
/sessions load 2026-03-08                   # 加载特定会话
/sessions alias 2026-03-08 "stock-api"      # 起别名
/sessions load stock-api                    # 用别名加载
```

不需要手动操心，hook 负责自动创建和更新。

---

## 层 4：Instincts — 自动学习行为模式

位置：`~/.claude/homunculus/instincts/personal/`

ECC continuous-learning-v2 hook 在后台观察操作，自动提取模式：
- 你纠正 Claude → 学到 instinct
- 你反复用某种模式 → 学到 instinct
- instinct 有置信度分数（0.3 → 0.9 逐步提升）

日常操作：
```bash
/instinct-status                    # 查看已学习的 instinct
/instinct-export                    # 导出给队友
/instinct-import                    # 导入其他项目的
/promote                            # 项目 instinct → 全局
```

手动告诉 Claude 记住偏好：
```
"记住：这个项目用 pnpm 而不是 npm"
"记住：Billo 项目的所有 API 都要加 correlation-id"
```

---

## 层 5：项目 CLAUDE.md vs Auto Memory

| | 项目 CLAUDE.md | Auto Memory |
|---|---|---|
| 位置 | 项目根目录（git 跟踪） | ~/.claude/projects/（本地） |
| 团队共享 | 是（提交到 git） | 否（个人） |
| 内容 | 项目规范、命令、架构说明 | 个人经验、调试记录、任务状态 |
| 修改频率 | 低（稳定后很少改） | 高（每次会话可能更新） |

---

## 日常工作流

### 开始新项目

1. 创建项目 CLAUDE.md（团队共享的规范）
2. Auto Memory 自动创建 memory/ 目录
3. 首次会话后 MEMORY.md 开始积累
4. 遇到项目特有模式 → 写入 topic file

### 继续昨天的工作

1. 打开 Claude Code → 自动加载 MEMORY.md + 最近 session
2. Claude 通过 Active Session State 知道你做到哪了
3. 继续工作
4. 完成后更新 MEMORY.md 状态

### 切换项目

1. cd 到另一个项目
2. Claude 自动加载那个项目的 CLAUDE.md + MEMORY.md
3. 上下文完全切换，不会混淆

### 发现通用模式

1. 在项目 A 发现好用模式
2. "记住：所有 API 都要用 Result pattern"
3. instinct 保存到项目级
4. 在项目 B 也验证了 → `/promote` 提升为全局

### Debug 经验保存

```
你："把这次 debug 经验保存到 memory"
Claude → 写入 memory/debugging.md
Claude → 更新 MEMORY.md 索引
下次遇到类似问题 → Claude 自动读到这个经验
```

---

## Related

- [[Everything Claude Code 多服务编排详解]]
- [[Everything Claude Code 用法速查]]
- [[Everything Claude Code 完整指南]]

## Source

- [Claude Code 官方文档](https://code.claude.com/docs/en/how-claude-code-works)
- [Claude Code Task Management](https://claudefa.st/blog/guide/development/task-management)
- ECC hooks: session-start.js, session-end.js, observe.sh
- ECC skills: continuous-learning-v2, strategic-compact