Memory and context: what sticks, what resets

You spent two hours teaching Claude Code how your billing package really works. You corrected the test command three times. You explained that OrderService is legacy and that new code goes through CheckoutFacade. Then you closed the laptop for lunch. After lunch you open a new session, ask a simple question, and watch the agent propose a change that reintroduces every mistake you already fixed.

That whiplash is not a character flaw in you or in the model. It is how session memory works. This is Part 5 of the Claude Code tutorial: what sticks across sessions, what resets when you run /clear or start fresh, how the context window fills and gets noisy, and how to keep git and project files as the source of truth. Parts 1 through 4 covered install, talking to a codebase, slash commands, and skills. Part 6 goes deep on instruction files. Here we map the layers so you stop treating chat history like a durable design doc.

What you will learn

Why session chat is temporary by design
What reloads every session (CLAUDE.md, and often auto memory)
How auto memory differs from files you commit
How context fills, why long sessions get noisy, and when to compact or clear
A practical “what sticks” table you can teach a teammate in five minutes
Habits that put durable truth in git, not in yesterday’s transcript

Product details move. Ground truth for this post is Anthropic’s public Claude Code docs on memory and the context window. Re-check those pages before you write team policy. Auto memory is a product feature that can save learnings across sessions; treat enablement and content as something you verify in your environment, not something you assume is identical on every machine.

The mental model: four layers, not one brain

People talk about “Claude’s memory” as if there were a single sticky note that survives forever. In practice you are juggling several different stores with different rules.

Four memory layers: session chat that resets, CLAUDE.md loaded each session, auto memory that can persist learnings, …

Picture four layers stacked under your keyboard:

Session chat. The conversation you are having right now: prompts, tool outputs, intermediate plans, side quests. This is working memory. It resets when you start a new session or run /clear. Compaction can also replace the long middle of a chat with a summary so the window can keep going.
CLAUDE.md (and related instruction files). Markdown you write. Loaded at the start of each session (with rules about scope and path). This is your standing brief: commands, style, safety, architecture notes that should not depend on who remembers last Tuesday.
Auto memory. Notes Claude can write for itself based on corrections and patterns it decides are worth keeping. Documented as a product feature that accumulates learnings across sessions for a project. Machine-local in the documented layout. You should verify whether it is enabled and what it actually stored.
Git and project files. Code, tests, configs, README, committed CLAUDE.md, CI. This is the durable source of truth for the product. If it only lived in chat, it did not really land.

Rule of thumb: Chat is a whiteboard. CLAUDE.md is the laminated wall card. Auto memory is the sticky notes Claude leaves for next time. Git is the building. When the whiteboard gets wiped, the building should still stand.

Session chat: what resets, and why that is useful

Every Claude Code session begins with a fresh context window for that conversation. Official memory docs state that two mechanisms carry knowledge across sessions: CLAUDE.md files you write, and auto memory notes Claude can accumulate. The chat transcript itself is not the cross-session database.

You reset chat on purpose when you:

Run /clear to drop the current conversation and free the window for unrelated work
Start a new session after closing the old one
Hand a task to a subagent that gets its own window (research stays out of your main transcript)

That design is frustrating only if you treated the transcript as documentation. It is helpful if you treat chat as temporary workspace. Long sessions accumulate failed approaches, abandoned file reads, partial refactors, and contradictory instructions (“use the old path” then “no, use the new path”). Those tokens still sit in the window. The model can get pulled toward yesterday’s wrong turn simply because the wrong turn is still on the page.

What “reset” does not mean

Clearing chat does not uninstall the product. It does not delete your repo. It does not erase a committed CLAUDE.md. It does not automatically delete auto memory files on disk. It means the conversational working set for that thread is gone or summarized away, depending on whether you cleared or compacted.

If you need a fact after a reset, put it where the next session will load it: a project instruction file, a test, a comment that is actually true, a short note in the PR, or (if appropriate) a memory entry you have reviewed. Do not hope the model “just knows” from last week’s vibe.

CLAUDE.md: loaded each session on purpose

CLAUDE.md files are the deliberate way to give Claude persistent instructions. You write them in plain text. Claude reads them at the start of every conversation (with documented rules about managed, user, project, and local scopes). They are context, not hard enforcement: Claude treats them as guidance. For hard blocks on tools or paths, you use permissions, hooks, and settings, not a polite paragraph in markdown.

That distinction matters for beginners. Writing “never push to main” in CLAUDE.md is a strong hint. It is not a physical lock on git. Pair behavioral notes with real rails when the cost of a mistake is high.

What belongs in CLAUDE.md (preview for Part 6, enough to use today):

Project brief in a few sentences
Build, test, and lint commands that actually work
Code style that is specific enough to check
Safety rules the team agrees on (secrets, prod data, force push)
Architecture facts that are easy to get wrong

Docs recommend keeping CLAUDE.md concise (a common target is under about 200 lines per file). Longer files eat the window and get followed less reliably. Multi-step procedures and rare workflows often belong in skills (Part 4) rather than in the always-on brief. Short true beats long aspirational. “Run npm test before you claim done” is better than a page of manifesto about quality culture.

Auto memory: product feature, verify in your setup

Auto memory is Anthropic’s mechanism for letting Claude accumulate learnings across sessions without you hand-writing every correction into CLAUDE.md. Claude may save notes about build commands, debugging patterns, architecture insights, and preferences it discovered while working. Official docs describe it as on by default in typical setups, toggleable via /memory and settings such as autoMemoryEnabled, with storage under a project-scoped directory on the machine (documented layout under ~/.claude/projects/<project>/memory/ with a MEMORY.md index).

Important practical facts for how you should talk about it at work:

It is a real product feature with documented enable/disable paths, storage locations, and load limits (docs describe loading the first 200 lines or 25KB of MEMORY.md, whichever comes first).
Users should verify settings. Do not assume every teammate has the same toggle state, the same Claude Code version, or the same memory directory. Run /memory and /context when something “should have been remembered.”
It is not a substitute for git. Auto memory is machine-local in the documented model. It is not shared across machines the way a committed CLAUDE.md is. A coworker cloning the repo does not automatically inherit your local MEMORY.md.
You can audit it. Memory files are plain markdown you can open, edit, or delete. If Claude learned a bad fact (“always skip tests on this package”), fix or delete that entry.

When should you put something in CLAUDE.md instead of hoping auto memory catches it? When the whole team needs the same rule, when the rule is safety-critical, when you want it in code review, or when you are tired of correcting the same mistake twice. Auto memory is great for “Claude keeps forgetting my preferred package manager.” CLAUDE.md is better for “we never commit secrets, and here is the command that runs the suite.”

What sticks vs what resets (cheat sheet)

Use this table when someone asks “why doesn’t it remember?”

Thing	Survives new session / `/clear`?	Where it lives	Who owns it
Chat transcript and mid-task plan	No (cleared or summarized)	Session context	You, while the thread lives
CLAUDE.md project brief	Yes (reloaded each session)	Repo or user config paths	Team (if committed) or you
Auto memory notes	Can, if enabled and stored	Local project memory dir	Claude writes; you audit
Skills you invoke	Bodies load on use; not “chat memory”	Skill files on disk	You or the team
File edits on disk	Yes	Working tree	You via review + git
Committed code and tests	Yes	Git remote + history	The team
Uncommitted experiment	Yes on disk, no as chat	Working tree only	You until committed

After compaction (not the same as a full clear), project-root CLAUDE.md and auto memory can be re-injected from disk according to docs, while path-scoped rules and nested CLAUDE.md files may need a matching file read again. Conversation-only instructions that never hit a file are the ones that feel “lost.” That is a feature if you promote important chat corrections into CLAUDE.md or tests.

The context window: why long sessions get noisy

The context window is the finite working set Claude can see for this session. Before you type anything, a lot already loads: system prompt material, environment info, skill descriptions, MCP tool names (often deferred in detail), CLAUDE.md content, and a slice of auto memory when present. Your first prompt is often tiny next to that stack. Then every file read, tool result, hook note, and reply adds more.

Official context-window material stresses a few operational truths:

File reads dominate growth. Vague prompts that force wide exploration cost more than “fix the null check in src/auth/session.ts.”
Follow-ups stay in the same window. The wrong approach from hour one is still sitting there at hour three.
Subagents can keep large research out of your main window; only the summary returns.
/compact replaces conversation history with a structured summary so work can continue. Startup instructions reload; the full verbatim middle of the chat does not.
/clear is the clean break when the next task is unrelated. Old chat crowds out the files you need next and costs tokens on every message.

Context smell checklist: vague exploration, repeated failed approaches, mixed tasks in one session, and a full window…

Context smell test

Your session is getting noisy when any of these show up:

Claude keeps proposing a design you already rejected thirty minutes ago
You are on a new ticket but the agent still talks about the old one
/context shows heavy usage and quality is sliding (more generic answers, more re-reads)
You are pasting “ignore previous instructions about X” instead of clearing
Half the transcript is debugging a wrong path you already abandoned

When that happens, choose deliberately: compact with a focus note if you need continuity, clear if you are changing jobs, or open a fresh session with a tighter CLAUDE.md so the standing rules stay and the mud does not.

Git and files are the source of truth

Here is the sentence worth taping above the monitor: if the only place a decision lives is in chat, you do not have a decision yet.

Claude Code is excellent at changing a tree of files. Those files are what CI runs, what code review sees, and what production ships. The agent’s confidence in a summary is not a substitute for:

A failing test that now passes for the right reason
A committed CLAUDE.md that new sessions load
A PR description that states what changed and what you checked
Config that the app actually reads at runtime

Beginners sometimes treat a good chat answer as “done.” Intermediate users ship the files and still forget to promote the standing rule that prevented the bug. Advanced teams treat the loop as: correct in chat once, encode in tests or CLAUDE.md, let the next session start smarter without replaying the novel.

A Monday morning workflow that respects the layers

Open the repo. Confirm branch. Skim CLAUDE.md if you have not in a while.
Start a session for one job, not three tickets mashed together.
Ask Claude to explore with a narrow question before large edits.
When you correct the same fact twice, add it to CLAUDE.md or a test.
Review the diff as if a human coworker wrote it (Part 9 of this series).
If the next task is unrelated, /clear or new session. Do not hoard transcripts for luck.
Commit what should survive. Leave chat behind without grief.

Worked example: the billing correction that should not die at lunch

Imagine you are on a small Node service. Session one:

You: The invoice total is wrong for multi-seat plans.
Claude: (reads files, proposes a fix in calculateTotal)
You: Stop. calculateTotal is legacy. New pricing goes through PricingEngine.
You: Also run pnpm test:billing, not npm test.
Claude: (adjusts plan, edits PricingEngine, tests pass)

If you stop there, session two after lunch may still open calculateTotal first, because that was the obvious name and nothing durable said otherwise. Three durable moves:

CLAUDE.md: “Billing math lives in src/billing/PricingEngine.ts. Do not extend calculateTotal.”
Script truth: document pnpm test:billing in CLAUDE.md next to other commands.
Test: a regression test for multi-seat totals so the next agent fails fast if it reopens the wrong path.

Optional fourth move: if auto memory is enabled and Claude saved “use pnpm for this repo,” great. Still put the architectural rule in CLAUDE.md so the team shares it. Auto memory on your laptop is not a substitute for onboarding the next hire.

Here is a minimal project CLAUDE.md fragment you might commit after that session:

# Project brief
Node billing service. APIs under src/api. Domain logic under src/billing.

# Commands
- Install: pnpm install
- Unit tests: pnpm test
- Billing suite: pnpm test:billing
- Lint: pnpm lint

# Architecture
- Pricing and invoice totals: src/billing/PricingEngine.ts
- Do not add logic to legacy calculateTotal helpers

# Safety
- Never commit .env or real customer dumps
- Do not run migrate against production URLs

That is short, true, and checkable. Part 6 expands the skeleton and the difference between CLAUDE.md, AGENTS.md, and README.

Commands that help you see what the session knows

You do not have to guess. Claude Code documents inspection commands that belong in your muscle memory:

Command	Use it when
`/context`	You want a live breakdown of what is in the window, including memory files loaded
`/memory`	You want to open, edit, or toggle memory-related files and auto memory
`/compact`	The thread is long but still the same job; optionally add focus text
`/clear`	You are switching to unrelated work and want a clean conversational slate
`/init`	You need a starting CLAUDE.md draft from the codebase (then edit hard)

If CLAUDE.md “is not working,” first confirm it loaded under memory files in /context. If it loaded and Claude still ignores a vague line, make the line concrete. If two files conflict, resolve the conflict instead of adding a third contradictory note.

Common mistakes

Treating chat as the design system of record. After reset, the design is gone. Promote decisions.
Never clearing because “context is free.” Context is finite. Noise is expensive in quality, not only in tokens.
Assuming auto memory means teammates share your sticky notes. Verify. Commit shared rules.
Writing a 900-line CLAUDE.md of aspirations. Short true instructions win. Move procedures to skills.
Expecting CLAUDE.md to hard-block tools. Use permissions and hooks when “must not” is literal.
Mixing three tickets in one session. You get a stew of half-relevant file reads.
Skipping review because “the agent remembers our standards.” Diffs land on disk. You own the merge.

How to practice this week

In an existing project, run a short session and deliberately correct one preference twice (for example the test command).
Run /memory and /context. Note what loaded. Toggle or inspect auto memory if your build supports it. Verify, do not assume.
Add three true lines to CLAUDE.md that would have prevented the double correction.
/clear or start a new session. Ask the agent the same task shape. Check whether it follows the written rule.
Commit the CLAUDE.md change if the team should share it. Leave personal paths in a local file if your workflow uses one.

Next up is Part 6: markdown and project instruction files in detail (CLAUDE.md, AGENTS.md, README, and friends), including a sample skeleton you can paste and thin down. If you still need install and first-run orientation, jump back to the start of this series from Learn.

Quick recap

Session chat resets with /clear or a new session; it is working memory, not the archive.
CLAUDE.md loads each session; put project brief, commands, style, and safety there as short true rules.
Auto memory can save learnings across sessions as a product feature; verify settings and audit the files.
Context fills with file reads and history; long sessions get noisy; compact or clear on purpose.
Git and project files are the source of truth. Promote durable facts out of chat.

Sources

Research and further reading used for this article:

Claude Code docs: How Claude remembers your project (CLAUDE.md scopes, auto memory, /memory, load behavior)
Claude Code docs: Explore the context window (what loads at startup, compaction survival, /clear and /compact guidance)
Claude Code docs: How Claude Code works (context window mechanics and related product behavior)
Claude Code docs: Best practices (managing context as a primary constraint)
Claude Code docs: Skills (on-demand workflows versus always-on CLAUDE.md)
Claude Code docs: Subagents (separate context windows for research)
Claude Code docs: Overview (product entry and doc index)
Analytics Made Simple: Learn (series map on this site)