Bộ nhớ với CLAUDE.md

Mỗi phiên Claude Code bắt đầu với một cửa sổ ngữ cảnh (context window) trống trơn - Claude không “nhớ” gì từ phiên trước, trừ khi thông tin đó được nạp lại. Có hai cơ chế giúp mang kiến thức xuyên suốt các phiên:

CLAUDE.md - chỉ dẫn do bạn viết tay.
Auto memory - ghi chú do Claude tự viết dựa trên những gì nó học được (lệnh build, mẹo debug, sở thích của bạn…) trong lúc làm việc.

CLAUDE.md so với Auto memory

Cả hai đều được nạp vào đầu mỗi phiên, và đều là ngữ cảnh - nghĩa là Claude cố gắng làm theo chứ không đảm bảo tuân thủ tuyệt đối 100%. Để chặn một hành động bất kể Claude quyết định gì, dùng PreToolUse hook thay vì trông cậy vào CLAUDE.md. Chỉ dẫn càng cụ thể, càng ngắn gọn, Claude càng làm theo nhất quán.

	`CLAUDE.md`	Auto memory
Ai viết	Bạn	Claude
Nội dung	Chỉ dẫn, quy tắc	Điều học được, pattern
Phạm vi	Dự án / cá nhân / tổ chức	Theo từng repo, dùng chung giữa các worktree
Nạp vào	Mọi phiên	Mọi phiên (200 dòng đầu hoặc 25KB, tùy cái nào đến trước)
Dùng cho	Coding standard, quy trình, kiến trúc dự án	Lệnh build, mẹo debug, sở thích Claude tự phát hiện

Dùng CLAUDE.md khi bạn muốn chủ động định hướng hành vi của Claude. Auto memory giúp Claude tự học từ những lần bạn sửa lỗi cho nó mà không cần bạn thao tác thủ công.

Subagent cũng có thể có auto memory riêng - xem cấu hình subagent để biết chi tiết.

`CLAUDE.md` - chỉ dẫn bạn viết tay

CLAUDE.md là file markdown Claude Code đọc vào đầu mỗi phiên làm việc, cho dự án, cho quy trình cá nhân của bạn, hoặc cho cả tổ chức. Bạn viết file này bằng văn bản thuần; Claude đọc nó mỗi khi phiên bắt đầu. Dùng file này để thiết lập:

Quy chuẩn code (coding standards)
Quyết định kiến trúc quan trọng
Thư viện/công cụ ưu tiên sử dụng
Checklist review trước khi commit

Khi nào nên thêm vào CLAUDE.md

Coi CLAUDE.md là nơi ghi lại những điều bạn phải giải thích lại nhiều lần. Nên thêm khi:

Claude mắc lại đúng lỗi cũ lần thứ hai.
Một lượt review phát hiện điều Claude lẽ ra phải biết về codebase này.
Bạn gõ lại đúng một lời sửa/làm rõ mà phiên trước đã từng gõ.
Một thành viên mới trong team cũng cần biết điều tương tự để làm việc hiệu quả.

Chỉ nên giữ những sự thật cần có mặt trong mọi phiên: lệnh build, quy ước, cấu trúc dự án, các quy tắc “luôn luôn làm X”. Nếu một chỉ dẫn là quy trình nhiều bước hoặc chỉ áp dụng cho một phần nhỏ của codebase, hãy tách ra thành skill hoặc rule theo đường dẫn cụ thể thay vì nhét hết vào CLAUDE.md. Xem Xây dựng dần theo thời gian để biết khi nào nên dùng cơ chế nào.

Đặt CLAUDE.md ở đâu

CLAUDE.md có thể đặt ở nhiều cấp, được nạp theo thứ tự từ phạm vi rộng đến hẹp (chỉ dẫn của dự án xuất hiện sau chỉ dẫn cá nhân trong ngữ cảnh):

Phạm vi	Vị trí	Dùng cho	Chia sẻ với
Cấp tổ chức (managed)	Do IT/DevOps triển khai qua MDM	Quy chuẩn công ty, chính sách bảo mật	Toàn bộ nhân viên
Cá nhân, mọi dự án	`~/.claude/CLAUDE.md`	Sở thích cá nhân áp dụng cho mọi dự án	Chỉ bạn
Dự án, dùng chung	`./CLAUDE.md` hoặc `./.claude/CLAUDE.md`	Kiến trúc, quy chuẩn, quy trình của dự án	Cả team (qua git)
Cá nhân, riêng dự án	`./CLAUDE.local.md`	URL sandbox riêng, test data riêng - nhớ thêm vào `.gitignore`	Chỉ bạn, chỉ dự án này

Các file CLAUDE.md/CLAUDE.local.md nằm trong cây thư mục phía trên thư mục làm việc được nạp toàn bộ ngay lúc khởi động. File trong thư mục con chỉ nạp khi Claude thực sự đọc file trong thư mục con đó - xem Cách CLAUDE.md được nạp bên dưới để biết thứ tự đầy đủ.

Với dự án lớn, có thể tách chỉ dẫn thành nhiều file theo chủ đề bằng .claude/rules/ - cho phép giới hạn phạm vi chỉ dẫn theo loại file hoặc thư mục con.

Tạo CLAUDE.md cho dự án

Một CLAUDE.md cấp dự án có thể đặt ở ./CLAUDE.md hoặc ./.claude/CLAUDE.md. Tạo file này và thêm chỉ dẫn áp dụng cho bất kỳ ai làm việc trên dự án: lệnh build/test, coding standard, quyết định kiến trúc, quy ước đặt tên, quy trình thường dùng. Những chỉ dẫn này được chia sẻ với cả team qua version control, nên hãy tập trung vào chuẩn cấp dự án thay vì sở thích cá nhân. Để xác nhận file đã được nạp, chạy /context trong phiên và kiểm tra mục Memory files.

Viết chỉ dẫn hiệu quả

Vì CLAUDE.md là ngữ cảnh chứ không phải cấu hình bắt buộc, cách viết ảnh hưởng trực tiếp đến việc Claude có làm đúng theo hay không:

Độ dài: nên dưới 200 dòng mỗi file. File càng dài càng tốn ngữ cảnh và càng giảm độ tuân thủ. Nếu chỉ dẫn đang phình to, dùng rule theo đường dẫn để chỉ nạp khi Claude thực sự làm việc với file khớp mẫu.
Cấu trúc: dùng heading và bullet để nhóm chỉ dẫn liên quan - dễ quét hơn đoạn văn dài.
Cụ thể, kiểm chứng được: “Dùng thụt lề 2 dấu cách” tốt hơn “format code cho đẹp”; “Chạy npm test trước khi commit” tốt hơn “nhớ test code”.
Nhất quán: hai chỉ dẫn mâu thuẫn nhau khiến Claude chọn bừa một trong hai - rà soát định kỳ CLAUDE.md, các file CLAUDE.md lồng trong thư mục con, và .claude/rules/ để loại bỏ chỉ dẫn lỗi thời. Với monorepo, dùng claudeMdExcludes để bỏ qua CLAUDE.md của team khác không liên quan tới việc bạn đang làm.

Có thể chia nhỏ nội dung bằng cú pháp import @đường-dẫn (xem bên dưới) để tổ chức gọn hơn - nhưng lưu ý file được import vẫn tính vào ngữ cảnh nạp lúc khởi động, không giúp giảm dung lượng.

Import thêm file với `@đường-dẫn`

CLAUDE.md có thể import file khác bằng cú pháp @đường-dẫn/tới/file. File được import sẽ được “trải” ra và nạp vào ngữ cảnh lúc khởi động, cùng lúc với CLAUDE.md chứa nó.

Cả đường dẫn tương đối lẫn tuyệt đối đều dùng được. Đường dẫn tương đối tính từ file chứa câu import, không phải từ thư mục làm việc hiện tại. File được import có thể tiếp tục import file khác, tối đa 4 lớp lồng nhau.

Khi parse import, Claude Code bỏ qua code span và code block trong markdown. Muốn nhắc tới một đường dẫn mà không import nó, bọc trong dấu backtick: viết `@README` giữ nguyên văn bản, còn @README đứng ngoài backtick sẽ được import.

Ví dụ, để đưa README, package.json, và một file hướng dẫn workflow vào ngữ cảnh:

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

Với chỉ dẫn cá nhân riêng cho dự án mà không muốn commit vào version control, tạo file CLAUDE.local.md ở gốc dự án. File này nạp cùng lúc với CLAUDE.md và được xử lý như nhau. Nhớ thêm CLAUDE.local.md vào .gitignore để không bị commit nhầm.

Nếu bạn làm việc trên nhiều git worktree của cùng một repo, CLAUDE.local.md (đã gitignore) chỉ tồn tại ở worktree bạn tạo ra nó. Muốn chia sẻ chỉ dẫn cá nhân giữa các worktree, import một file từ thư mục home thay vào đó:

# Individual Preferences
- @~/.claude/my-project-instructions.md

Một import trong file memory cấp dự án được coi là “external” khi đường dẫn của nó trỏ ra ngoài thư mục làm việc, giống ví dụ import từ thư mục home ở trên. Lần đầu Claude Code gặp import external trong một dự án, nó hiện hộp thoại xác nhận liệt kê các file đó. Nếu bạn từ chối, các import này bị vô hiệu hóa và hộp thoại không hiện lại nữa.

Hộp thoại này bảo vệ bạn khỏi những file người khác commit vào một dự án dùng chung. Import trong file memory cấp người dùng, như ~/.claude/CLAUDE.md và ~/.claude/rules/, là file do chính bạn viết nên được nạp thẳng không cần hộp thoại xác nhận, tin cậy như phần còn lại trong cấu hình cá nhân của bạn.

AGENTS.md

Claude Code đọc CLAUDE.md, không đọc AGENTS.md. Nếu repo của bạn đã dùng AGENTS.md cho các coding agent khác, tạo một CLAUDE.md import lại file đó để cả hai công cụ đọc chung chỉ dẫn mà không phải viết trùng. Bạn cũng có thể thêm chỉ dẫn riêng cho Claude bên dưới câu import - Claude nạp file được import lúc khởi động phiên, rồi đọc tiếp phần còn lại:

@AGENTS.md

## Claude Code
Dùng plan mode cho các thay đổi trong src/billing/.

Symlink cũng dùng được nếu bạn không cần thêm nội dung riêng cho Claude:

ln -s AGENTS.md CLAUDE.md

Lệnh này không in gì ra khi thành công. Ở phiên tiếp theo, chạy /context và kiểm tra CLAUDE.md có xuất hiện trong Memory files không.

Trên Windows, tạo symlink cần quyền Administrator hoặc bật Developer Mode, nên dùng cách import @AGENTS.md thay thế.

Chạy /init sẽ đọc luôn Cursor rules (.cursor/rules/ hoặc .cursorrules) và Copilot rules (.github/copilot-instructions.md), gộp phần liên quan vào CLAUDE.md được sinh ra. Với CLAUDE_CODE_NEW_INIT=1, /init còn đọc thêm AGENTS.md, .devin/rules/, .windsurf/rules/ hoặc .windsurfrules, và .clinerules.

Bạn cũng có thể chạy /import để mang cấu hình từ một coding agent khác được hỗ trợ vào Claude Code - lệnh này gộp một lần các file chỉ dẫn như AGENTS.md vào CLAUDE.md tương ứng, đồng thời mang theo cả MCP server, command, subagent, và skill. Yêu cầu Claude Code v2.1.213 trở lên.

Cách CLAUDE.md được nạp

Claude Code đọc CLAUDE.md bằng cách đi ngược từ thư mục làm việc hiện tại lên thư mục gốc, kiểm tra từng thư mục trên đường đi để tìm CLAUDE.md và CLAUDE.local.md. Vì vậy chạy Claude Code ở foo/bar/ sẽ nạp chỉ dẫn từ cả foo/bar/CLAUDE.md, foo/CLAUDE.md, lẫn mọi CLAUDE.local.md đi kèm.

Mọi file tìm được đều được nối vào ngữ cảnh chứ không ghi đè lên nhau. Xét theo cây thư mục, nội dung được sắp xếp từ gốc filesystem xuống tới thư mục làm việc - với ví dụ foo/bar/, foo/CLAUDE.md xuất hiện trong ngữ cảnh trước foo/bar/CLAUDE.md, nghĩa là chỉ dẫn gần nơi bạn chạy Claude nhất được đọc sau cùng. Trong mỗi thư mục, CLAUDE.local.md được nối sau CLAUDE.md, nên ghi chú cá nhân của bạn luôn là thứ Claude đọc cuối cùng ở cấp đó.

Claude cũng phát hiện CLAUDE.md/CLAUDE.local.md trong các thư mục con của thư mục làm việc. Thay vì nạp ngay lúc khởi động, các file này chỉ được nạp khi Claude thực sự đọc file trong thư mục con đó.

Nếu bạn làm việc trong monorepo lớn mà CLAUDE.md của team khác bị nạp theo không liên quan, dùng claudeMdExcludes để bỏ qua chúng.

Comment HTML dạng block () trong CLAUDE.md bị loại bỏ trước khi nội dung được nạp vào ngữ cảnh của Claude. Dùng chúng để ghi chú cho người bảo trì khác mà không tốn token ngữ cảnh. Comment bên trong code block vẫn được giữ nguyên. Khi bạn mở trực tiếp CLAUDE.md bằng tool Read, comment vẫn hiển thị bình thường.

Nạp từ thư mục bổ sung

Cờ --add-dir cho Claude quyền truy cập thêm thư mục ngoài thư mục làm việc chính. Mặc định, CLAUDE.md trong các thư mục này không được nạp.

Để nạp cả memory file từ thư mục bổ sung, đặt biến môi trường CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Lệnh này nạp CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, và CLAUDE.local.md từ thư mục bổ sung. CLAUDE.local.md bị bỏ qua nếu bạn loại trừ local khỏi --setting-sources.

Tổ chức theo chủ đề với `.claude/rules/`

Với dự án lớn, có thể tách chỉ dẫn thành nhiều file trong .claude/rules/, mỗi file một chủ đề (testing.md, security.md…) - giúp team dễ bảo trì hơn. Rule còn có thể được giới hạn theo đường dẫn file cụ thể, chỉ nạp vào ngữ cảnh khi Claude làm việc với file khớp mẫu, giảm nhiễu và tiết kiệm ngữ cảnh.

Thiết lập rules

Đặt file markdown trong thư mục .claude/rules/ của dự án. Mỗi file nên nói về một chủ đề, đặt tên rõ nghĩa như testing.md hay api-design.md. Mọi file .md được quét đệ quy, nên bạn có thể tổ chức rule vào thư mục con như frontend/ hay backend/:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Chỉ dẫn chính của dự án
│   └── rules/
│       ├── code-style.md   # Quy chuẩn code style
│       ├── testing.md      # Quy ước testing
│       └── security.md     # Yêu cầu bảo mật

Rule không có frontmatter paths được nạp ngay lúc khởi động, cùng độ ưu tiên với .claude/CLAUDE.md.

Project rule bị bỏ qua nếu bạn loại trừ project khỏi --setting-sources.

Rules theo đường dẫn cụ thể

Rule có thể giới hạn phạm vi bằng frontmatter YAML với trường paths. Những rule có điều kiện này chỉ áp dụng khi Claude làm việc với file khớp mẫu đã chỉ định.

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

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

Rule không có trường paths được nạp vô điều kiện và áp dụng cho mọi file. Rule theo đường dẫn kích hoạt khi Claude đọc file khớp mẫu, không phải mỗi lần dùng tool bất kỳ. Việc khớp mẫu cũng hoạt động khi Claude tiếp cận file qua đường dẫn symlink tới thư mục dự án (ví dụ trong một checkout dạng symlink).

Dùng glob pattern trong trường paths để khớp file theo phần mở rộng, thư mục, hoặc kết hợp cả hai:

Pattern	Khớp với
`*/.ts`	Mọi file TypeScript ở bất kỳ thư mục nào
`src/*/`	Mọi file trong thư mục `src/`
`*.md`	File markdown ở gốc dự án
`src/components/*.tsx`	React component trong một thư mục cụ thể

Có thể khai báo nhiều pattern và dùng brace expansion để khớp nhiều phần mở rộng trong một pattern:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Mỗi nhóm brace nhân số pattern được mở rộng lên: src/*.{ts,tsx} mở rộng thành 2 pattern, còn {a,b}/{c,d}/*.{ts,tsx} thành 8. Để giới hạn việc mở rộng, toàn bộ danh sách paths của một rule dùng chung một “ngân sách” 1.000 pattern đã mở rộng và 4 MiB; pattern không chứa dấu ngoặc nhọn không tính vào ngân sách này. Nếu vượt ngân sách, Claude Code dùng nguyên pattern chưa mở rộng - dấu ngoặc nhọn trong đó sẽ được hiểu theo nghĩa đen và không khớp file nào.

Cú pháp glob coi [ là ký tự mở đầu bracket expression như [abc]. Pattern có [ không thể đọc thành bracket expression hợp lệ (ví dụ photos [2024/**) sẽ không hợp lệ: nó không khớp file nào, còn các pattern khác trong rule vẫn hoạt động bình thường. Để khớp ký tự [ theo nghĩa đen, escape thành photos \[2024/**.

Chia sẻ rules giữa các project bằng symlink

Thư mục .claude/rules/ hỗ trợ symlink, nên bạn có thể duy trì một bộ rule dùng chung rồi link vào nhiều project. Symlink được resolve và nạp bình thường; symlink vòng lặp (circular) được phát hiện và xử lý an toàn.

Ví dụ link cả một thư mục dùng chung lẫn một file riêng lẻ:

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

Rules cấp người dùng

Rule cá nhân trong ~/.claude/rules/ áp dụng cho mọi project trên máy bạn. Dùng cho sở thích không gắn với project cụ thể:

~/.claude/rules/
├── preferences.md    # Sở thích code cá nhân
└── workflows.md      # Quy trình làm việc bạn ưa thích

Rule cấp người dùng được nạp trước rule cấp project, nên rule cấp project có độ ưu tiên cao hơn (đọc sau, gần ngữ cảnh hiện tại hơn).

Quản lý CLAUDE.md cho team lớn

Với tổ chức triển khai Claude Code cho nhiều team, bạn có thể tập trung hóa chỉ dẫn và kiểm soát CLAUDE.md nào được nạp.

Triển khai CLAUDE.md cấp tổ chức

Tổ chức có thể triển khai một CLAUDE.md quản lý tập trung, áp dụng cho mọi user trên máy. File này không thể bị loại trừ bởi setting cá nhân.

Tạo file tại vị trí managed policy:
- macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
- Linux và WSL: /etc/claude-code/CLAUDE.md
- Windows: C:\Program Files\ClaudeCode\CLAUDE.md
Triển khai bằng hệ thống quản lý cấu hình: dùng MDM, Group Policy, Ansible, hoặc công cụ tương tự để phân phối file này tới các máy dev. Xem thêm managed settings cho các tùy chọn cấu hình toàn tổ chức khác.

Trường claudeMd cho phép đặt nội dung CLAUDE.md quản lý trực tiếp trong managed-settings.json thay vì triển khai một file riêng:

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

Phạm vi: mọi phiên Claude Code trên máy, ở mọi repository. Với chỉ dẫn riêng cho một repo, hãy commit một CLAUDE.md cấp dự án thay vào đó.

Độ ưu tiên: giống file CLAUDE.md quản lý - nạp trước CLAUDE.md cấp user và cấp dự án.

Chỉ có hiệu lực ở: managed và policy settings. Đặt claudeMd ở user/project/local settings không có tác dụng.

CLAUDE.md quản lý và managed settings phục vụ mục đích khác nhau - dùng settings để thực thi kỹ thuật, dùng CLAUDE.md để hướng dẫn hành vi:

Vấn đề	Cấu hình ở
Chặn tool, lệnh, đường dẫn file cụ thể	Managed settings: `permissions.deny`
Bắt buộc chạy trong sandbox	Managed settings: `sandbox.enabled`
Biến môi trường và điều hướng API provider	Managed settings: `env`
Phương thức xác thực và khóa tổ chức	Managed settings: `forceLoginMethod`, `forceLoginOrgUUID`
Quy chuẩn code style và chất lượng	CLAUDE.md quản lý
Nhắc nhở xử lý dữ liệu, tuân thủ	CLAUDE.md quản lý
Chỉ dẫn hành vi cho Claude	CLAUDE.md quản lý

Quy tắc trong settings được client thực thi bất kể Claude quyết định gì. Chỉ dẫn CLAUDE.md định hướng hành vi của Claude nhưng không phải lớp thực thi bắt buộc.

Loại trừ file CLAUDE.md cụ thể

Trong monorepo lớn, CLAUDE.md của thư mục cha có thể chứa chỉ dẫn không liên quan tới việc bạn đang làm. Setting claudeMdExcludes cho phép bỏ qua file cụ thể theo đường dẫn hoặc glob pattern.

Ví dụ loại trừ một CLAUDE.md ở cấp cao nhất và một thư mục rules từ folder cha. Thêm vào .claude/settings.local.json để việc loại trừ chỉ áp dụng trên máy bạn:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Pattern được so khớp với đường dẫn tuyệt đối bằng cú pháp glob. Bạn có thể cấu hình claudeMdExcludes ở bất kỳ settings layer nào: user, project, local, hoặc managed policy. Các mảng này được gộp (merge) qua các layer.

CLAUDE.md quản lý (managed policy) không thể bị loại trừ - đảm bảo chỉ dẫn cấp tổ chức luôn có hiệu lực bất kể setting cá nhân.

Auto memory - Claude tự ghi chú

Ngoài CLAUDE.md, Claude Code còn tự xây dựng “auto memory” trong quá trình làm việc: lệnh build, mẹo debug, quyết định kiến trúc, sở thích code style… được ghi lại mà không cần bạn chủ động viết. Claude không lưu mọi thứ mỗi phiên - nó tự đánh giá điều gì đáng nhớ cho những lần sau, dựa trên việc thông tin đó có hữu ích cho một cuộc hội thoại tương lai hay không.

Bật/tắt auto memory

Auto memory bật mặc định. Để bật/tắt, mở /memory trong phiên và dùng nút gạt auto memory - thao tác này lưu autoMemoryEnabled vào user settings tại ~/.claude/settings.json. Để tắt riêng cho một project, đặt autoMemoryEnabled trong settings của project đó:

{
  "autoMemoryEnabled": false
}

Để tắt bằng biến môi trường, đặt CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Nơi lưu trữ

Mỗi project có một thư mục memory riêng tại ~/.claude/projects/<project>/memory/. Đường dẫn <project> được suy ra từ git repository, nên mọi worktree và thư mục con trong cùng repo dùng chung một thư mục auto memory. Ngoài git repo, thư mục gốc của project được dùng thay thế.

Để lưu auto memory ở vị trí khác, đặt autoMemoryDirectory trong settings.json (đọc được từ bất kỳ settings scope nào: user, project, local, policy, hoặc --settings):

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

Giá trị này phải là đường dẫn tuyệt đối hoặc bắt đầu bằng ~/. Khi đặt trong .claude/settings.json hoặc .claude/settings.local.json của project, giá trị chỉ có hiệu lực sau khi bạn chấp nhận hộp thoại workspace trust cho folder đó - cùng cơ chế kiểm soát hook.

Thư mục này chứa một file MEMORY.md làm điểm vào, cùng các file chủ đề khác:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Mục lục ngắn gọn, nạp mỗi phiên
├── debugging.md       # Ghi chú chi tiết về pattern debug
├── api-conventions.md # Quyết định thiết kế API
└── ...                # Các file chủ đề khác Claude tự tạo

MEMORY.md đóng vai trò mục lục của thư mục memory. Claude đọc/ghi file trong thư mục này suốt phiên làm việc, dùng MEMORY.md để theo dõi cái gì được lưu ở đâu.

Auto memory chỉ tồn tại trên máy cục bộ (machine-local). Mọi worktree và thư mục con trong cùng git repo dùng chung một thư mục auto memory, nhưng file không được chia sẻ giữa các máy hay giữa các môi trường cloud.

Claude Code tự xoá transcript phiên cũ sau khoảng thời gian cleanupPeriodDays, nhưng loại trừ thư mục auto memory khỏi đợt dọn tự động này - MEMORY.md và các file chủ đề chỉ mất khi bạn hoặc Claude chủ động sửa/xoá.

Cách hoạt động

200 dòng đầu của MEMORY.md, hoặc 25KB đầu - tùy cái nào đến trước - được nạp vào đầu mỗi cuộc hội thoại. Nội dung vượt ngưỡng đó không được nạp lúc khởi động phiên. Claude giữ MEMORY.md ngắn gọn bằng cách chuyển ghi chú chi tiết sang các file chủ đề riêng.

Sau khi Claude ghi vào MEMORY.md, Claude Code đo file theo giới hạn đọc 200 dòng/25KB. Nếu file gần chạm giới hạn, Claude Code nhắc Claude rút gọn: mỗi mục một dòng, chuyển chi tiết sang file chủ đề, gộp hoặc xóa mục đã cũ. Nếu file vượt giới hạn, việc ghi vẫn thành công, nhưng Claude Code trả về lỗi yêu cầu Claude viết lại mục lục - vì phần vượt giới hạn sẽ bị bỏ qua ở lần nạp kế tiếp.

Việc đo chỉ tính phần nội dung thực sự được nạp: frontmatter YAML và comment HTML dạng block bị loại bỏ trước khi tính, nên không tính vào giới hạn.

Giới hạn này chỉ áp dụng cho MEMORY.md. File CLAUDE.md được nạp toàn bộ bất kể độ dài, dù file ngắn hơn vẫn cho độ tuân thủ tốt hơn.

Các file chủ đề như debugging.md hay patterns.md không được nạp lúc khởi động. Claude đọc chúng khi cần, bằng tool đọc file thông thường.

Auto memory của cuộc hội thoại chính không được nạp vào subagent - ngoại trừ khi subagent là một “fork” (kế thừa toàn bộ cuộc hội thoại và system prompt của cha). Auto memory riêng của một subagent, bật bằng trường memory trong cấu hình subagent, là một thư mục tách biệt.

Claude đọc/ghi memory file suốt phiên làm việc. Khi bạn thấy các thông báo như “Saved 2 memories” hay “Recalled 2 memories” trong giao diện Claude Code, đó là lúc Claude đang cập nhật hoặc đọc từ ~/.claude/projects/<project>/memory/.

Khi Claude ghi một memory file có sẵn frontmatter YAML, Claude Code ghi lại thời điểm ghi vào trường modified dưới dạng timestamp ISO 8601 - giúp bạn (và cả Claude, khi đọc lại) biết thông tin đó còn mới hay đã cũ.

Xem lại và chỉnh sửa memory

Auto memory là file markdown thuần, bạn có thể sửa hoặc xóa bất cứ lúc nào. Chạy /memory để duyệt và mở các memory file ngay trong phiên.

Xem và sửa với `/memory`

Lệnh /memory liệt kê vị trí CLAUDE.md, CLAUDE.local.md, và các memory file khác ở cả cấp user lẫn project - kể cả những file CLAUDE.md chưa tồn tại (để bạn tạo mới). Lệnh này cũng cho phép bật/tắt auto memory và mở thư mục auto memory. Chọn một file để mở trong editor của bạn; chọn file chưa tồn tại sẽ tạo file đó trước. Để kiểm tra chính xác file nào đã nạp vào phiên hiện tại, chạy /context.

Editor dạng GUI như VS Code mở file trong cửa sổ riêng, bạn vẫn dùng được phiên trong lúc file đang mở. Editor terminal như Vim sẽ chiếm toàn bộ terminal cho tới khi bạn thoát.

Khi bạn nói Claude nhớ điều gì đó, kiểu “luôn dùng pnpm, không dùng npm” hay “nhớ rằng test API cần Redis chạy sẵn ở local”, Claude lưu nó vào auto memory. Muốn thêm hẳn vào CLAUDE.md thay vào đó, nói thẳng “thêm điều này vào CLAUDE.md”, hoặc tự sửa file bằng /memory.

Xử lý sự cố bộ nhớ

Đây là những vấn đề thường gặp nhất với CLAUDE.md và auto memory, cùng cách debug.

Claude không làm theo CLAUDE.md của tôi

Nội dung CLAUDE.md được đưa vào dưới dạng một user message sau system prompt, không phải một phần của system prompt. Claude đọc và cố gắng làm theo, nhưng không có gì đảm bảo tuân thủ tuyệt đối, nhất là với chỉ dẫn mơ hồ hoặc mâu thuẫn.

Cách debug:

Chạy /context, kiểm tra file có nằm trong Memory files không - nếu không thấy, Claude không đọc được file đó. Dùng /memory để mở và sửa.
Kiểm tra CLAUDE.md liên quan có nằm ở vị trí được nạp cho phiên của bạn không (xem Đặt CLAUDE.md ở đâu).
Viết chỉ dẫn cụ thể hơn - “dùng thụt lề 2 dấu cách” tốt hơn “format code cho đẹp”.
Rà soát các CLAUDE.md khác xem có mâu thuẫn nhau không. Nếu hai file đưa ra hướng dẫn khác nhau cho cùng một hành vi, Claude có thể chọn bừa một trong hai.

Nếu chỉ dẫn cần chạy bắt buộc tại một thời điểm cố định (trước mỗi commit, sau mỗi lần sửa file…), dùng Hooks thay vì CLAUDE.md - hooks thực thi bằng shell command tại các lifecycle event cố định, không phụ thuộc việc Claude có “nhớ” hay không.

Với chỉ dẫn muốn đưa vào cấp system prompt, dùng cờ --append-system-prompt. Cờ này phải truyền lại ở mỗi lần chạy, nên phù hợp với script/automation hơn là dùng tương tác.

Tôi không biết auto memory đã lưu gì

Chạy /memory và chọn thư mục auto memory để duyệt những gì Claude đã lưu. Mọi thứ đều là markdown thuần, bạn đọc/sửa/xóa được.

CLAUDE.md của tôi quá dài

File trên 200 dòng tốn nhiều ngữ cảnh hơn và có thể giảm độ tuân thủ. Dùng rule theo đường dẫn để chỉ nạp chỉ dẫn khi Claude làm việc với file khớp mẫu, hoặc cắt bớt nội dung không cần thiết mỗi phiên. Tách thành import @đường-dẫn giúp tổ chức gọn hơn nhưng không giảm ngữ cảnh, vì file import vẫn nạp lúc khởi động.

Lệnh /doctor đề xuất cắt gọn cho một CLAUDE.md đã commit: nó loại bỏ nội dung Claude có thể tự suy ra từ codebase (cấu trúc thư mục, danh sách dependency, tổng quan kiến trúc) và giữ lại các điểm dễ mắc lỗi, lý do quyết định, và quy ước khác với mặc định của công cụ.

Chỉ dẫn có vẻ mất sau `/compact`

CLAUDE.md ở gốc dự án sống sót qua compaction: sau /compact, Claude đọc lại nó từ đĩa và tiêm lại vào phiên. CLAUDE.md lồng trong thư mục con và rule có frontmatter paths: không tự động tiêm lại - chúng chỉ nạp lại vào lần kế tiếp Claude đọc file trong thư mục con đó, hoặc file khớp mẫu của rule.

Nếu một chỉ dẫn biến mất sau compaction, khả năng cao là nó chỉ được nói trong hội thoại (chưa từng ghi vào CLAUDE.md), nằm trong CLAUDE.md lồng chưa được nạp lại, hoặc là rule theo đường dẫn chưa khớp file nào kể từ đó. Thêm chỉ dẫn chỉ-nói-miệng vào CLAUDE.md để nó tồn tại lâu dài. Xem Điều gì sống sót qua compaction để biết chi tiết đầy đủ.

Xem lại Viết chỉ dẫn hiệu quả để biết thêm về độ dài, cấu trúc, và độ cụ thể.

Tài nguyên liên quan

Debug cấu hình của bạn - chẩn đoán vì sao CLAUDE.md hay settings không có tác dụng
Hooks - thực thi chỉ dẫn bắt buộc, không phụ thuộc việc Claude có “nhớ” hay không
Subagents - subagent có thể có auto memory riêng
Settings - cấu hình hành vi Claude Code bằng settings file
Cửa sổ ngữ cảnh - CLAUDE.md nạp vào ngữ cảnh ở đâu so với phần còn lại