Managing Context & Memory in Claude Code: /compact, CLAUDE.md & Token Budget (2026)

If you have used Claude Code for long, multi-file sessions, you have probably hit this: things are going well, then Claude starts "forgetting" a decision you locked in 20 minutes ago, or the terminal warns that context is nearly full. This article pulls together the three pieces that most guides keep separate - in-session context, cross-session memory, and token budget - into one practical workflow. If you are brand new, read a beginner guide first; but if you run multi-file sessions every day, this one is for you.

Context vs memory in Claude Code: what's the difference?

These two words get used interchangeably, but they are completely different things - and mixing them up is the root of most trouble when it comes to managing context in Claude Code. Context (the context window) is the short-term memory Claude can "see" right now: your question, the contents of files it has read, the conversation history, tool results it has run, plus the CLAUDE.md that was loaded at the start of the session. It is finite, and it vanishes when you end the session or type /clear.

Memory (Claude Code's persistent memory) lives across sessions. There are two kinds: CLAUDE.md - the file you write to brief Claude about your project - and auto memory - where Claude saves what it learns on its own. The key point: memory does not live inside context, it gets reloaded into context every time a new session starts.

Here is a one-liner so you never mix them up again: context is what Claude is thinking right now, memory is what Claude always knows.

Why does every Claude Code session start with an empty context?

A lot of people quietly assume Claude "remembers" yesterday's conversation the way a coworker would. It does not. Fundamentally, a language model has no built-in long-term memory - Claude does not actually remember the conversation. Every new session is a clean, blank context window. The feeling that "it remembers my project" actually comes from Claude Code automatically reloading memory (CLAUDE.md and auto memory) at the start of each session, not from the model recalling anything.

This is exactly why memory exists: it is the bridge that compensates for a context window that "loses its memory" after every reset. Once you understand this, you stop expecting Claude to remember on its own and start deliberately writing down what needs to be remembered. The fresh-context-window-per-session behavior is described in the official Claude Code documentation on the context window (accessed 2026-08-09).

The practical consequence: any decision that only lives in the chat, without being written to a file, is at risk of evaporating - when the session ends, or even sooner if context gets compacted. We will come back to this in the /compact section.

Measure context with /context and the token state

You cannot manage what you cannot measure. The first command to commit to memory is /context. Type it during a session and Claude Code lists the Memory files currently loaded (which CLAUDE.md files made it into context) and the percentage of the context window in use.

/context

This is the most reliable way to check whether your CLAUDE.md actually made it into context - do not guess, look at the Memory files list. On top of that, the status line in your terminal shows the token percentage in use in real time. When context reaches a high threshold, Claude Code will automatically compact (auto-compact) so the session does not stall.

The auto-compact threshold sits around 80-83% per the official Claude Code documentation (accessed 2026-08-09), but this number can change between versions.

/compact - compacting context the right way

This is the most important command in the article. /compact reads the entire current conversation, produces a condensed summary, then replaces the old conversation with that summary. The result: it frees up most of the tokens while keeping the thread of work intact - Claude still knows what you are doing, just in compressed form.

# automatic compaction
/compact

# compact with instructions on what to keep
/compact keep the DB schema decisions and the files I edited, drop the debug logs

When should you compact? My practical rule: be proactive around 60%, do not wait until 90%. Compacting early, while the conversation is still "clean," produces a far better summary than forcing a compaction once context is already crammed - at that point Claude has to drop a lot of things and the summary tends to miss details. Using /compact <instructions> to spell out what to keep is a big quality booster.

⚠️ Important note on limits: compaction is lossy. Anything that lives only in the conversation and has not been written to a file can be lost permanently after a compaction. This is a real bug that causes people to "lose" decisions mid-task. The table below shows what survives and what does not:

The takeaway in short: before you compact, tell Claude to "write the important decisions into CLAUDE.md" - then run /compact. Whatever is on disk is safe.

/clear vs /compact - which one should you use?

These two commands are easy to confuse, but they serve very different situations. Short version: /compact when you are continuing the same work, /clear when you are switching to something else.

The thing to remember: whether you /clear or /compact, cross-session memory (CLAUDE.md and auto memory) is still reloaded - so you do not lose your project's "baseline knowledge," only the temporary conversation. When you switch tasks, do not hesitate to /clear: hanging onto an unrelated old conversation just burns tokens and distracts Claude.

CLAUDE.md - the long-term memory you write yourself

CLAUDE.md is the most powerful memory tool you control directly. It loads automatically into context every session, in order from the broadest scope to the narrowest. Claude Code reads several levels of CLAUDE.md and merges them together:

The broad-to-specific load order means narrower levels (project, local) can add to broader ones. The fastest way to get started: run /init - Claude Code will scan your codebase and scaffold a starter CLAUDE.md for the project.

/init

Writing an effective CLAUDE.md: keep it short - under about 200 lines. A longer file not only costs context every session but also lowers adherence (Claude struggles to prioritize when there are too many instructions). Write things that are specific and verifiable: "use 2-space indentation" beats "format it nicely." For long content, use @path to import other files, and put context-specific conventions into path-scoped .claude/rules/ (loaded only when you open a file matching the glob) to save context. To go deeper on how to structure this file, see the guide on writing a proper CLAUDE.md file - that spoke owns the details, so I will not repeat them here.

Auto memory - when Claude remembers across sessions on its own

This is a relatively new surface (2026) that a lot of older guides skip. Beyond the CLAUDE.md you write, Claude Code can itself save what it learns while working into a project-specific memory folder, something like ~/.claude/projects/<project>/memory/.

In there, MEMORY.md acts as an index and has the top of the file loaded each session; the other topic files are loaded on-demand only when needed. You manage this feature with the /memory command (toggle it via the autoMemoryEnabled option), and you will see notices like "Saved N memories" / "Recalled N memories" when Claude writes or recalls learnings.

/memory

To be clear on the distinction: CLAUDE.md is what you write (instructions - how you want Claude to work), while auto memory is what Claude writes (learnings - what it has picked up). The two complement each other. The auto memory mechanism and its load limits are laid out in the official Claude Code memory documentation (accessed 2026-08-09).

Token budget - working cheaper and more sustainably

This is the part competitors almost entirely leave blank. Newer models are context-aware: they track how many tokens are left and automatically answer more concisely, using tools more sparingly as context runs low. But do not just leave it to chance - the six rules below keep your sessions both cheap and stable:

Rule 3 is worth emphasizing: when you need Claude to read a large directory or a long log, hand it to a subagent instead of reading it straight into the main session. The subagent works in a separate context and returns only its conclusion - your main context stays light. This way of organizing work is covered in detail in the article on using subagents to isolate context. As for the comments in rule 6, human notes in CLAUDE.md wrapped in <!-- --> never reach Claude's context, so you can annotate freely without spending tokens.

The context & memory management workflow (practical checklist)

Pull it all together into a six-step routine you can run every day:

1. Scaffold CLAUDE.md: run /init to generate a starter file from the codebase.
2. Trim CLAUDE.md: keep it under 200 lines, specific and verifiable; move context-specific conventions into .claude/rules/.
3. Monitor: type /context periodically during long sessions, and keep an eye on the token % in the status line.
4. Compact early: /compact around 60%, with instructions on what to keep (for example, keep decisions + edited files).
5. Reset on task switch: /clear when you move to an unrelated task.
6. Lock in decisions: tell Claude to "update CLAUDE.md with this decision" before compacting or ending the session, so nothing is lost to compaction.

Speed things up with a ready-made kit (AgentKit)

Writing a decent CLAUDE.md, .claude/rules/, and subagent config for each project takes real time. If you want to move faster, some ready-made kits like the AgentKit bundle — now $149 (from $198) ship with sample CLAUDE.md/rules plus subagents that have their own context - which fits the very token-budget principles above. I have a closer look at what AgentKit is and whether it is worth it if you want to weigh it up; but for context management, the /context, /compact, and /clear commands above remain the foundation whether or not you use a kit.

Common mistakes & how to avoid them

Honestly, these are the spots where I - and plenty of others - trip up the most:

• Losing decisions after /compact: because they were only said in chat, never written to a file -> always write important decisions into CLAUDE.md before compacting.
• A bloated CLAUDE.md: a file that is too long both wastes tokens and lowers adherence -> split things out into path-scoped .claude/rules/.
• Rules / nested CLAUDE.md not auto-reloading after compact: path-scoped rules and subdirectory CLAUDE.md do not reload themselves -> reopen the file that matches the glob to reactivate them.
• Conflicting instructions across multiple CLAUDE.md files: when levels contradict each other, Claude may pick in a way you did not intend -> review for consistency across user/project/local.

If you run into other snags, see the roundup on fixing common Claude Code errors. And to understand the bigger picture of how Claude Code fits its pieces together, check out the article on the difference between skills, subagents, hooks, and MCP.

Frequently asked questions (FAQ)

How is /compact different from /clear?

/compact compresses the conversation into a condensed summary and keeps the thread of work - use it when you are continuing the same task but context is full. /clear wipes the conversation entirely and starts an empty context - use it when you switch to a different task. Both still reload CLAUDE.md and auto memory.

At what % does auto-compact trigger?

Per the official documentation, auto-compact kicks in when context usage is around 80-83%. Even so, you should proactively /compact earlier, around 60%, for a higher-quality summary with less loss. The exact threshold can change between versions.

Does CLAUDE.md survive /compact?

Yes. The CLAUDE.md at your project root is re-injected from disk, so it is always there after a compaction. But nested CLAUDE.md in subdirectories and path-scoped rules do not auto-reload - you need to reopen the matching file to reactivate them.

When should I /compact?

Proactively, when context usage is around 60% - do not wait until 90%. Compacting early, while the conversation is still "clean," gives a better summary. Add instructions too, for example /compact keep the schema decisions and edited files, so Claude retains exactly what you need.

Where is auto memory stored?

Claude Code saves learnings to a project-specific memory folder (something like ~/.claude/projects/<project>/memory/), with MEMORY.md as the index, whose top portion is loaded each session. You toggle and inspect it with the /memory command. Verify the exact path live by version.

How do I reduce tokens in Claude Code?

Compact early with /compact at ~60%, keep CLAUDE.md lean (< 200 lines), delegate heavy reading to a subagent so it does not eat the main context, split tasks into phases, and /clear when you switch work. Those are the most effective token-budget levers.

Conclusion + next steps

The whole workflow in one line: measure with /context -> compact early with /compact at ~60% -> /clear when you switch tasks -> lock decisions into CLAUDE.md, and let auto memory handle the learnings. Master the three pieces - context, memory, and token budget - and your long sessions stop "forgetting" and get noticeably cheaper. Next step: learn how to write a proper CLAUDE.md file so your memory really earns its keep, and dig deeper into what context engineering is when you want to optimize at the architectural level.