🧩

Context · Memory · Handoff Complete Guide

Claude Code

Three "Memory" Mechanisms in Claude Code — When Each Is Used and How They Differ

There are three things that can be called "memory" in Claude Code. Each has completely different scope and lifetime.

1. Context — Current Conversation (Volatile)

The contents of the current ongoing conversation. Has a token limit (context window), so earlier parts get truncated as conversations grow. Can be compressed with /compact or fully reset with /clear.

Only valid within a single session. Disappears when you close the session (though --resume can reopen the session itself).

2. Memory — Cross-Session Memory (Persistent)

Persistent memory stored as .md files in ~/.claude/projects/project/memory/. Persists across session closures — even the next day.

Saved via explicit instructions like "remember this", "always use bun", or auto-saved when Claude judges something important. Can be deleted with "forget this".

Memory ≠ CLAUDE.md. CLAUDE.md is project rules (shared doc committed to Git). Memory is personal preferences, feedback, and work context (local only).

3. Handoff — Session Transfer

Mechanisms for moving sessions to different environments.

claude -c (--continue): instantly resume last session
claude -r (--resume): past session selector
/remote-control: access current session from mobile/browser
Session transfer between claude.ai ↔ Claude Code

Handoff carries Context as-is. Memory auto-loads always, so no separate transfer needed.

Context vs Memory vs Handoff

Criteria	Context	Memory	Handoff
Definition	Current conversation content	Persistent cross-session memory	Session transfer mechanism
Lifetime	Gone on session end	Persistent (file-based)	Moves with session
Storage	RAM	`~/.claude/projects//memory/.md`	Session history DB
Limit	Token window (model-dependent)	MEMORY.md 200-line limit	None
Commands	`/compact`, `/clear`	"remember this", "forget this"	`-c`, `-r`, `/remote-control`
Git tracked	No	No (local only)	No

Memory vs CLAUDE.md — Don't Confuse!

Criteria	Memory	CLAUDE.md
Content	Personal preferences, feedback, work context	Project rules, code conventions, architecture
Scope	You only (local)	Whole team (Git committed)
Example	"User prefers Korean" "Skip trailing summaries"	"Use SQLite, no jsonb" "Run commands in Docker"

"Why Doesn't It Remember?" Troubleshooting

⚠

Why doesn't it remember what I said earlier?

→ Context was compressed/truncated. After long sessions, earlier conversation is auto-compressed. Use /compact with emphasis, or record important decisions in CLAUDE.md.

⚠

Why doesn't it remember yesterday's conversation?

→ Not saved to Memory. Explicitly save with "remember this", or the content wasn't important enough for auto-save. Use "always do X" for important patterns.

⚠

Want to continue yesterday's session?

→ Use Handoff. claude -c for recent, claude -r to pick from list. Note: older sessions may have compressed Context.

How to Use

1

Context: /compact to compress, /clear to reset, statusline to check remaining

2

Memory: "remember this" or auto-save. Located at ~/.claude/projects/*/memory/

3

Handoff: claude -c (resume recent), claude -r (select session), /remote-control (mobile)

4

Memory ≠ CLAUDE.md — Memory is personal (local), CLAUDE.md is project rules (Git)

Source

Anthropic Docs