Memory trong Claude Code hoạt động như thế nào?

Về bản chất kỹ thuật, các mô hình ngôn ngữ lớn (LLM) là hệ thống stateless: không lưu trạng thái giữa các lần gọi. Mỗi khi bạn mở một phiên mới, Claude Code bắt đầu từ một "bảng trắng" — không có ký ức về cấu trúc thư mục, lỗi đã xử lý tối qua hay quy ước đặt tên riêng của dự án. Hệ thống memory sinh ra để vá đúng khoảng trống đó.

Thiết lập bộ nhớ tử tế giúp bạn xóa bỏ "Repetition Tax" — khoản thời gian và token lãng phí mỗi phiên chỉ để nhắc lại vai trò, quy tắc và môi trường làm việc. Thay vì nhồi một tệp hướng dẫn khổng lồ dễ gây nhiễu, Claude Code chia việc ghi nhớ thành hai lớp: chỉ dẫn cố định (CLAUDE.md) và kinh nghiệm tích lũy (auto memory).

Vì sao mỗi phiên Claude Code lại mất trí nhớ?

Mọi phiên làm việc với Claude Code đều bị bó trong một cửa sổ ngữ cảnh (context window). Lúc khởi động, bối cảnh là con số 0. Việc dựng lại ngữ cảnh bằng tay mỗi lần chính là "Repetition Tax": bạn tốn token và sự tập trung để gõ lại những thứ lặp đi lặp lại như "dự án dùng TypeScript" hay "API nằm trong thư mục src/api".

Đây không phải giới hạn có thể lách bằng cách dán thật nhiều thông tin vào đầu phiên. Cửa sổ ngữ cảnh càng đầy, không gian suy luận còn lại cho các tác vụ xử lý code phức tạp phía sau càng hẹp — nhồi ngữ cảnh thủ công thực chất là tự bào mòn chất lượng đầu ra.

Vì thế Claude Code cần một cơ chế "briefing" tự động: nạp sẵn các dữ liệu nền (build command, cấu trúc thư mục, quy ước) ngay khi khởi động, và tách bạch giữa ghi nhớ hội thoại tạm thời với bộ nhớ ổn định lâu dài. Nhờ đó Claude phản hồi nhất quán, bất kể bạn đang ở phiên thứ mấy của dự án.

Hai hệ thống bộ nhớ: CLAUDE.md và auto memory

Claude Code vận hành trên hai hệ thống bộ nhớ bổ trợ nhau, cả hai đều được nạp vào ngữ cảnh ngay đầu mỗi phiên. Điểm mấu chốt: Claude coi chúng là ngữ cảnh để tham khảo, không phải cấu hình bắt buộc tuân thủ — muốn chặn cứng một hành vi, bạn phải dùng hook thay vì viết vào CLAUDE.md.

CLAUDE.md đóng vai "hiến pháp" của dự án: những gì Claude phải làm. Auto memory giống một cuốn nhật ký hành trình, giúp Claude nhận ra các mẫu đã gặp để không lặp lại sai lầm cũ. Dùng CLAUDE.md khi bạn muốn chủ động định hướng hành vi; để auto memory tự đúc kết những gì nó học được từ các lần bạn sửa lưng nó. Muốn xem bức tranh rộng hơn về cách CLAUDE.md, rules, skills và hooks phối hợp điều hướng Claude, xem Hướng dẫn về Claude memory files và cơ chế điều hướng.

CLAUDE.md: viết chỉ dẫn Claude luôn tuân theo

Để CLAUDE.md thực sự có tác dụng, hãy tư duy theo hướng cấu hình chứ đừng mô tả kiểu văn xuôi. Chỉ dẫn cần cụ thể tới mức kiểm chứng được. Thay vì "format code cho đẹp", hãy viết "dùng thụt lề 2 khoảng trắng, chạy npm test trước khi commit". Câu càng mơ hồ, Claude càng dễ diễn giải sai.

Giới hạn 200 dòng là một mốc đáng nhớ. Vượt qua nó, khả năng tuân thủ của mô hình bắt đầu giảm rõ: các chỉ dẫn nằm giữa tệp hay bị bỏ sót. Nếu hướng dẫn phình to, hãy tách bớt sang thư mục .claude/rules/ hoặc dùng @import, thay vì cố nhét tất cả vào một chỗ. Nội dung tối thiểu nên có: lệnh build/test, sơ đồ các thư mục trọng yếu và những quy ước đặt tên đặc thù.

Một tệp CLAUDE.md gọn gàng có thể trông như sau:

### Build & Test
 
- Build: `npm run build`
- Test: `npm test` (cần Redis chạy local ở cổng 6379)
 
### Quy ước
 
- Dùng thụt lề 2 khoảng trắng, ưu tiên async/await hơn callback
- API handler nằm ở `src/api/handlers/`
- Mọi endpoint mới đều phải có integration test

Muốn đi sâu vào cách viết và tối ưu một tệp CLAUDE.md, xem CLAUDE.md: Tối ưu hóa ngữ cảnh cho Claude Code.

Đặt CLAUDE.md ở đâu: bốn cấp phạm vi và thứ tự nạp

Claude Code nạp chỉ dẫn theo hình tháp, từ rộng đến hẹp. Tệp ở cấp càng cụ thể càng được nạp sau và ưu tiên cao hơn, tức là ghi đè lên cấp rộng hơn khi có mâu thuẫn:

1. Managed Policy (cấp tổ chức) — do IT/DevOps quản lý để áp tiêu chuẩn bảo mật và tuân thủ cho toàn công ty. Đây là lớp người dùng không tự tắt được.
   • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
   • Linux/WSL: /etc/claude-code/CLAUDE.md
   • Windows: C:\Program Files\ClaudeCode\CLAUDE.md
2. User (cấp cá nhân) — ~/.claude/CLAUDE.md, nơi lưu sở thích riêng áp dụng cho mọi dự án của bạn (ví dụ quy ước code, lối tắt công cụ cá nhân).
3. Project (cấp dự án) — ./CLAUDE.md hoặc ./.claude/CLAUDE.md, commit lên Git để cả team dùng chung.
4. Local (cấp cục bộ) — ./CLAUDE.local.md, ưu tiên cao nhất, thường nằm trong .gitignore để giữ URL sandbox hay dữ liệu test riêng của bạn.

Claude đọc các tệp này bằng cách đi ngược cây thư mục từ nơi bạn khởi động lên tới gốc, rồi nối tất cả lại thành ngữ cảnh — chỉ dẫn gần nơi bạn làm việc nhất sẽ được đọc sau cùng.

Tổ chức chỉ dẫn: imports (@path) và .claude/rules/

Khi dự án phình to, dồn tất cả vào một tệp sẽ sớm phá vỡ giới hạn 200 dòng. Dùng cú pháp @path/to/file (ví dụ @README.md hay @package.json) để Claude tự tham chiếu nội dung mà không cần bạn copy-paste. Lưu ý: tệp được import vẫn nạp đầy vào ngữ cảnh lúc khởi động, nên @import giúp tổ chức chứ không tiết kiệm token.

Với các quy tắc đặc thù theo module, hãy dùng thư mục .claude/rules/. Mỗi tệp lo một chủ đề, và bạn có thể thêm YAML frontmatter với trường paths để giới hạn phạm vi (path-specific rules). Cách này tiết kiệm token thật sự, vì rule chỉ được nạp khi Claude chạm vào tệp khớp mẫu:

---
paths:
  - "src/api/**/*.ts"
---
 
# Quy tắc cho tầng API
 
- Mọi endpoint phải kiểm tra đầu vào (input validation)
- Trả response theo định dạng chuẩn { data, error }

Auto memory: khi Claude tự ghi nhớ qua từng phiên

Auto memory là hệ thống tự lưu kinh nghiệm của Claude Code, bật sẵn từ bản v2.1.59 trở đi. Khác với bộ nhớ giới hạn slot trên bản Claude web, auto memory ở đây không giới hạn số mục: nó ghi thẳng ra các tệp markdown cục bộ mà bạn đọc và sửa được bất cứ lúc nào.

Dữ liệu nằm ở ~/.claude/projects/<project>/memory/, dùng chung cho mọi worktree của cùng một repo. Tệp MEMORY.md đóng vai mục lục (index); đầu phiên Claude chỉ nạp 200 dòng đầu (hoặc 25KB) của tệp này để tiết kiệm ngữ cảnh. Các ghi chú chi tiết được đẩy sang những tệp chủ đề như debugging.md hay commands.md, và chỉ được đọc khi Claude thật sự cần tới.

Khi giao diện hiện dòng "Writing memory" hay "Recalled memory", đó là lúc Claude đang cập nhật hoặc đọc lại thư mục này. Không phải phiên nào Claude cũng ghi lại điều gì — nó tự cân nhắc thông tin nào đáng nhớ cho các cuộc trò chuyện sau. Muốn tắt hẳn, đặt biến môi trường CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Thiết kế auto memory tốt: phân loại và chống lỗi thời

Auto memory tự phân loại thông tin thành các tệp theo chủ đề để về sau dễ truy xuất, và giữ MEMORY.md luôn cô đọng bằng cách đẩy chi tiết ra tệp riêng. Bài toán khó của mọi hệ thống bộ nhớ là chống lỗi thời: một ghi chú đúng ở tháng trước có thể sai sau một lần refactor.

Một số cấu hình có thêm cơ chế bảo trì ngầm thường gọi là auto-dream: cứ sau khoảng 24 giờ, Claude chạy một lượt phản tỉnh (reflective pass) tách khỏi luồng làm việc chính, nên không thêm độ trễ cho phiên của bạn. Chu kỳ này thường đi qua bốn pha:

1. Orient — đọc tệp index để nắm những gì đang được ghi nhớ.
2. Gather signal — quét lại nhật ký phiên để tìm chỉnh sửa và mẫu mới.
3. Consolidate — hợp nhất thông tin, đổi ngày tương đối thành ngày tuyệt đối, xóa các mục mâu thuẫn.
4. Prune — cắt bỏ những gì đã lỗi thời để tệp index luôn nằm trong giới hạn và giữ hiệu năng.

Dù có hay không có auto-dream, nguyên tắc cho bạn vẫn giống nhau: định kỳ mở thư mục memory ra đọc, xóa tay những ghi chú đã cũ. Vì tất cả chỉ là markdown, bạn toàn quyền kiểm soát.

Bộ nhớ cho agent tự xây: API Memory Tool

Nếu bạn đang xây agent tự hành trên API của Anthropic thay vì dùng Claude Code, hệ thống cung cấp Memory Tool — một hệ thống tệp (filesystem) đọc/ghi phía client tại đường dẫn /memories. Claude gọi tool để tạo, đọc, cập nhật, xóa các tệp bộ nhớ; ứng dụng của bạn mới là bên thực thi các thao tác đó. Khác với auto memory, ở đây bạn tự sở hữu nơi lưu, tự định nghĩa schema và tự quyết cái gì được giữ lại.

Kết quả thực tế là một agent biết "tiếp nối" công việc: một coding agent nhớ được các quyết định kiến trúc từ phiên đầu, một research agent tích lũy dần kho dữ kiện đã xác thực. Kỹ thuật đáng dùng là ghép Memory Tool với context compaction: khi cửa sổ ngữ cảnh đầy, compaction tóm tắt hội thoại ở phía server, còn Memory Tool đảm bảo các "hard fact" không rơi rớt qua ranh giới tóm tắt đó. Hai cơ chế này được thiết kế để đi cùng nhau.

Lệnh /memory và quy trình quản lý bộ nhớ hằng ngày

Lệnh /memory trong CLI là điểm điều khiển trung tâm: nó liệt kê mọi tệp CLAUDE.md, CLAUDE.local.md và rules đang được nạp trong phiên, cho bạn bật/tắt auto memory và mở nhanh thư mục memory để xem hay dọn dẹp. Khi bạn nói "nhớ giúp tôi là luôn dùng pnpm chứ không phải npm", Claude sẽ lưu câu đó vào auto memory; muốn ghi vào CLAUDE.md thì bảo thẳng "thêm dòng này vào CLAUDE.md".

Với dự án mới, chạy /init để Claude tự dựng một tệp CLAUDE.md nền từ codebase, rồi tinh chỉnh dần. Một thói quen tốt cho các phiên dài là dùng một sub-agent ở cuối phiên để rà lại toàn bộ hội thoại và đề xuất những gì đáng đưa vào bộ nhớ — cách này giữ memory luôn sắc và tránh tích tụ ngữ cảnh rác.

Khắc phục sự cố khi Claude không tuân theo bộ nhớ

Khi Claude bắt đầu phớt lờ chỉ dẫn, hãy đi qua danh sách kiểm tra sau:

• Kiểm tra việc nạp. Chạy /memory; nếu tệp không có trong danh sách, nghĩa là Claude không hề thấy nó.
• Đếm dòng. Xác nhận tệp dưới 200 dòng — càng dài, khả năng tuân thủ càng giảm.
• Phạm vi đường dẫn. Một rule trong CLAUDE.md ở thư mục con chỉ nạp khi Claude đọc tệp trong thư mục đó; chuyển các quy tắc "luôn áp dụng" lên tệp gốc.
• Sau khi /compact. Nếu chỉ dẫn biến mất sau /compact, khả năng là nó chỉ được nói trong hội thoại hoặc nằm ở CLAUDE.md thư mục con chưa nạp lại. Tệp CLAUDE.md ở gốc dự án thì được đọc lại tự động; hãy đưa các chỉ dẫn quan trọng về đó.

Cuối cùng, nhớ ranh giới giữa hướng dẫn và cưỡng chế. CLAUDE.md chỉ là ngữ cảnh, không phải rào chắn cứng. Với những việc bắt buộc phải chạy đúng thời điểm — như lint trước mỗi lần commit hay chặn một lệnh nguy hiểm — hãy dùng PreToolUse hook thay vì dặn dò bằng lời. Muốn biết chính xác tệp nào đang được nạp và vì sao, cấu hình InstructionsLoaded hook để ghi lại nhật ký nạp chỉ dẫn.

Tài liệu tham khảo

• How Claude remembers your project — Claude Code Docs
• Give Claude Permanent Memory — Faisal Haque (Plain English)
• Stop Re-Introducing Yourself to Claude — Substack
• Claude Code Memory Management: The Complete Guide 2026 — Data Science Collective
• You're Using 1 of 3 Memory Systems in Claude Code — Substack
• How Memory Works in Claude Code Harness — Kanav Anand
• Memory and Dreaming for Self-Learning Agents — YouTube