Agent Memory: Bộ nhớ 3 tầng giúp Claude agent không 'lãng trí'

Phân biệt 3 tầng bộ nhớ User, Project, Local trong Claude Code. Cách giữ agent không 'quên' lệnh quan trọng sau 20 phút làm việc và xử lý dữ liệu nhạy cảm đúng cách.

Định nghĩa

Agent Memory là hệ thống lưu trữ phân tầng gồm user, project, và local scope cho phép Claude Code và các subagent duy trì bối cảnh quan trọng xuyên suốt nhiều session, tránh hiện tượng "bức tường 20 phút" khi context window đầy dẫn đến critical instructions bị mất trong quá trình compaction.

Giải thích chi tiết

Vấn đề "Con cá vàng" của LLM Agent

LLM agents không có hippocampus (hải mã - phần não lưu trữ ký ức dài hạn của con người). Chúng không thực sự "học" trong quá trình hội thoại — mỗi turn là một inference mới trên chuỗi text được nối lại từ đầu. Đây là lý do tại sao sau khoảng 20 phút làm việc liên tục (khoảng 200K tokens), agent bắt đầu "đi lạc": context window đầy, hệ thống trigger compaction - một thuật toán nén lossy (mất dữ liệu) tóm tắt chat history cũ. Câu lệnh quan trọng như "Đừng xóa email nào nếu không có approve" có thể bị nén thành "Handle emails carefully" - mất đi ràng buộc an toàn.

Ba tầng phạm vi bộ nhớ

Hệ thống memory của Claude Code chia thành 3 scope tương ứng 3 loại "quên" khác nhau của con người:

User scope (~/.claude/memory/): Tương đương semantic memory (trí nhớ ngữ nghĩa). Lưu trữ xuyên project, bền vững như "bạn là ai", "coding style của bạn (tab vs spaces)", "bạn thích giải thích chi tiết hay ngắn gọn". Được load mỗi khi session bắt đầu.

Project scope (.claude/memory/): Tương đương episodic memory (trí nhớ sự kiện). Chứa quyết định kiến trúc đặc thù repository, convention của team, lịch sử feature. Sống sót qua các session nhưng bị cô lập per codebase — agent trong project A không biết gì về project B.

Local scope: Tương đương working memory (bộ nhớ làm việc). Chỉ tồn tại trong session hiện tại, không ghi file. Dùng cho dữ liệu nhạy cảm hoặc task một lần mà persistence là rủi ro chứ không phải tài sản.

Cơ chế Compaction-Aware Persistence

Insight cốt lõi: tách biệt chat history (volatile RAM) và memory files (disk storage). Chat history dùng để trò chuyện, memory files dùng để lưu state. Các quy tắc an toàn quan trọng được ghi vào MEMORY.md hoặc AGENTS.md trong thư mục .claude/memory/ sẽ được re-inject fresh mỗi turn, trong khi chat history bị tóm tắt lossy khi context đầy. Điều này giống như cách con người không nhớ verbatim cuộc trò chuyện 3 tiếng trước, nhưng nhớ rõ các quyết định quan trọng được ghi trong notebook.

Mandatory Retrieval

Khác với "contextual recall" bị động (hy vọng LLM tự nhớ), Agent Memory yêu cầu explicit retrieval. Subagent phải chủ động gọi memory_search trước khi hành động, tương tự cách senior developer tra cứu documentation trước khi viết code thay vì dựa vào trí nhớ.

Ví dụ thực tế

Freelancer chuyển đổi giữa nhiều client

Anh Minh là freelancer full-stack tại Hà Nội, cùng lúc làm 3 project: app giao đồ ăn tích hợp VietQR (Node.js), landing page bán hàng kiểu Shopee Affiliate (Next.js), và hệ thống CRM legacy (Laravel). User scope lưu trong ~/.claude/memory/ quy tắc cá nhân của anh: "Luôn dùng semicolon, prefer functional programming, giải thích bằng tiếng Việt có thuật ngữ tiếng Anh".

Project scope trong .claude/memory/ của từng repo lưu riêng: app giao đồ ăn có "Dùng Repository pattern cho database, không bao giờ log thông tin nhạy cảm kiểu số thẻ VietQR", landing page có "Dùng shadcn/ui cho components, màu primary là #FF6B35 theo brand client". Khi spawn subagent để refactor từng project, agent tự động load đúng context mà Minh không cần nhắc đi nhắc lại "nhớ là project này dùng Repository pattern nhé" — tránh lỗi architectural mismatch.

Team review PR với tribal knowledge

Team 5 người ở TP.HCM phát triển ví điện tử startup dùng subagent chuyên trách làm code review. Trong .claude/memory/, họ lưu AGENTS.md ghi lại các quy tắc không thể tìm thấy trong code: "Tribal knowledge: API ZaloPay phải retry tối đa 3 lần nếu lỗi 502, constraint này không có trong comment hay type signature". Khi spawn security-auditor agent để review PR liên quan đến payment, agent tự động retrieve thông tin này trước khi phân tích, bắt được lỗi logic mà linter không phát hiện được.

Phân tích dữ liệu nhạy cảm (sensitive data)

Chị Lan là data analyst làm việc với file CSV chứa thông tin CCCD/CMND và số tài khoản ngân hàng của khách hàng. Thay vì load dữ liệu vào Project scope (lưu vĩnh viễn), chị dùng Local scope — agent phân tích dữ liệu trong session hiện tại, generate báo cáo tổng hợp (không chứa PII), rồi session kết thúc. Dữ liệu gốc không bao giờ được ghi vào disk qua memory files, đảm bảo compliance theo Nghị định 13/2023/NĐ-CP về bảo vệ dữ liệu cá nhân trong khi vẫn tận dụng được khả năng reasoning của AI.

Ứng dụng

Developer độc lập / Freelancer: Dùng User scope để duy trì coding style cá nhân và preferences xuyên suốt mọi project. Không cần setup lại "tôi thích import sorting kiểu gì" mỗi khi chuyển repo.

Team Lead / Startup CTO: Dùng Project scope để institutionalize kiến trúc vào .claude/memory/. Khi tuyển thêm dev mới hoặc spawn subagent làm việc, họ tự động inherit "tribal knowledge" (những quyết định kiến trúc chỉ tồn tại trong đầu của lead dev) mà không cần onboarding meeting.

Data / Security Analyst: Dùng Local scope cho các tác vụ exploratory data analysis (EDA) trên dữ liệu nhạy cảm. Đảm bảo "quên" dữ liệu gốc sau khi session kết thúc, chỉ giữ lại insights đã được anonymize.

DevOps / Platform Engineer: Dùng Project scope để lưu infrastructure patterns: "Microservice này phải dùng Redis cluster, không dùng local cache" — subagent tự động apply khi generate deployment config.

So sánh

Phạm vi	Vị trí lưu trữ	Thời gian tồn tại	Loại trí nhớ tương đương	Dùng cho	Ví dụ cụ thể
User	`~/.claude/memory/`	Vĩnh viễn, cross-project	Semantic memory	Coding style, identity	Prefer 4 spaces, dùng tiếng Việt
Project	`./.claude/memory/`	Theo project, cross-session	Episodic memory	Architecture, conventions	"Dùng Repository pattern", "Màu brand #FF6B35"
Local	Session RAM	Chỉ trong session	Working memory	Sensitive data, one-time	Analyze CSV chứa CCCD/CMND, không lưu lại
Chat History	Context window	Cho đến khi compaction	Short-term memory	Conversation flow	"Bước trước chúng ta đã thử..." (bị mất sau 20 phút)

Kết luận: Chat history là bộ nhớ ngắn hạn dễ bay hơi, trong khi User và Project scope là bộ nhớ dài hạn "cứng". Local scope là clipboard tạm thời cho dữ liệu nhạy cảm. Để agent hoạt động reliable trong production, bạn phải chuyển critical constraints từ chat (volatile) sang memory files (persistent).