🧠 How Memory Works
🧠 Imagine It This Way: Claude Code doesn't have magical memory. Everything it "remembers" lives in the current session's context window. It's like a desk: whatever is on the desk, it can see. Whatever is removed, it forgets.
A memory of Claude Code is fundamentally different from human memory. It is ephemeral per session: everything you said, everything the agent read, and all the responses stay in that session's context window. When the session ends, the “memory” ends too.
What persists between sessions is: the CLAUDE.md (read automatically), notes saved with /memory, and the codebase (that the agent can reread). None of these are model memory. They are files the model reads again in each session.
In one sentence: context window = temporary workspace; CLAUDE.md and /memory = persistent notes.
💡 The /memory Command
🧠 Imagine It This Way: /memory is a shortcut for saving quick preferences without editing CLAUDE.md. It's like sticking a note on your computer screen that stays there between sessions.
In a session, type /memory opens an editor to save notes that Claude Code will automatically read in all future sessions for that project. Internally, these notes are stored in the generated CLAUDE.md.
Use /memory for quick preferences: "I prefer responses in Portuguese," "always run tests before committing," "the dev database is at localhost:5432." For more complex and structured instructions, edit the CLAUDE.md directly.
In one sentence: /memory saves quick notes that persist between sessions without manually editing CLAUDE.md.
📐 Context Window — The Scarce Resource
🧠 Imagine It This Way: Think of the context window as Claude's RAM. It has a fixed limit. When you fill it with files and conversation, performance drops. Managing context is a critical skill.
The context window has a fixed limit of approximately 200k tokens. Everything competes for this space: the system prompt (CLAUDE.md), your messages, the files the agent reads, the generated responses, and the conversation history. As the session grows, the available space shrinks.
In practice, a productive session lasts between 30 minutes and 2 hours before the context starts to fill up. Longer sessions suffer from gradual degradation: the model starts forgetting details from earlier in the conversation, repeating things, and losing the thread.
⚠️ Signs of a Full Context Window
Claude starts forgetting instructions from the beginning, repeats questions you've already answered, ignores CLAUDE.md rules, or simply stops working well. When you notice this, it's time to compact the context or start a new session.
In one sentence: 200k tokens = fixed limit; long sessions degrade. Actively manage context.
🗜️ Compaction — When and How
🧠 Imagine It This Way: compaction is the automatic "quick summary." When the context fills up, Claude Code compresses the conversation into a shorter summary. It frees up space but loses details.
A compaction happens in two ways: automatic (when the context reaches ~95% of the limit) or manual (via the command /compact). The process summarizes the entire conversation up to that point in a shorter text, freeing up space.
The trade-off is clear: you gain space but lose nuance. Specific details, code decisions, and long explanations can be summarized inaccurately. That's why it's important to create checkpoints (commit, save notes) before compaction happens.
# compactar manualmente (dentro da sessão) /compact # o Claude resume a conversa e libera espaço # use ANTES de o contexto encher pra ter controle
In one sentence: /compact summarizes the conversation to free up space; it loses details, so create checkpoints first.
🔗 Session Handoff Between Conversations
🧠 Imagine It This Way: when a session gets too long, it’s better to start a new one and “hand off the baton.” The art is in transferring the essential context without dragging along the clutter.
There are three strategies for handoff between sessions: (1) /resume resumes the previous session as it was. (2) Start a new session with a manual summary: ask Claude to “summarize what we've done so far in 10 bullets” and paste that into the new session. (3) Save the state in CLAUDE.md or in a notes file.
The best practice is to combine them: commit the code (a checkpoint in git), update CLAUDE.md if anything important changed, and start a new session. That way, the agent starts fresh but has all the necessary context in the files.
In one sentence: commit the code + update the CLAUDE.md + start a new session = clean handoff.
📍 Checkpoint Strategies
🧠 Imagine It This Way: checkpoints prevent loss of progress. A Git commit is the natural checkpoint. Combine it with notes in CLAUDE.md and TODO files for long tasks.
O checkpoint more natural in development is the git commit. Commit after every significant block of work. If the context fills up or the session degrades, you can always start a new session from the latest commit without losing anything.
For very long tasks (hours of work), add intermediate checkpoints: a TODO.md file with the current state, notes in CLAUDE.md about decisions made, and partial commits with descriptive messages. When the new session starts, the agent reads these files and resumes the work.
Tarefa longa? Faça checkpoints: 1. git commit a cada bloco de trabalho 2. Atualize CLAUDE.md se decisões mudaram 3. Use /memory pra notas rápidas 4. Peça ao Claude "resuma o estado atual" 5. Ao iniciar sessão nova, o contexto está nos arquivos
In one sentence: git commit = natural checkpoint; combine it with CLAUDE.md and TODO.md for long tasks.
🧾 Module Summary
Next module:
1.6 — Your Personal Workflow: aliases, tmux, VS Code, and the ultimate setup.