Claude Code Memory System

Every time a Claude Code session ends, the context is cleared.

Do we sometimes have to tell Claude again every time "use pnpm instead of npm" or "our indentation is 2 spaces"?Memory Systemwas created precisely for this.

What is Claude Code's memory system?

Claude Code has no automatic memory across sessions—every new session starts with a fresh context window.

The memory system uses two complementary mechanisms to allow knowledge topersist across sessionsand automatically load at the start of each conversation:

Mechanism Who writes it Best for
CLAUDE.md file You (the developer) write manually Project conventions, team agreements, build commands, etc.
Auto Memory Claude writes automatically Experience accumulated from your corrections and preferences

Both mechanisms are loaded into the context at the start of each session. Claude treats them asreference context, not enforced configuration—the more specific and concise the instructions, the more consistently Claude follows them.

Hierarchical structure of memory files

Claude Code uses afour-level memory hierarchy, with priority from high to low:

1. 企业级配置（Enterprise policy）    ← 最高优先级，只读
2. 用户级 CLAUDE.md                   ← ~/.claude/CLAUDE.md，对所有项目生效
3. 项目级 CLAUDE.md                   ← 项目根目录，随 Git 提交共享给团队
4. 子目录级 CLAUDE.md                 ← src/、api/、tests/ 等子目录，按上下文加载

The most specific rules take priority: A subdirectory's CLAUDE.md overrides similar rules from higher levels.

CLAUDE.md file explained

What is CLAUDE.md?

CLAUDE.mdIt is a Markdown file placed in the project root (or subdirectory). At the start of each new session, Claude Code willautomatically inject it into the system prompt. It is long-term memory that you can configure.

Creating CLAUDE.md

Method 1: Using/initcommand to auto-generate

# 在 Claude Code 会话中执行
/init

Claude will analyze your directory structure and automatically generate a CLAUDE.md skeleton tailored to your tech stack. For example, running it in a Node.js project/init, Claude will automatically detect frameworks, testing tools, build commands, etc., and generate an initial file that is 80% complete within 30 seconds.

Method 2: Manual creation

touch CLAUDE.md

Recommended CLAUDE.md structure

# 项目约定

## 技术栈
- 前端：Next.js 15、TypeScript 5.7、Tailwind CSS 4
- 后端：Node.js 22、Prisma 6
- 测试：Vitest 3.2

## 代码规范
- 始终使用函数式 React 组件
- 文件名使用 kebab-case
- 测试文件与源码放在同一目录

## 常用命令
- 构建：`pnpm build`
- 测试：`pnpm test`
- 启动开发服务器：`pnpm dev`

## API 约定
- 所有 API 路由以 `/api/v1/` 开头
- 错误响应格式：`{ error: string, code: number }`

Golden rules for writing good CLAUDE.md

✅ Do this:

  • Use imperative sentences and short lists, not narrative paragraphs
  • Include specific version numbers and commands
  • Add code examples (a 5-line example beats a 50-character explanation)
  • Keep it under200 lines(anything beyond that won't be loaded at session start)

❌ Avoid writing like this:

  • Vague instructions like "follow best practices" or "write clean code"
  • Too many generic rules (only include conventions unique to this project)
  • Outdated information (recommend reviewing once a month)

Subdirectory CLAUDE.md

my-project/
├── CLAUDE.md              # 全局项目规范
├── src/
│   └── CLAUDE.md          # 仅在处理 src/ 文件时加载
├── api/
│   └── CLAUDE.md          # API 特定约定
└── tests/
    └── CLAUDE.md          # 测试特定规则

Claude Code only loads a subdirectory's CLAUDE.md when processing files in that directory, saving tokens while providing more precise context.

Auto Memory explained in detail

How does it work?

Auto Memory allows Claude to accumulate knowledge across sessionsself-accumulate knowledgewithout you needing to write anything manually. Claude automatically saves notes during work, including:

  • Build commands and debugging tips
  • Architecture decision notes
  • Code style preferences
  • Workflow habits

Claude doesn't save everything every time; it judges which information will be useful in future sessionsuseful in future sessionsbefore writing it.

File structure of Auto Memory

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁的索引文件，每次会话开始时加载（前 200 行）
├── debugging.md       # 调试模式的详细笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 创建的其他主题文件

MEMORY.mdis the index of the entire memory directory; Claude uses it to track what is stored in each file.

Triggering Auto Memory

When you tell Claude certain things, it automatically saves them to memory:

你：始终使用 pnpm，不要用 npm
你：记住 API 测试需要本地运行 Redis 实例
你：我们的日期格式统一用 ISO 8601

Want to save to CLAUDE.md instead of Auto Memory?State it explicitly:

你：把这条加到 CLAUDE.md

Enabling/Disabling Auto Memory

Method 1: Via/memorycommand toggle(see next section)

Method 2: Configure in project settings

// .claude/settings.json
{
  "autoMemoryEnabled": false
}

Method 3: Environment variables

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
blockquote>

Note:Auto Memory islocal machine-level; all worktrees and subdirectories of the same Git repository share one memory directory, butit does not sync across machines or cloud environments.。

/memoryCommand usage guide

/memoryis the core command for managing the memory system.

/memoryCommand functions

In a Claude Code session, enter/memory, and you can:

  • ViewList of all CLAUDE.md and rule files loaded in the current session
  • ToggleAuto Memory on/off status
  • OpenAuto Memory folder link
  • Select any fileto open and edit in the editor

#Shortcut key — quickly add memory

This is a hidden efficiency gem:

# 始终在函数参数中使用具名参数（named parameters）

Press#key, type what you want to remember, press Enter — Claude Code automatically writes it to the corresponding CLAUDE.md file. Perfect for:

  • Recording project conventions
  • Saving common Bash commands
  • Noting code style details

Common issues and debugging

Claude ignores instructions in CLAUDE.md?

  1. Run/memoryto confirm the CLAUDE.md file has been loaded
  2. Make sure Claude Code is running in the directory containing CLAUDE.md (or a subdirectory)
  3. Check whether the instruction is specific enough — "follow best practices" is too vague, while "use named imports (tree-shaking compatible)" is more effective
  4. Check whether the file exceeds 200 lines (content beyond that is not loaded)

CLAUDE.md is context, not enforced rules

Claude readsand tries its best to follow CLAUDE.md, but there is no guarantee of strict compliance, especially when instructions are vague or conflicting. Think of it as "a work guide for Claude" rather than "unbreakable rules."

Real-world workflow examples

Scenario 1: Initializing a new project

# 1. 在项目根目录启动 Claude Code
cd my-project
claude

# 2. 生成记忆文件骨架
/init

# 3. 审查并完善生成的 CLAUDE.md
/memory  # 打开文件编辑

# 4. 开始工作，Claude 会自动积累记忆

Scenario 2: Recording debugging findings

你：记住，运行集成测试前必须先启动 Docker Compose
Claude：好的，我已将这条记录到 Auto Memory 中。
In the next session, Claude will automatically know this dependency.

Scenario 3: Team collaboration

Put the project root directory'sCLAUDE.mdCommit to the Git repository — every team member's Claude assistant reads the same specifications, ensuring a consistent AI-assisted experience.

git add CLAUDE.md
git commit -m "feat: add Claude Code memory configuration"

Best practices summary

Scenario Recommended approach
Team-shared specifications CLAUDE.md in the project root, committed to Git
Personal preferences ~/.claude/CLAUDE.md(User-level)
Module-specific rules Subdirectory CLAUDE.md
Let Claude self-learn Enable Auto Memory, verbally communicate preferences
Temporary context @docs/filename.mdReference as needed, don't cram it into CLAUDE.md
Task tracking Use in Markdown files[ ]Checkbox

Reference resources

Other extensions