Memory and Context Management

Claude Code has a memory system that lets it remember information across conversations. While CLAUDE.md files give static project instructions, the memory system captures dynamic, evolving knowledge -- like design decisions you made last week, your preferred approach to a recurring problem, or notes about the current state of a project.

In this lesson, you will learn how memory works, how to manage it, and how to use context effectively throughout your sessions.

What You Will Learn

• How Claude Code's memory system works
• How to save, view, and manage memories
• The difference between memory and CLAUDE.md
• How context works within a conversation
• Techniques for effective context management
• Using /compact and /clear strategically

---

How Memory Works

Claude Code's memory system stores information in Markdown files within a .claude/ directory. When you tell Claude Code to remember something, it creates a memory entry that is loaded into future conversations.

Saving a Memory

You can explicitly ask Claude Code to remember something:

Remember that we decided to use Zod for all input validation
in this project, replacing the old Joi validators.

Claude Code saves this as a memory entry. In future conversations, it recalls this decision and uses Zod for validation without you having to mention it again.

The /memory Command

Use the /memory command to interact with the memory system:

/memory

This shows you all current memory entries. From here you can:

• View existing memories
• Edit memories that need updating
• Delete memories that are no longer relevant

What Gets Remembered

Good things to store in memory:

• Design decisions: "We chose PostgreSQL over MongoDB because we need strong consistency for financial transactions"
• Work in progress: "The authentication refactoring is half done. The login flow is complete but the registration flow still uses the old system"
• Preferences: "I prefer detailed explanations when reviewing code changes"
• Recurring context: "The staging environment is at staging.example.com and uses the staging-db database"

Memory vs CLAUDE.md

When should you use memory versus CLAUDE.md?

Use CLAUDE.md for:

• Stable project conventions that rarely change
• Build commands and architecture documentation
• Team-wide coding standards
• Information that every developer on the team needs

Use memory for:

• Personal preferences and working style
• Temporary project context (current sprint goals, in-progress work)
• Decisions made during conversations that should persist
• Dynamic information that changes frequently

Think of CLAUDE.md as the team handbook and memory as your personal notebook.

---

Context Management Within a Conversation

Every Claude Code conversation has a context window -- the total amount of information it can hold in working memory. Understanding how to manage context is crucial for productive long sessions.

What Counts as Context

Everything in the conversation uses context:

• Your messages: Every prompt you type
• Claude Code's responses: Including explanations, code, and tool results
• File contents: Every file Claude Code reads
• Command output: Results from running shell commands
• CLAUDE.md files: Loaded at the start of each conversation
• Memory entries: Loaded at the start of each conversation

The Context Window Size

With Claude Opus 4.6, the context window is up to 1 million tokens. That is a lot, but in a long session with many file reads and edits, you can still reach the limit. Here is a rough sense of scale:

• A typical source code file: 200-500 tokens
• A large file (1000+ lines): 3,000-10,000 tokens
• A short conversation message: 50-200 tokens
• The output of npm test on a large project: 2,000-5,000 tokens

Signs You Are Running Low on Context

Claude Code tells you when context is getting full. Watch for:

• A context usage indicator showing high percentage
• Claude Code's responses becoming less detailed or losing earlier context
• Explicit warnings about context limitations

---

Strategies for Effective Context Management

Use /compact Regularly

The /compact command is your most important context management tool. It summarizes the conversation so far into a condensed form, freeing up space for new work:

/compact

When to use it:

• After completing a major task within a session
• When switching to a different area of the codebase
• When Claude Code starts losing track of earlier context
• Proactively every 15-20 exchanges in a long session

Use /clear When Switching Tasks

If you are moving to a completely unrelated task, use /clear to start fresh:

/clear

This wipes the conversation and gives you a full context window for the new task. Your CLAUDE.md and memory are reloaded, so project context is preserved.

Be Specific About File Reads

Instead of asking Claude Code to read broad sets of files, be targeted:

# Less efficient (reads many files)
Read all the files in the src/services/ directory

# More efficient (reads only what is needed)
Read src/services/auth.ts and src/services/token.ts

Resume Previous Conversations

Instead of re-explaining context from a previous session, resume it:

# Resume the most recent conversation
claude --continue

# Choose from recent conversations
claude --resume

This loads the previous conversation's context, so you can pick up where you left off.

Break Large Tasks into Sessions

For very large tasks (like a major refactoring), break the work across multiple conversations:

• Session 1: Plan the refactoring and make changes to Module A
• Session 2 (using --continue or a fresh start): Make changes to Module B
• Session 3: Make changes to Module C and run the full test suite

Each session gets a fresh context window while memory and CLAUDE.md maintain continuity.

---

Advanced Context Techniques

Priming Context

At the start of a session for complex work, prime the context with the most relevant information:

I am working on the payment processing system.
The key files are:
- src/services/payment.ts (main service)
- src/routes/payment.ts (API routes)
- src/models/transaction.ts (data model)
Please read these files before we begin.

This ensures Claude Code has the most relevant code loaded before you start making requests.

Using Conversations as Checkpoints

When you reach a good stopping point in a long session:

1. Run /compact to compress the conversation
2. Verify Claude Code still has the important context by asking a quick question
3. Continue working with the compressed context

Context-Efficient Prompts

Write prompts that give Claude Code what it needs without unnecessary verbosity:

# Good: Specific and efficient
Fix the null check in handlePayment (src/services/payment.ts line 42).
The amount parameter can be undefined when called from the webhook handler.

# Less efficient: Forces Claude Code to search broadly
Something is broken in the payment system somewhere.
Can you look through all the files and figure it out?

---

Key Takeaways

• Claude Code's memory system stores information in .claude/ directory files, persisting across conversations
• Use memory for personal preferences and dynamic decisions; use CLAUDE.md for stable project conventions
• The /memory command lets you view, edit, and delete memory entries
• Context management is crucial for long sessions: use /compact regularly and /clear when switching tasks
• Be specific about file reads to conserve context space
• Resume previous conversations with --continue or --resume instead of re-explaining context
• Break very large tasks across multiple sessions, using memory and CLAUDE.md for continuity
• Prime context at the start of complex sessions by asking Claude Code to read key files first