Memory — Cách Claude nhớ project của bạn

Vấn đề: Mỗi session Claude Code bắt đầu từ con số 0

Mỗi lần mở Claude Code, context window hoàn toàn trắng. Không nhớ bạn thích gì, project chạy thế nào, hay lần trước fix bug gì.

Hai cơ chế giải quyết chuyện này:

• CLAUDE.md — file bạn viết, chứa instruction cho Claude
• Auto memory — ghi chú Claude tự viết khi học được điều gì từ bạn

Cả hai đều được load vào đầu mỗi session.

CLAUDE.md vs Auto Memory

	CLAUDE.md	Auto Memory
Ai viết	Bạn	Claude
Chứa gì	Instructions, rules	Patterns, learnings
Scope	Project, user, hoặc org	Per working tree
Dùng cho	Coding standards, workflows, architecture	Build commands, preferences Claude tự phát hiện

💡 Tip: Dùng CLAUDE.md khi bạn muốn điều khiển Claude. Dùng auto memory khi bạn muốn Claude tự học từ cách bạn làm việc.

CLAUDE.md — Instruction file cho Claude

Đặt ở đâu?

Scope	Location	Chia sẻ với
Project	./CLAUDE.md hoặc ./.claude/CLAUDE.md	Team (qua git)
User	~/.claude/CLAUDE.md	Chỉ bạn (mọi project)
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	Toàn tổ chức

File cụ thể hơn sẽ được ưu tiên hơn. Project CLAUDE.md ghi đè User CLAUDE.md.

Khởi tạo nhanh

/init

Claude sẽ scan codebase và tạo CLAUDE.md với build commands, test instructions, conventions nó phát hiện được. Nếu file đã tồn tại, /init gợi ý cải thiện thay vì ghi đè.

Viết instruction hiệu quả

Ngắn gọn: Giữ dưới 200 dòng. File dài = tốn context + Claude hay bỏ qua.

Cụ thể: Viết rõ ràng, kiểm chứng được.

# Tốt
- Use 2-space indentation
- Run `npm test` before committing
- API handlers live in `src/api/handlers/`

# Không tốt
- Format code properly
- Test your changes
- Keep files organized

Không mâu thuẫn: Nếu hai rules nói ngược nhau, Claude chọn ngẫu nhiên. Review định kỳ.

Import file khác

Dùng @path/to/file để kéo thêm context:

See @README for project overview.
Git workflow: @docs/git-instructions.md
Personal prefs: @~/.claude/my-project-instructions.md

Path tương đối tính từ file chứa import, không phải working directory. Import lồng nhau tối đa 5 cấp.

⚠️ Lưu ý: Lần đầu gặp external imports, Claude Code sẽ hỏi bạn approve. Nếu bạn từ chối, imports bị tắt vĩnh viễn.

.claude/rules/ — Chia nhỏ instructions

Khi CLAUDE.md quá dài, tách ra thành nhiều file trong .claude/rules/:

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

Mỗi file .md là một topic. Đặt tên mô tả: testing.md, api-design.md.

Path-specific rules — Chỉ load khi cần

Thêm paths frontmatter để rule chỉ áp dụng cho file matching pattern:

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

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

Rules không có paths sẽ load mọi lúc. Rules có paths chỉ load khi Claude đọc file khớp pattern.

Một số pattern phổ biến:

Pattern	Match
**/*.ts	Mọi TypeScript file
src/**/*	Mọi file trong src/
src/components/*.tsx	React components trong thư mục cụ thể

💡 Tip: Dùng path-specific rules cho team lớn — frontend team không cần thấy backend rules và ngược lại. Tiết kiệm context window.

Symlinks cho shared rules

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

User-level rules

Rules cá nhân đặt ở ~/.claude/rules/ — áp dụng mọi project, ưu tiên thấp hơn project rules.

Auto Memory — Claude tự ghi chú

Claude tự lưu những gì nó học được: build commands, debugging patterns, style preferences. Không phải session nào cũng lưu — chỉ khi thông tin hữu ích cho future conversations.

Bật/tắt

Auto memory bật mặc định. Tắt qua:

/memory  # toggle trong UI

Hoặc settings:

{
  "autoMemoryEnabled": false
}

Hoặc env: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Nơi lưu trữ

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index, load mỗi session (200 dòng đầu)
├── debugging.md       # Chi tiết debug patterns
├── api-conventions.md # API design decisions
└── ...

MEMORY.md là mục lục. Chỉ 200 dòng đầu được load tự động. Chi tiết nằm trong topic files, Claude đọc khi cần.

⚠️ Lưu ý: Auto memory là machine-local. Mọi worktrees trong cùng git repo chia sẻ một memory directory. Không sync giữa các máy.

Xem và chỉnh sửa

/memory

Lệnh này liệt kê tất cả CLAUDE.md và rules đang load, cho bạn toggle auto memory, và mở memory folder. Mọi file đều là plain markdown — bạn tự sửa, xóa thoải mái.

Khi bạn nói “remember that…” hoặc “always use pnpm”, Claude lưu vào auto memory. Muốn lưu vào CLAUDE.md thì nói rõ “add this to CLAUDE.md”.

Troubleshooting

Claude không follow CLAUDE.md

CLAUDE.md là context, không phải enforcement. Claude đọc và cố follow, nhưng không đảm bảo 100%.

Cách debug:

1. Chạy /memory — kiểm tra file có được load không
2. Kiểm tra location đúng chưa (xem bảng scope ở trên)
3. Viết cụ thể hơn — “Use 2-space indentation” thay vì “format code nicely”
4. Tìm conflicting instructions giữa các file

💡 Tip: Dùng InstructionsLoaded hook để log chính xác file nào load, khi nào, và tại sao.

Instructions mất sau /compact

CLAUDE.md sống sót qua compaction. Sau /compact, Claude đọc lại từ disk. Nếu instruction mất, nghĩa là nó chỉ được nói trong conversation, không nằm trong CLAUDE.md. Thêm vào file để persist.

CLAUDE.md quá lớn

Trên 200 dòng → tốn context, giảm adherence. Giải pháp:

• Tách ra @path imports
• Dùng .claude/rules/ files
• Giữ CLAUDE.md làm index, chi tiết đặt file khác

Tóm tắt nhanh

Muốn làm gì	Dùng gì
Instruction cho cả team	./CLAUDE.md (commit vào git)
Preference cá nhân	~/.claude/CLAUDE.md
Rules theo loại file	.claude/rules/ + paths frontmatter
Claude tự học từ bạn	Auto memory (bật mặc định)
Xem tất cả memory/rules	/memory