Mỗi session của Claude Code khởi động với một context window trống. Chương này giải thích các cơ chế giúp Claude nhớ kiến thức xuyên session (CLAUDE.md, auto memory), cách quản lý context window khi nó đầy dần, và cách resume/branch/checkpoint để không mất công việc.
5.1 Hai cơ chế memory
Claude Code có hai hệ thống memory bổ sung cho nhau. Cả hai đều được load ở đầu mỗi conversation, và đều là context — không phải cấu hình bắt buộc. Muốn chặn hành động cứng, dùng PreToolUse hook, không phải CLAUDE.md.
| CLAUDE.md files | Auto memory | |
|---|---|---|
| Ai viết | Bạn | Claude |
| Nội dung | Instructions, rules | Learnings, patterns |
| Scope | Project, user, hoặc org | Theo repository, share qua worktrees |
| Load vào | Mọi session | Mọi session (200 dòng hoặc 25KB đầu của MEMORY.md) |
| Dùng cho | Coding standards, workflows, kiến trúc | Build commands, debugging insights, preferences |
Dùng CLAUDE.md khi bạn muốn chủ động hướng dẫn Claude. Auto memory để Claude tự học từ các lần bạn sửa/chỉnh mà không tốn công thủ công.
5.2 CLAUDE.md files
File markdown chứa instructions bền vững cho project, workflow cá nhân, hoặc toàn tổ chức. Claude đọc chúng ở đầu mỗi session.
Khi nào bổ sung vào CLAUDE.md
- Claude lặp lại cùng một lỗi lần thứ hai
- Code review bắt lỗi mà Claude lẽ ra phải biết về codebase này
- Bạn gõ lại cùng một correction/clarification như session trước
- Một teammate mới sẽ cần đúng context đó để làm việc
Giữ lại những fact Claude cần trong mọi session: build commands, conventions, layout project, rules "always do X". Nếu là quy trình nhiều bước hoặc chỉ liên quan một phần codebase, chuyển sang skill hoặc path-scoped rule.
Vị trí đặt file (theo load order, rộng → hẹp)
| Scope | Location | Purpose |
|---|---|---|
| Managed policy | macOS: /Library/Application Support/ClaudeCode/CLAUDE.mdLinux/WSL: /etc/claude-code/CLAUDE.mdWindows: C:\Program Files\ClaudeCode\CLAUDE.md | Instructions toàn tổ chức (IT/DevOps) |
| User instructions | ~/.claude/CLAUDE.md | Preferences cá nhân, mọi project |
| Project instructions | ./CLAUDE.md hoặc ./.claude/CLAUDE.md | Instructions share cho team |
| Local instructions | ./CLAUDE.local.md (thêm vào .gitignore) | Preferences riêng của project |
CLAUDE.md và CLAUDE.local.md trong cây thư mục phía trên working directory được load đầy đủ khi launch. File trong subdirectory được load on demand khi Claude đọc file trong thư mục đó.
Tip: Chạy
/initđể sinh CLAUDE.md tự động — Claude phân tích codebase và tạo file với build/test commands, conventions. Nếu đã có CLAUDE.md,/initđề xuất cải tiến thay vì ghi đè. ĐặtCLAUDE_CODE_NEW_INIT=1để bật flow tương tác nhiều pha (CLAUDE.md + skills + hooks).
Viết instructions hiệu quả
CLAUDE.md tiêu tốn token trong context window. Cách viết ảnh hưởng trực tiếp đến mức độ Claude tuân thủ.
- Size: nhắm dưới 200 dòng mỗi file. File dài hơn tốn context và giảm adherence.
- Structure: dùng markdown headers + bullets để nhóm instructions liên quan.
- Specificity: viết cụ thể, kiểm chứng được.
- "Use 2-space indentation" thay vì "Format code properly"
- "Run
npm testbefore committing" thay vì "Test your changes" - "API handlers live in
src/api/handlers/" thay vì "Keep files organized"
- Consistency: nếu hai rule mâu thuẫn, Claude có thể chọn tùy tiện. Rà soát định kỳ để loại bỏ instructions cũ/xung đột.
Import file khác với @path
CLAUDE.md có thể import file khác bằng cú pháp @path/to/import. File được import expand và load vào context lúc launch, cùng với CLAUDE.md tham chiếu nó.
- Chấp nhận cả relative và absolute path. Relative path resolve theo file chứa import, không theo working directory.
- Import có thể đệ quy, tối đa 4 hops.
- Parser bỏ qua Markdown code spans và fenced code blocks. Để nhắc một path mà không import, bọc trong backtick:
`@README`giữ nguyên text, còn@READMEngoài backtick thì import.
See @README for project overview and @package.json for available npm commands for this project.
# Additional Instructions
- git workflow @docs/git-instructions.md
Để share instructions cá nhân qua nhiều worktrees, import từ home directory (vì CLAUDE.local.md gitignored chỉ tồn tại trong worktree tạo ra nó):
# Individual Preferences
- @~/.claude/my-project-instructions.md
Warning: Lần đầu gặp external imports, Claude Code hiện dialog phê duyệt liệt kê các file. Nếu từ chối, imports bị vô hiệu và dialog không hiện lại.
AGENTS.md
Claude Code đọc CLAUDE.md, không đọc AGENTS.md. Nếu repo đã dùng AGENTS.md, tạo CLAUDE.md import nó:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Hoặc symlink nếu không cần thêm nội dung Claude-specific:
ln -s AGENTS.md CLAUDE.md
Trên Windows, symlink cần quyền Administrator/Developer Mode nên dùng import @AGENTS.md. Chạy /init trong repo có sẵn AGENTS.md (hoặc .cursorrules, .windsurfrules...) sẽ đọc và tích hợp phần liên quan.
Thứ tự load CLAUDE.md
Claude Code đi lên cây thư mục từ working directory, kiểm tra CLAUDE.md và CLAUDE.local.md ở mỗi cấp. Tất cả file được concatenate (không ghi đè nhau), thứ tự từ filesystem root xuống working directory — nên instructions gần nơi launch được đọc sau cùng. Trong mỗi thư mục, CLAUDE.local.md đứng sau CLAUDE.md.
- Block-level HTML comment (
<!-- notes -->) bị strip trước khi inject vào context (dùng để ghi chú cho maintainer mà không tốn token). Comment trong code block được giữ lại. --add-dirmặc định không load CLAUDE.md từ thư mục thêm. Bật bằng:
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
.claude/rules/ — chia nhỏ instructions
Với project lớn, tách instructions thành nhiều file trong .claude/rules/. Rules có thể scope theo path để chỉ load khi Claude làm việc với file khớp.
your-project/
├── .claude/
│ ├── CLAUDE.md # Main project instructions
│ └── rules/
│ ├── code-style.md
│ ├── testing.md
│ └── security.md
Rule không có paths frontmatter được load lúc launch với priority như .claude/CLAUDE.md. Rule có paths chỉ kích hoạt khi Claude đọc file khớp pattern:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
Glob patterns thường dùng: **/*.ts, src/**/*, *.md, src/components/*.tsx. Brace expansion: src/**/*.{ts,tsx}.
- Share rules qua projects bằng symlink:
ln -s ~/shared-claude-rules .claude/rules/shared - User-level rules ở
~/.claude/rules/áp cho mọi project, load trước project rules (project rules có priority cao hơn).
Quản lý cho team lớn
- Deploy org-wide CLAUDE.md ở managed policy location — không thể bị exclude bởi individual settings. Hoặc dùng key
claudeMdtrongmanaged-settings.json:
{
"claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}
- Exclude CLAUDE.md không liên quan (monorepo) bằng
claudeMdExcludestrong.claude/settings.local.json:
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}
Managed policy CLAUDE.md không thể bị exclude. Phân biệt: managed settings để enforce kỹ thuật (permissions.deny, sandbox.enabled), managed CLAUDE.md để hướng dẫn hành vi.
5.3 Auto memory
Auto memory để Claude tích lũy kiến thức xuyên session mà bạn không viết gì. Claude tự lưu note khi làm việc: build commands, debugging insights, kiến trúc, code style, workflow habits. Claude không lưu mỗi session — nó tự quyết định thông tin nào đáng nhớ cho tương lai.
Bật/tắt
Mặc định on. Tắt qua toggle trong /memory, hoặc settings, hoặc env var:
{ "autoMemoryEnabled": false }
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
Storage location
Mỗi project có thư mục riêng tại ~/.claude/projects/<project>/memory/. <project> suy từ git repo, nên mọi worktree/subdirectory trong cùng repo share một thư mục auto memory. Đổi vị trí bằng autoMemoryDirectory (phải là absolute path hoặc bắt đầu ~/).
~/.claude/projects/<project>/memory/
├── MEMORY.md # Index cô đọng, load vào mọi session
├── debugging.md # Notes chi tiết
├── api-conventions.md
└── ...
Cách hoạt động
- Chỉ 200 dòng đầu hoặc 25KB đầu (tùy cái nào đến trước) của
MEMORY.mdđược load ở đầu mỗi conversation. Phần vượt ngưỡng không được load. - Topic files (
debugging.md...) không load lúc startup — Claude đọc on demand khi cần. - Sau khi Claude ghi
MEMORY.md, nếu file gần chạm limit, Claude Code nhắc rút gọn; nếu vượt limit, ghi vẫn thành công nhưng trả về error yêu cầu viết lại index (vì phần vượt sẽ bị drop ở lần load kế). YAML frontmatter và HTML comment bị strip nên không tính vào limit. - Limit này chỉ áp cho
MEMORY.md. CLAUDE.md luôn load đầy đủ bất kể độ dài (dù ngắn hơn thì adherence tốt hơn). - Auto memory của main conversation không load vào subagents — trừ fork, kế thừa parent.
Khi thấy "Writing memory" / "Recalled memory" trong giao diện, Claude đang cập nhật/đọc từ thư mục memory. File là plain markdown, có thể edit/xóa bất cứ lúc nào.
5.4 Lệnh /memory
/memory liệt kê các CLAUDE.md, CLAUDE.local.md, và memory file khác trên user + project scope; cho toggle auto memory; và mở thư mục auto memory. Chọn file bất kỳ để mở trong editor.
- Để kiểm tra file thực sự đã load vào session hiện tại, chạy
/context. - Khi bạn bảo Claude "always use pnpm, not npm" hay "remember that...", Claude lưu vào auto memory. Muốn thêm vào CLAUDE.md thay vì memory, nói "add this to CLAUDE.md" hoặc tự edit qua
/memory.
5.5 Context window
Context window (mặc định ~200K token) chứa mọi thứ Claude biết trong session: instructions, file đọc, response của chính Claude, và cả nội dung không bao giờ hiện trong terminal.
Load lúc startup (trước khi bạn gõ gì)
| Thành phần | Ghi chú |
|---|---|
| System prompt | Instructions cốt lõi. Luôn load đầu tiên. Bạn không bao giờ thấy |
| Auto memory (MEMORY.md) | 200 dòng / 25KB đầu |
| Environment info | Working dir, platform, shell, OS, git status |
| MCP tools (deferred) | Tên tools; schema đầy đủ load on demand qua tool search |
| Skill descriptions | Mô tả một dòng; body load khi thực sự dùng skill |
~/.claude/CLAUDE.md | Preferences global |
| Project CLAUDE.md | File quan trọng nhất bạn tạo được |
Note: Skill có
disable-model-invocation: truekhông nằm trong list startup — tốn 0 context cho đến khi bạn gọi/name. Đặt flag này cho skill có side-effect (commit, deploy, gửi message).
Khi Claude làm việc
- Mỗi lần Read file cộng thêm token vào context (thường là phần lớn context usage). Prompt càng cụ thể ("fix the bug in auth.ts"), Claude càng đọc ít file.
- Path-scoped rules load tự động cùng file khớp pattern.
- PostToolUse hook: chỉ đưa thông tin vào context của Claude qua field
hookSpecificOutput.additionalContext. Plain stdout khi exit 0 chỉ ghi vào debug log, không vào context. - Subagent: chạy trong context window riêng. File reads của nó không chạm context của bạn; chỉ final summary + metadata trailer nhỏ quay về. Đây là cách chính để tiết kiệm context cho task research nặng.
Quản lý context trong session
| Command | Tác dụng |
|---|---|
/context | Hiện phân tích context hiện tại theo category + gợi ý tối ưu |
/compact [instructions] | Thay history bằng summary có cấu trúc, tùy chọn focus |
/clear | Bắt đầu context trống (conversation cũ được lưu, resume được) |
/memory | Mở/edit các file CLAUDE.md và auto memory |
/compact focus on the auth bug fix
Chiến lược trước khi auto-compaction chạy:
- Compact có focus trước khi bắt đầu task dài mới — summary giữ đúng cái bạn chọn.
- Clear giữa các task khi chuyển việc không liên quan — history cũ chèn ép file cần dùng và tốn token mỗi message.
- Delegate large reads cho subagent.
Điều gì sống sót qua compaction
Khi session dài compact, Claude Code tóm tắt history. Số phận instructions tùy cách chúng được load:
| Mechanism | Sau compaction |
|---|---|
| System prompt và output style | Không đổi; không thuộc message history |
| Project-root CLAUDE.md và unscoped rules | Re-inject từ disk |
| Auto memory | Re-inject từ disk |
Rules có paths: frontmatter | Mất đến khi đọc lại file khớp |
| Nested CLAUDE.md trong subdirectory | Mất đến khi đọc lại file trong thư mục đó |
| Invoked skill bodies | Re-inject, cap 5,000 token/skill và 25,000 token tổng; drop cũ trước |
| Hooks | Không liên quan; hooks chạy như code, không phải context |
Nếu một instruction biến mất sau
/compact, nó chỉ được nói trong conversation hoặc nằm trong nested CLAUDE.md chưa reload. Thêm instructions chỉ-nói-miệng vào CLAUDE.md để chúng bền vững. Skill bodies bị truncate giữ phần đầu file — đặt instructions quan trọng gần đầuSKILL.md.
Khi context đầy
Claude Code tự compact khi gần chạm limit — context đầy không kết thúc session. Nếu cần cửa sổ lớn hơn thay vì conversation nhỏ hơn: Fable 5, Sonnet 5, Opus 4.6+, Sonnet 4.6 hỗ trợ context window 1 triệu token (chọn model variant [1m]; Sonnet 5 chạy 1M không cần variant).
5.6 Sessions — resume, continue, branch
Một session là conversation đã lưu, gắn với một project directory. Claude Code lưu liên tục vào transcript file cục bộ để bạn resume, branch, hoặc chuyển task.
Resume
| Command | Tác dụng |
|---|---|
claude --continue | Resume session gần nhất trong thư mục hiện tại |
claude --resume | Mở session picker |
claude --resume <name> | Resume session theo tên (khớp chính xác thì vào thẳng) |
claude --resume <session-id> | Resume theo ID (dùng cho session từ claude -p/SDK) |
claude --from-pr <number> | Session picker lọc theo pull request |
/resume | Chuyển conversation khác từ trong session đang chạy |
Session claude -p / Agent SDK không hiện trong picker nhưng resume được qua session ID. Chạy từ đúng thư mục tạo session (ID lookup scope theo project directory hiện tại + worktrees của nó).
Resumed session khôi phục: conversation history đầy đủ (gồm tool calls + results), model đang dùng, permission mode (trừ plan và bypassPermissions — không bao giờ khôi phục; auto chỉ khôi phục khi account còn đủ điều kiện), active goal, và scheduled tasks chưa hết hạn.
Không khôi phục tự động: --mcp-config, --settings, --plugin-dir, --fallback-model, directory thêm bằng --add-dir — phải truyền lại khi resume. Còn settings.json/settings.local.json được đọc lại lúc launch nên không cần truyền lại.
Session picker
Phím tắt trong picker (/resume hoặc claude --resume):
| Shortcut | Action |
|---|---|
↑ / ↓ | Điều hướng |
→ / ← | Mở/thu nhóm session |
Enter | Resume session đang chọn |
Space | Preview nội dung session |
Ctrl+R | Rename session đang chọn |
/ (hoặc ký tự) | Vào search mode; dán URL PR để tìm session tạo ra nó |
Ctrl+A | Hiện session từ mọi project trên máy |
Ctrl+W | Hiện session từ mọi worktree của repo (chỉ repo nhiều worktree) |
Ctrl+B | Lọc theo git branch hiện tại |
Esc | Thoát picker / search mode |
Mặc định picker hiện session interactive của worktree hiện tại. Chọn session từ worktree khác cùng repo → resume tại chỗ; từ project không liên quan → copy lệnh cd + resume vào clipboard.
Đặt tên session
| Khi nào | Cách |
|---|---|
| Lúc startup | claude -n auth-refactor |
| Trong session | /rename auth-refactor (tên hiện trên prompt bar) |
| Từ picker | Highlight session, nhấn Ctrl+R |
| Khi accept plan | Plan mode đặt tên từ nội dung plan (nếu bạn chưa đặt) |
Session không đặt tên vẫn có default display name (vd my-app-3f) và một AI-generated title (tóm tắt prompt đầu, viết bởi model nhỏ/nhanh). Nhưng chỉ tên bạn tự đặt mới là resume handle — default name và generated title thì không.
Branch
Branch tạo bản sao conversation đến hiện tại và chuyển bạn vào đó, giữ nguyên bản gốc. Dùng để thử hướng khác mà không mất đường đang đi.
/branch try-streaming-approach
Từ command line:
claude --continue --fork-session
- Session gốc không đổi, vẫn còn trong picker.
/branchin ra hai session ID: branch mới và bản gốc. - Permissions "allow for this session" không mang theo sang branch mới.
- Session tạo bằng
/branch/--fork-sessioncó session ID riêng, hiện thành row riêng trong picker. - Resume cùng session trong hai terminal không fork → message hai bên interleave vào một transcript.
Export và vị trí transcript
/exportmở menu copy conversation ra clipboard hoặc lưu file text (messages + tool outputs render dạng đọc được). Truyền filename để ghi thẳng.- Transcript lưu dạng JSONL tại
~/.claude/projects/<project>/<session-id>.jsonl. Format là internal, đổi giữa các version — script parse trực tiếp có thể vỡ. Để build trên session data, dùng/exporthoặc các script interface.
claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'
| Để | Set |
|---|---|
Move storage khỏi ~/.claude | CLAUDE_CONFIG_DIR |
| Đổi retention 30 ngày | cleanupPeriodDays (settings.json) |
| Chặn ghi transcript mọi mode | CLAUDE_CODE_SKIP_PROMPT_HISTORY |
| Chặn ghi cho một lần non-interactive | --no-session-persistence |
5.7 Checkpointing
Claude Code tự động track file edits của Claude, cho phép undo nhanh và rewind về trạng thái trước nếu có gì đi chệch.
Cách checkpoint hoạt động
- Mỗi user prompt tạo một checkpoint mới (snapshot code trước prompt).
- Giữ snapshot cho 100 checkpoint gần nhất trong session.
- Checkpoint lưu cùng conversation → session resume vẫn
/rewindđược. - Tự cleanup cùng session sau 30 ngày (
cleanupPeriodDays).
Rewind và summarize
Chạy /rewind, hoặc nhấn Esc hai lần khi ô prompt trống, để mở rewind menu. (Nếu ô prompt có text, double Esc xóa text đó thay vì mở menu — text được lưu vào input history, nhấn Up để lấy lại.)
Menu liệt kê từng prompt đã gửi. Chọn điểm rồi chọn action:
- Restore code and conversation — revert cả code lẫn conversation về điểm đó
- Restore conversation — rewind message, giữ code hiện tại
- Restore code — revert file changes, giữ conversation
- Summarize from here — nén conversation từ điểm này trở đi thành summary, giải phóng context
- Summarize up to here — nén conversation trước điểm này, giữ nguyên message sau
- Never mind — quay lại không thay đổi
Hai option restore code chỉ hiện khi checkpoint được chọn có file changes để revert.
Restore vs. Summarize: Restore revert state (undo code/conversation). Summarize nén một phần conversation thành AI summary mà không đổi file trên disk. Message gốc vẫn được giữ trong transcript để Claude tham chiếu lại nếu cần. Để hướng summary focus, highlight option Summarize và gõ instructions inline chỗ add context (optional) rồi Enter.
Rewind past a cleared conversation: Nếu bạn đã
/cleartrong cùng process, rewind menu hiện thêm entry/resume <session-id> (previous session)ở đầu list để quay lại conversation trước khi/clear. Có đến khi bạn thoát hoặc resume session khác (cần v2.1.191+).
Giới hạn
- Không track file sửa bởi bash command (
rm,mv,cp...). Chỉ track edit trực tiếp qua file editing tools của Claude. - Không track external changes — sửa tay ngoài Claude Code hoặc edit từ session khác thường không được capture (trừ khi trùng file session hiện tại sửa).
- Không thay thế version control. Coi checkpoint là "local undo", Git là "permanent history". Vẫn dùng Git cho commits, branches, lịch sử dài hạn.
Xem thêm
content/en/docs/claude-code/memory.md— CLAUDE.md hierarchy và auto memorycontent/en/docs/claude-code/context-window.md— trực quan hóa context window, điều gì survive compactioncontent/en/docs/claude-code/sessions.md— resume, branch, export, vị trí transcriptcontent/en/docs/claude-code/checkpointing.md— rewind code và conversationcontent/en/docs/claude-code/sub-agents.md— delegate research sang context window riêngcontent/en/docs/claude-code/skills.md— package workflow load on demandcontent/en/docs/claude-code/hooks-guide.md— enforce hành động cứng bằng hookscontent/en/docs/claude-code/settings.md— cấu hình settings files