How do I make Claude Code remember between sessions?

Put in CLAUDE.md what you would otherwise re-explain at the start of every session: build and test commands, conventions that differ from the defaults, the project layout and rules like "run npm test before committing". Claude Code reads it at the start of every session (Claude Code docs: memory).

1. Run /init in the project. Claude reads the codebase and writes a starting CLAUDE.md with the commands and conventions it finds. If the file exists, /init suggests improvements and does not overwrite it.
2. Keep each file under 200 lines. Anthropic's docs say longer files use more context and are followed less reliably. Move rules that only matter for part of the codebase into .claude/rules/ with a paths list, so they load only when Claude works on matching files.
3. Put personal, project-specific notes in CLAUDE.local.md and add it to .gitignore. Put preferences for every project in ~/.claude/CLAUDE.md.
4. Run /context in a new session and check the list under Memory files to confirm the file loaded.

Claude reads these files as context, and the docs say they are not enforced configuration. For a rule that must hold every time, write a hook (Claude Code docs: memory): a PreToolUse hook can block an action whatever Claude decides.

If the repository already has an AGENTS.md for other coding agents, Claude Code v2.1.277 and later reads it directly when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. With both present, Claude reads only CLAUDE.md by default, so put @AGENTS.md on the first line of CLAUDE.md to share one file (Claude Code docs: AGENTS.md).

The project-root CLAUDE.md also survives compaction: after /compact, Claude Code reads it again from disk. An instruction you gave only in chat survives only as far as the compaction summary keeps it, so anything you have said twice belongs in the file.

Auto memory is a folder of notes Claude writes for itself, and Claude Code loads the first 200 lines or the first 25KB of its index, MEMORY.md, whichever comes first, at the start of every session (Claude Code docs: auto memory). The notes are about you, your corrections, ongoing work and where to find things outside the repo. Claude skips what it can work out from the code and what CLAUDE.md already says.

• It lives in ~/.claude/projects/<project>/memory/: MEMORY.md as the index, one line per memory, and one topic file per memory, which Claude opens only when it needs it.
• It is on by default in local sessions. Ask Claude to "remember" something and it goes here. Ask it to "add this to CLAUDE.md" to put it in CLAUDE.md instead.
• Run /memory to browse and edit the files, open the folder, or switch auto memory off. To switch it off for one project, set autoMemoryEnabled to false in that project's settings. The variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 switches it off too.

{
  "autoMemoryEnabled": false
}

Everything past the 200-line or 25KB mark is not loaded at the next session start. Claude Code reminds Claude to shorten the index as it nears the limit. If a write takes the file over the limit, the write still succeeds and Claude Code returns an error telling Claude to rewrite the index (Claude Code docs: auto memory). On long-running projects several people have still reported the limit as a problem. One report from May 2026 described the newest rules at the end of a chronological index as the ones cut (issue 57574, closed as a duplicate), and an open feature request asks for the limit to be configurable (issue 79217).

1. Open /memory every few weeks and read the index. When Claude writes a memory file with frontmatter, Claude Code stamps a modified time in it, which makes stale notes easier to spot.
2. Keep one short line per entry in MEMORY.md and move detail into topic files, which do not count against the limit.
3. Delete notes that are wrong or finished. Memory files are kept out of Claude Code's 30-day transcript cleanup, so they stay until you or Claude remove them.
4. Move standing rules from auto memory into CLAUDE.md, which loads in full.

Run claude --continue to reopen the most recent session in the current directory, or claude --resume to pick one from a list. Claude Code saves every session as it goes, as a JSONL file under ~/.claude/projects/<project>/, and keeps it for 30 days by default (Claude Code docs: sessions).

1. Name a session while you work with /rename oauth-migration, or start it with claude -n oauth-migration. Then claude --resume oauth-migration reopens it directly (sessions).
2. Before /clear, name the session you are leaving. /clear keeps the old session on disk, and /clear release-prep names it as you leave. In the same Claude Code process, /rewind also lists the previous session at the top (checkpointing).
3. claude --continue only looks in the current directory. From anywhere else, run claude --resume <session-id>, or press Ctrl+A in the picker to list sessions from every project on the machine. /cd moves a session to another directory's storage.

A resumed session is the conversation as it was saved, compaction included. If the session was compacted, it continues from the last summary, the recent messages that compaction kept whole and everything since, and the messages that summary replaced are not loaded again (what Claude Code forgets when it compacts).

Resuming a long conversation also resends everything it loads. Claude Code sends the full conversation with every request, which Anthropic's docs give as one reason usage climbs in a long session. On Pro and Max plans, resuming a long conversation after a long break or on a different model can show a "Resume this conversation?" dialog with an estimate of the share of your 5-hour limit the saved conversation alone would use (sessions). If the next task does not need the whole conversation, start a new one with a handoff file.

Some resumes fail outright. An open issue, opened on v2.1.153, reports that resuming a session that used extended thinking can fail on every prompt with a 400 error about thinking blocks (issue 63147, open as of 2026-10-23). Comments in it report the same error without a resume as well, on versions from v2.1.141 to v2.1.170. Check your version with claude --version and read the issue first, and copy the session's .jsonl file before trying any workaround. Its format is internal and changes between versions, so /export is the safer way to keep a readable copy.

Keep the plan and its progress in a file in the repo, and start the next session by asking Claude to read it. Anthropic's best practices describe the same move for larger features: have Claude write a spec to a file, then start a fresh session to carry it out (best practices). In a Hacker News thread about a memory tool, several commenters said plain markdown files in the repo, such as plans and work logs, already cover this for them (discussion).

Git history shows what changed. The handoff file is for what git leaves out: why a decision went the way it did, what was tried and failed, and what comes next. Listing the files that matter also lets the next session open those first instead of exploring the codebase again.

# Handoff: OAuth migration

Goal: replace session cookies with OAuth in src/auth/.
Done: callback handler and tests (all passing).
Tried and dropped: refreshing tokens in middleware, it raced with logout.
Next: move the token store to Redis, then remove src/auth/legacy.ts.
Files that matter: src/auth/callback.ts, src/auth/store.ts, tests/auth.test.ts
Open question: keep the old cookie for one release or not.

To write a handoff from a session you already closed, without loading it into the new one, ask it from the command line: claude -p --resume <session-id> "Summarize what we did, what failed and why, and the next step", and save the answer to HANDOFF.md (sessions). That one request reads the old conversation, and the new session starts from the file.

To have it load without asking, import it from CLAUDE.md with @HANDOFF.md. An imported file loads with CLAUDE.md in every session, so keep it short and clear it out when the task is done.

A handoff file holds what you or Claude chose to write down. The conversation itself, the tool output and the details nobody thought to note stay behind in the old session.

It follows you across worktrees but not across machines. Auto memory is kept per git repository, so every worktree and subdirectory of one repo shares it, and the docs say it is machine-local, with files not shared across machines or cloud environments (Claude Code docs: auto memory). Session transcripts are local to the machine as well.

• A committed CLAUDE.md travels with the repo to every clone and machine.
• A gitignored CLAUDE.local.md exists only in the worktree where you made it. To share personal notes across worktrees, import a file from your home folder, for example @~/.claude/my-project-instructions.md.
• The autoMemoryDirectory setting moves auto memory to another absolute path. On an open request for portable project memory, one commenter describes pointing it at a folder inside the project that they sync themselves (issue 25739). We found no first-party sync of auto memory between machines as of 2026-10-23.

OpenAI's Codex reads standing instructions from AGENTS.md before it does any work (Codex docs: AGENTS.md) and has Memories, which turn useful context from earlier chats into local files under ~/.codex/memories/. Memories are off by default: turn them on in the app's personalization settings or with memories = true under [features] in config.toml. OpenAI's docs treat the files as generated state and say rules that must always apply belong in AGENTS.md or checked-in docs (Codex docs: memories).

Cursor carries context between chats with rules: project rules in .cursor/rules as version-controlled .mdc files, user rules for every project, team rules on Team and Enterprise plans, and AGENTS.md. A rule set to always apply is included in every chat. The others load when a file matches their pattern, when the agent judges their description relevant, or when you @-mention them (Cursor docs: rules).

Memory servers, vector stores and proxies are the other options, compared in which kind of memory a coding agent should use.