Claude Code Sessions and Memory: Resume Work Safely

Direct answer

A Claude Code session is a saved conversation tied to a project directory. Claude Code sessions are the separate saved workstreams you can resume, rename, branch, rewind, or export. Memory works differently. The CLAUDE.md file holds instructions written by people, while auto memory holds notes Claude writes for future sessions. Treat one session as one active workstream. Keep durable rules in the project instruction file, audit auto memory, and verify the current branch, files, and diff whenever you resume.

Summary

Continue: `claude --continue` reopens the most recent session for the current directory.
Resume: `claude --resume` opens the picker; a name or session ID can select a specific conversation.
Branch: `/branch` copies the current history into a new session ID and preserves the original.
Clear: `/clear` starts a fresh context while keeping the previous conversation available to resume.
Compact: `/compact` replaces older history with a summary inside the current session.
Project instructions: people write and maintain them, then Claude loads the files that are in scope.
Claude-written notes: plain Markdown preserves selected repository learnings for future conversations on that machine.
Safety: transcripts, tool output, and memory can contain sensitive or stale information, so inspect and govern them.

Four layers that are often called memory

Most confusion comes from using one word for four different systems. Session history, active context, project instructions, and auto memory have different owners, scopes, storage, and failure modes. Treat them separately before deciding what to preserve.

Session transcript: the saved messages, tool uses, and results for one conversation. Resume appends to that conversation.
Context window: the material the model can use for its next response. It includes history, loaded files, tools, instructions, and memory.
Human instructions: project, user, local, directory, or organization files load when their scope applies.
Persistent learned notes: Claude stores them for the repository and recalls them in later sessions. People can inspect, edit, or delete them.

Resuming a transcript does not restore an old filesystem, branch, terminal environment, external service, permission decision, or running process. It restores conversation history. Claude reads the files and state that exist when the session continues. Before editing, reconcile the discussion with the current repository.

Read Anthropic's explanation of sessions, context, local transcripts, resume, and forks.

Current session commands

`claude --continue`: resume the most recent session for the current directory.
`claude --resume`: open the interactive session picker.
Named resume: `claude --resume <name>` selects an exact session or searches when the name is ambiguous.
ID-based resume: `claude --resume <session-id>` selects a specific conversation, including supported non-interactive sessions.
`claude --from-pr <number>`: resume the session linked to a pull request when that link exists.
`/resume`: switch conversations from inside an active CLI session.
`/rename <name>`: give the current workstream a descriptive, findable name.
`/branch [name]`: copy the history into a new session ID and leave the original unchanged.
`/clear`: start a fresh context while leaving the old conversation saved.
`/compact [focus]`: summarize history, optionally preserving a named focus.
`/context`: inspect what currently consumes context.
`/export [filename]`: render the current conversation as readable text.

The current CLI picker starts with interactive sessions from the worktree. `Ctrl+W` widens the view to repository worktrees, while `Ctrl+A` widens it to projects on the machine. Search, preview, branch grouping, session names, time, message count, and Git branch help distinguish similar workstreams.

Use the official Manage sessions page for current picker, naming, resume, and branch behavior.

Continue, resume, compact, branch, or start fresh?

Continue in the same session when the task, branch, assumptions, and evidence still match the current work.
Resume a named session when returning to the same workstream after closing the terminal or changing sittings.
Compact when the task remains coherent but tool output and exploration consume too much context.
Branch the session when two approaches need the same starting analysis but should keep independent conversation histories.
Start a new session when the task changes, prior assumptions create noise, or the next job deserves clean context.
Choose a Git worktree when parallel sessions must edit different branches without sharing one working directory.
Create a written handoff when another person or tool needs verified state without inheriting the entire conversation.

A session branch is not a Git branch. `/branch` forks conversation history. A Git worktree or branch isolates code. Use both when you need an alternative reasoning path and a separate checkout. If the same session opens in two terminals without a fork, Anthropic warns that messages can interleave in one transcript.

Resume checklist

Confirm the project path, worktree, Git branch, and session name before sending a new instruction.
Inspect the working tree, recent commits, open pull request, and current ticket rather than trusting an old summary.
Review the last accepted plan, unresolved questions, pending tests, and files the session expected to change.
Recheck volatile facts, dependency versions, API behavior, prices, credentials, and external issue state.
Ask for a concise state summary that separates verified facts, assumptions, completed work, and next actions.
Correct stale context before authorizing edits or commands. Record durable corrections in the proper source of truth.

Manage context inside a long session

A saved session can contain far more history than the model should use at once. The context window includes prompts, replies, file contents, command output, project instructions, auto memory, tools, skills, and system instructions. Claude Code clears older tool output and compacts history as the window fills.

Run `/context` before guessing which content consumes the window.
Use `/compact focus on the current plan, changed files, verification, and remaining risks` when those details matter.
Start a new session for a new task instead of carrying unrelated research and tool output forward.
Move durable rules out of conversation history and into a maintained project instruction file or scoped rule.
Keep large generated logs and files out of the main conversation when a concise finding is enough.
After compaction, verify nested instructions again when the relevant subdirectory or path-scoped rule becomes active.

Project-root instructions and auto memory are re-injected after compaction. Nested instruction files and path-scoped rules reload when matching files are read. A detail mentioned only in the conversation can be summarized away. Keep repeatable rules in a durable file and current task status in a verified handoff or issue.

Explore Anthropic's current context-window and compaction behavior.

How Claude Code memory works

The product currently has two complementary persistent-memory mechanisms. People write project instructions. Claude writes auto memory based on useful corrections, preferences, build commands, debugging discoveries, and patterns. Both provide context, not guaranteed enforcement.

Human-instruction owner: a person or organization maintains explicit commands, conventions, and architecture constraints.
Human-instruction scope: organization, user, project, local, directory, imported file, or path-scoped rule, depending on placement and configuration.
Learned-note owner: Claude decides what to note, while a person can inspect, edit, delete, enable, or disable it.
Repository scope: learned notes are shared across its worktrees and subdirectories on the same machine.
Default storage: `~/.claude/projects/<project>/memory/`, with `MEMORY.md` as the concise index.
Startup load: the first 200 lines or 25KB of `MEMORY.md`, whichever comes first; topic files load on demand.
Inspection: `/memory` opens memory locations and settings, while `/context` confirms what loaded into the current session.

What belongs in each place

Put a repeatedly needed build command, code convention, approval rule, or unusual project constraint in the maintained project instructions.
Put path-specific guidance in scoped rules or a nested instruction file that loads with the relevant files.
Let auto memory capture discovered debugging patterns and repeated preferences that may help later.
Put ticket status, acceptance criteria, owner, due date, and release evidence in the team's tracking system.
Put source code, configuration, migrations, tests, and documentation in the repository as their own source of truth.
Keep secrets out of prompts, transcripts, memory, issue comments, and instruction files. Use approved secret storage instead.

Review the official project-instruction hierarchy, auto-memory limits, audit controls, and troubleshooting steps.

Govern memory and transcripts

Claude Code stores local CLI transcripts as plaintext JSONL under `~/.claude/projects/`. Tool results can include file content, pasted text, command output, and credentials exposed by a command. Anthropic documents a 30-day default cleanup for session data, controlled by `cleanupPeriodDays`. Auto memory is separate and persists until edited or deleted.

Decide which repositories may use auto memory and who is responsible for reviewing it.
Open `/memory` regularly. Remove stale facts, duplicates, sensitive content, and conclusions that lack evidence.
Keep project instructions concise and specific. Resolve conflicts across user, project, local, nested, and imported files.
Use permissions to prevent reads of credential files and avoid commands that print secrets into transcripts.
Set a retention period that matches team policy. Understand what resume, rewind, and audit capability will be lost.
Use `claude project purge <path> --dry-run` to preview project-state deletion before considering the confirmed purge.
Document the approved source of truth for architecture, status, access, and operational rules outside model-written memory.

Read Anthropic's application-data paths, plaintext warning, retention, and project-purge guidance.

Create a reliable session handoff

A good handoff is a short verified state record, not a transcript dump. It should let the next session validate the workspace before continuing. Store it where the team already tracks the work, and link evidence rather than copying sensitive output.

Goal and acceptance criteria.
Project path, worktree, branch, ticket, and pull request.
Completed changes with file or commit evidence.
Verification commands and exact results.
Open risks, assumptions, failed approaches, and unresolved decisions.
External facts that need a fresh check.
Safe next action and actions that still require human approval.

Example goal: fix the checkout retry bug. The reproduction is confirmed on branch `fix/retry`, but no code is committed. Evidence is the failing `checkout-retry.spec.ts` test. The payment sandbox may have changed. Next, verify the API response, implement the smallest fix, and run the focused test and typecheck. Do not deploy without approval.

Troubleshooting Claude Code sessions and memory

Wrong conversation resumed: verify path, worktree, branch, name, and ID; use the picker preview before selecting.
Session missing from the picker: widen to worktrees or projects, or resume a supported non-interactive session by ID.
Instructions ignored: run `/context`, check the loaded memory files, make rules specific, and remove conflicts.
Incorrect learned note: inspect `/memory`, edit or delete the Markdown, then correct the durable source of truth.
Context feels noisy: run `/context`, compact with a focus, or start a new session with a verified handoff.
Compaction lost a nested rule: read a matching file so the path-scoped or nested instruction loads again.
Code and conversation disagree: trust the inspected repository state, tests, issue, and current external evidence.
Sensitive value entered the transcript: rotate it when needed, remove the exposure from governed systems, and review local retention.

Frequently asked questions

A new session starts with fresh conversation context. You can resume a saved session to continue its transcript. Project instructions and auto memory carry selected guidance or learned notes into new sessions, but they do not reproduce every prior conversation.

`claude --continue` reopens the most recent session in the current directory. The resume command opens a picker, while a name or session ID targets a specific session. Give each workstream a descriptive name when several share a repository.

No. The official sessions guide says the previous conversation remains saved and resumable. `/clear` starts fresh context. Local cleanup, manual deletion, a project purge, or skipped session persistence can change what remains available later.

The default auto-memory directory is machine-local. It is shared across worktrees and subdirectories of the same Git repository on that machine, but not across machines or cloud environments. Check current enterprise and SDK options before designing shared storage.

Use Better Design's project-instructions guide to write concise rules.

Preserve the right state

Resume a session when the workstream is still valid. Start fresh when it is not. Keep explicit rules in maintained project instructions, allow auto memory only with review, and store project truth in the systems that own it. The reliable workflow is not perfect recall. It is a short path from saved context to verified current state.

Connect Better Design