Claude Code keeps forgetting context? What to save where

Claude Code spends an hour tracing an authentication bug. It finds that the token refresh path must stay separate because mobile clients retry differently. It changes two files, runs the focused tests, and leaves one failing integration test for tomorrow.

The next session opens the same repository and sees the code. It doesn't know which paths were ruled out, why the split is intentional, or which test is still failing. You explain the work again.

That feels like one memory failure. It's usually four:

• the previous conversation wasn't resumed
• stable project instructions existed only in chat
• unfinished work had no handoff
• the reason behind a team decision had no current shared record

Saving more transcript fixes none of them well. Claude Code gives you six different continuity mechanisms; the trick is matching each kind of context to the right one. (For why agents forget in general, and how the same layers apply to every tool, start with the AI coding agent memory guide.)

Every Claude Code memory option, side by side

Option	Best for	Shared with teammates?	Main risk
Resume the session	Continuing the same conversation	No	Local, and tied to one client's session history
CLAUDE.md and .claude/rules/	Stable project instructions	Yes, through Git	Gets large or stale if used as a journal
Auto memory	Your recurring learnings	No	Machine-local and not authoritative
Task handoff file	Unfinished branch state	Yes, if committed	Must be closed when the task ends
Plugin	Reusable skills, agents, hooks, MCP setup	Through distribution	Packages behavior, not current truth
MCP server	Live data and shared services	Yes, by server policy	Only as good as the source's status fields

Most teams need several of these at once.

How do I pick up exactly where I left off?

Claude Code stores CLI sessions locally as you work. claude --continue resumes the most recent interactive session in the current directory; claude --resume opens a picker. A resumed session restores conversation history, tool calls, and results, which no summary file can match for speed.

Name sessions you expect to come back to:

/rename auth-refresh-debug

claude --resume auth-refresh-debug

Know the limits. The CLI, desktop app, web app, and VS Code extension keep different session histories. Sessions are local and can get very large. A session resumed after a long gap may be offered as a compacted summary. And launch flags aren't always restored: if a session depended on --plugin-dir, you'll need to pass it again, or install the plugin properly. If a teammate or another environment needs the context, it has to live somewhere else.

Source: Claude Code session management

Why did Claude forget something mid-session?

Usually compaction. Claude Code compacts automatically as the context window fills, and anything left out of the summary is no longer in context. You can steer it:

/compact focus on the auth refresh bug, attempted fixes, current failing test,
and constraints we must preserve

Compaction treats sources differently. Project-root CLAUDE.md, auto memory, and several startup mechanisms reload afterwards. Instructions you only gave in conversation, and some path-scoped context, may be summarized away until a matching file is read again. That's the practical argument for moving anything you repeat into a file.

Use /context to see what's occupying the window and /memory to check which memory files are loaded.

Source: Claude Code context window

What belongs in CLAUDE.md?

Anything you'd otherwise repeat in every session: build and test commands, repository layout, conventions, hard boundaries, and short pointers to deeper records.

## Billing service

- Run focused tests with `pnpm test billing`.
- Do not make the event queue the only confirmation path.
- Accepted architecture decisions are indexed in `docs/adr/README.md`.

Claude Code reads project CLAUDE.md at session start, but as instructions, not enforced configuration. The documentation recommends keeping it under about 200 lines, because longer files use more context and reduce adherence. Put path-specific guidance in .claude/rules/, and use @path imports to share a common file such as AGENTS.md across tools.

Don't turn CLAUDE.md into a transcript archive or a running task log. It should say how to work and where to look. The full boundary is in CLAUDE.md vs agent memory.

Source: Claude Code memory and CLAUDE.md

What does auto memory remember, and what doesn't it?

Auto memory is on by default. Claude saves project-specific learnings as plain Markdown on your machine: a test quirk, a debugging path, a preference that should come back next time.

The boundary is in the same sentence: it's machine-local. It isn't shared across machines or cloud environments, and independent subagents don't automatically inherit the main conversation's memory. Everything is inspectable through /memory, so review it and delete notes that have gone wrong rather than assuming they stay correct.

Use it to make your own sessions faster. Don't let it be the only copy of an architecture choice, a policy, or an owner.

How should I hand off unfinished work?

A handoff answers four questions: what's done, what's open, what the next session should do first, and which constraints it must preserve.

# Auth refresh handoff

Done:
- traced refresh failures to mobile retry timing
- changed `token-store.ts` and `refresh.ts`
- unit tests pass

Next:
- fix `auth.integration.test.ts` case 14
- rerun the mobile retry fixture

Do not change:
- separate mobile refresh path; see ADR 0021

Branch: `fix/mobile-refresh`
Last good command: `pnpm test auth --filter refresh`

Commit it with the branch when someone else, another machine, or another tool may continue. Delete it when the task ends, or a future session will treat old next steps as current. Anthropic's guidance for long-running agents recommends the same thing: durable progress artifacts and clean state, so a fresh context window can orient itself.

Is a memory plugin the answer?

Claude Code plugins bundle skills, agents, hooks, MCP server configuration, and other reusable pieces, versioned and installable across projects and teammates. A plugin could package:

• a /handoff skill that writes your team's standard task summary
• a hook that reminds the agent to run tests before a PR
• a review agent with restricted tools
• an MCP connection to an internal system

That's distribution, not memory. A plugin can define how to fetch or record context, but its files shouldn't hard-code fast-changing team state. Put the behavior in the plugin and the current data in the system it reads. Before installing anything sold as memory, ask where the data lives, who can change it, and how stale entries are retired.

Source: Create Claude Code plugins

When should Claude fetch context over MCP instead?

When the context is shared across people or repositories, changes outside the codebase, or is too large for startup instructions. Instead of pasting a ticket, deploy status, or document into every session, Claude queries it when needed.

MCP is a connection, not a guarantee of meaning. A generic memory server can return several similar notes; a docs server can find a proposal and its replacement. Review the permissions and retention of each server, and prefer sources that return scope and status, not just similar text.

Source: Connect Claude Code to tools via MCP

Where should architecture decisions live?

Not in a memory note. A memory can say, "We considered using the queue for confirmation." A decision record says whether the team accepted or rejected it, why, who owns the choice, and what replaced it. Without those fields, retrieval makes context loss worse: Claude finds an old proposal and a new choice and treats both as equal evidence.

Give each decision:

• the choice and its scope
• rationale and constraints
• rejected options
• owner and date
• status: proposed, accepted, deprecated, superseded
• a link to any replacement

For a single repository, an ADR can carry this. For choices that span product, engineering, several repositories, and several agents, use a shared system every tool can query. Why Claude Code forgets architecture decisions goes deeper on this layer.

A quick rule: sort by how fast it changes

• Same conversation: resume the session.
• Slow and universal: CLAUDE.md or a scoped rule.
• Slow and personal: auto memory.
• Temporary and task-specific: handoff file.
• Repeatable behavior: plugin.
• Current external state: MCP.
• A choice the team made: decision record.

In a repository, that tends to look like:

repo/
  CLAUDE.md                  # stable instructions + pointers
  .claude/rules/             # path-scoped rules
  docs/adr/                  # repository decisions
  .handoffs/current.md       # temporary task state

plugin/
  skills/handoff/SKILL.md    # how to write the handoff
  hooks/                     # repeatable checks
  .mcp.json                  # shared service connections

Before you close a meaningful session

1. Name the session if you may resume it.
2. Move repeated instructions into CLAUDE.md or a scoped rule.
3. Update the branch handoff with done, next, risks, and commands.
4. Record any accepted architecture or product decision in the team's decision log.
5. Commit the handoff and decision pointer with the code.

Then prove it. Open a fresh session, ideally on another machine or client, and ask: what is this branch trying to finish, which test is failing, why must the mobile refresh path stay separate, and which decision governs that? Then change the decision and ask again. If the answers require reopening the old transcript, the durable context is incomplete.

Where Lockstep fits

Lockstep covers the one layer above that shouldn't depend on a single session or a single machine: accepted team decisions. Owners approve decisions captured from Slack, docs, tickets, and PRs; Claude Code reads the relevant ones through the get_product_context MCP tool before it writes code, and a PR check flags changes that may conflict (warnings by default, blocking only if you opt in). Resume, CLAUDE.md, auto memory, handoffs, and plugins keep doing their jobs alongside it.

For moving work between tools, see how to share memory between Cursor and Claude Code. For the wider landscape, compare the best tools for AI coding agent context and decision log tools for product and engineering.