Overview
Persistent memory system that lets AI remember the user's preferences, project conventions, and important context across sessions. Core principle:Every valuable interaction should be persisted。
When to Use
Scenarios that must be actively remembered:
- User explicitly states a preference: "I prefer tabs"
- User implies a preference: behavior patterns, communication style
- Project technical decisions: runtime choices, code standards, testing frameworks
- Historical context: previously fixed bugs, important PRs, deprecated patterns
- Anything the user says "remember", "don't forget", "last time we"
Commands that immediately trigger memory:
/remember- Remember the current information/init-memory- Initialize the memory structure/reflect- Reflect and update memory
Core Pattern
1. Memory storage location
~/.claude/memory/
├── system/ # 附加到 system prompt
│ ├── persona/
│ │ ├── behavior.md # 行为准则
│ │ └── constraints.md # 约束限制
│ ├── human/
│ │ ├── background.md # 用户背景
│ │ └── preferences/
│ │ ├── coding.md # 编码偏好
│ │ └── comm.md # 沟通偏好
│ └── project/
│ ├── overview.md # 项目概览
│ ├── tooling.md # 工具配置
│ └── conventions.md # 约定规范
└── detached/ # 按需加载
├── history/ # 历史上下文
└── archive/ # 归档
2. Memory file format
---
label: preferences/coding
description: 用户的编码偏好,影响代码生成风格
---
# 编码偏好
## 格式
- 缩进: Tabs (非 spaces)
- 行尾: LF (非 CRLF)
## 风格
- 避免 try-catch 用于控制流
- 使用 early return
- 添加 JSDoc 注释
## 沟通
- 修改代码前先解释思路
3. Key principles
| Principle | Description |
|---|---|
| Proactive | No need for the user to say "remember"; save valuable information as soon as you see it |
| Hierarchical | Use / separators to create 2-3 levels of depth |
| Small and focused | Each file ~40 lines, one topic |
| Retrievable | File names and paths must be meaningful |
Quick Reference
Common commands
| Command | Purpose |
|---|---|
/remember <信息> |
Quickly remember the current information |
/init-memory |
Initialize the hierarchical memory structure |
/reflect |
Reflect and update memory |
/memory-check |
Check the current memory state |
File operations
# 读取记忆
cat ~/.claude/memory/system/human/preferences/coding.md
# 更新记忆
echo "新偏好内容" >> ~/.claude/memory/system/human/preferences/coding.md
# 创建新记忆块
cat > ~/.claude/memory/system/project/tooling/bun.md << 'EOF'
---
label: project/tooling/bun
description: Bun 运行时相关配置
---
# Bun 配置
EOF
Implementation
Initialize the memory structure
mkdir -p ~/.claude/memory/system/{persona,human/preferences,project}
mkdir -p ~/.claude/memory/detached/{history,archive}
Memory injected into the System Prompt
At the start of a session, append the contents of all .md files under system/ to the system prompt:
以下是你需要知道的重要信息:
--- USER PREFERENCES ---
[读取 ~/.claude/memory/system/human/**/*.md]
--- PROJECT CONTEXT ---
[读取 ~/.claude/memory/system/project/**/*.md]
--- BEHAVIOR GUIDELINES ---
[读取 ~/.claude/memory/system/persona/**/*.md]
Automatic memory script
Create ~/.claude/remember.sh:
#!/bin/bash
# 用法: remember "标签" "内容"
LABEL="$1"
CONTENT="$2"
DATE=$(date +%Y-%m-%d)
mkdir -p ~/.claude/memory/detached
cat >> ~/.claude/memory/detached/"$LABEL".md << EOF
---
label: $LABEL
date: $DATE
---
$CONTENT
EOF
Common Mistakes
| Error | Consequence | Fix |
|---|---|---|
| Only remember in the current session | Information is lost | Write to the file system immediately |
| Memory block is too large | Hard to retrieve | Split into multiple small files |
| Flat structure | Chaos | Use / to create hierarchy |
| Do not update old memories | Information becomes outdated | Regularly /reflect |
| Do not tell the user | The user does not know | Proactively confirm "remembered" |
Red Flags - Act immediately
The following situations mean you have violated the memory principles and must correct them immediately:
- ❌ "I will remember this in the current session" → Must write to a file
- ❌ The user says "last time we" and you do not know → Historical memory was not loaded
- ❌ The user repeats the same preference → It was not stored correctly
- ❌ The user says "I told you before" → Memory was not persisted
- ❌ Forgetting the user's coding preferences → It was not loaded at the start of the session
All of these situations mean: write to the memory file, then continue。
Workflow
digraph memory_flow {
"用户提供信息" -> "判断是否值得记忆?"
"判断是否值得记忆?" -> "是" [label="偏好/约定/上下文"]
"判断是否值得记忆?" -> "否" [label="一次性问题"]
"是" -> "选择正确位置"
"选择正确位置" -> "human/preferences" [label="用户偏好"]
"选择正确位置" -> "project" [label="项目相关"]
"选择正确位置" -> "persona" [label="行为准则"]
"选择正确位置" -> "detached" [label="历史上下文"]
"选择正确位置" -> "写入记忆文件"]
"写入记忆文件" -> "确认已记住"
}
Automatically load at startup (important)
Must execute: At the start of every session, memory files must be loaded into the context.
Auto-load Hook
In ~/.claude/settings.json configure hooks:
{
"hooks": {
"MemoryLoad": {
"match": ".*",
"command": "cat ~/.claude/memory/system/human/preferences/*.md ~/.claude/memory/system/project/*.md 2>/dev/null"
}
}
}
Manual load command
If the hook is not configured, execute at session start:
# 加载所有 system 记忆到上下文
cat ~/.claude/memory/system/human/preferences/*.md
cat ~/.claude/memory/system/project/*.md
cat ~/.claude/memory/system/persona/*.md
Memory check reminder
In long sessions, if the user provides important information but does not explicitly ask to "remember" it, proactively check at the following moments:
- After the user finishes a segment of important context
- 30 minutes into the session
- When the user expresses frustration or mentions past issues
Reminder phrasing:
"I noticed you mentioned some important background information. Would you like me to remember this for future reference?"
Integration with other tools
| Tool | Integration method |
|---|---|
| conversation_search | Search historical conversations to supplement memory |
| Read | Read memory file |
| Write/Edit | Update memory file |
| Bash | File operations |