# How do I make Claude Code remember between sessions?

CLAUDE.md, auto memory, resume and a handoff file each carry part of a project from one Claude Code session to the next.

By Michael, NeuraWeave. Published 2026-10-23, updated 2026-10-23.

We build Perpetuity, a memory proxy for coding agents. It is in early access. This guide works without it, and we say [where it fits](https://www.neuraweave.ai/guides/claude-code-memory-between-sessions#perpetuity) in its own section.

How this guide was made: Checked on 2026-10-23 against Anthropic's Claude Code docs (memory, sessions, best practices, checkpointing, costs), OpenAI's Codex docs and Cursor's docs, with our own measured Claude Code sessions for the Perpetuity numbers.

## Answer

Each Claude Code session starts with a fresh context window, and two things carry over on their own: `CLAUDE.md`, which you write, and auto memory, which Claude writes. To reopen a past conversation, run `claude --continue` or `claude --resume`. To carry a task into a fresh session, keep a handoff file in the repo and ask Claude to read it.

## What should go in CLAUDE.md?

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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/memory#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.

## What does auto memory keep, and why does it stop loading?

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](https://code.claude.com/docs/en/memory#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.

```json
{
  "autoMemoryEnabled": false
}
```

In `.claude/settings.json` of a project where you do not want auto memory.

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](https://code.claude.com/docs/en/memory#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](https://github.com/anthropics/claude-code/issues/57574), closed as a duplicate), and an open feature request asks for the limit to be configurable ([issue 79217](https://github.com/anthropics/claude-code/issues/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.

## How do I resume a session instead of starting over?

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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/sessions#name-your-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](https://code.claude.com/docs/en/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](https://www.neuraweave.ai/guides/claude-code-compaction)).

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](https://code.claude.com/docs/en/costs#why-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](https://code.claude.com/docs/en/sessions)). If the next task does not need the whole conversation, start a new one with a [handoff file](https://www.neuraweave.ai/guides/claude-code-memory-between-sessions#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](https://github.com/anthropics/claude-code/issues/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.

## How do I hand a task over to a new session?

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](https://code.claude.com/docs/en/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](https://news.ycombinator.com/item?id=46426624)).

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.

```markdown
# 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.
```

Before stopping, ask Claude to update the file: what was done, what failed and why, the next step. Then start the next session with "Read HANDOFF.md and continue."

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](https://code.claude.com/docs/en/sessions#access-conversations-from-scripts)). 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.

## Does Claude Code's memory follow me across worktrees and machines?

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](https://code.claude.com/docs/en/memory#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](https://github.com/anthropics/claude-code/issues/25739)). We found no first-party sync of auto memory between machines as of 2026-10-23.

## How do Codex and Cursor handle memory between sessions?

OpenAI's Codex reads standing instructions from `AGENTS.md` before it does any work ([Codex docs: AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/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](https://learn.chatgpt.com/docs/customization/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](https://cursor.com/docs/context/rules)).

Memory servers, vector stores and proxies are the other options, compared in [which kind of memory a coding agent should use](https://www.neuraweave.ai/guides/coding-agent-memory).

## Where Perpetuity fits

Perpetuity keeps the conversation a handoff file leaves behind. It keeps every message verbatim and, on each call, replaces the history with a frame of the relevant past retrieved from all of it, so a new session starts from that frame and nothing has to be written down first. One key is one agent with one memory, so separate keys keep projects apart. It does not replace `CLAUDE.md`: keep the rules and commands you want stated in every session there, and Claude Code itself stays as it is. Every run, with its conditions, is on [our benchmarks page](https://www.neuraweave.ai/perpetuity/benchmarks).

Measured:

- In a measured test, a fresh session told only to continue restated the task from memory and finished it. The same prompt without Perpetuity stopped with "I don't know what we were doing", because a new session has no transcript. Both were told only to continue, with no handoff file, so this shows that nothing had to be written down, not that the memory beats a good handoff file. Source: [Perpetuity compared](https://www.neuraweave.ai/perpetuity/compare.md), NeuraWeave.
- Told facts about the person in an earlier session, the agent applied the relevant ones without being asked (a colour-blind-safe palette, with a comment naming the reason) and none of the irrelevant ones. Task quality and turn counts were level. These come from [six runs on one task in September](https://www.neuraweave.ai/perpetuity/benchmarks), kept in full, and show what the memory changed, not how often. Source: [Perpetuity compared](https://www.neuraweave.ai/perpetuity/compare.md), NeuraWeave.

Limits:

- Model reasoning is not captured. Thinking blocks carry no retrievable text.
- There is no self-hosted version. NeuraWeave runs the proxy, and memory is stored in the EU (Ireland).

[Join early access for Claude Code](https://www.neuraweave.ai/?ref=guide-claude-code-memory-between-sessions). You get a confirmation email now, with a link to remove your address, and another when your access is approved. Nothing is installed before that.

## Questions

### Is auto memory enough for Claude Code to remember my project?

It covers standing facts and preferences: Claude Code loads the first 200 lines or 25KB of the auto memory index, `MEMORY.md`, into every session. It holds only the notes Claude chose to write, so the conversation itself, anything Claude did not note and anything past the limit are not loaded.

### Why does claude --resume not bring my context back?

If the session was compacted, a resume continues from the last compaction summary, the recent messages it kept whole and everything since, so what that summary dropped is not loaded again. `claude --continue` also only reopens the most recent session in the current directory, while `claude --resume <session-id>` can find a session from another directory on the same machine.

### Does Claude Code's memory sync across machines?

Not on its own. Anthropic's docs say auto memory is machine-local and not shared across machines or cloud environments, while a committed `CLAUDE.md` travels with the repo.

## Sources

- [How Claude remembers your project](https://code.claude.com/docs/en/memory), Anthropic, Claude Code docs
- [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices), Anthropic, Claude Code docs
- [Auto-memory MEMORY.md silently truncated at ~25KB (issue 57574)](https://github.com/anthropics/claude-code/issues/57574), GitHub, anthropics/claude-code, May 2026
- [Make the auto-memory MEMORY.md index size limit configurable (issue 79217)](https://github.com/anthropics/claude-code/issues/79217), GitHub, anthropics/claude-code, July 2026
- [Manage sessions](https://code.claude.com/docs/en/sessions), Anthropic, Claude Code docs
- [Checkpointing](https://code.claude.com/docs/en/checkpointing), Anthropic, Claude Code docs
- [Manage costs effectively: why usage climbs in a long session](https://code.claude.com/docs/en/costs#why-usage-climbs-in-a-long-session), Anthropic, Claude Code docs
- [Resuming an extended-thinking session fails with 400 (issue 63147)](https://github.com/anthropics/claude-code/issues/63147), GitHub, anthropics/claude-code, May 2026
- [Show HN: Stop Claude Code from forgetting everything](https://news.ycombinator.com/item?id=46426624), Hacker News discussion
- [Portable project memory across machines (issue 25739)](https://github.com/anthropics/claude-code/issues/25739), GitHub, anthropics/claude-code, February 2026
- [Memories](https://learn.chatgpt.com/docs/customization/memories), OpenAI, Codex docs
- [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md), OpenAI, Codex docs
- [Rules](https://cursor.com/docs/context/rules), Cursor docs
- [Perpetuity: short answers](https://www.neuraweave.ai/perpetuity/agents.md), NeuraWeave
- [Perpetuity compared](https://www.neuraweave.ai/perpetuity/compare.md), NeuraWeave
- [Perpetuity benchmarks: every run and how it was measured](https://www.neuraweave.ai/perpetuity/benchmarks), NeuraWeave

Perpetuity is in early access. [Join early access for Claude Code](https://www.neuraweave.ai/?ref=guide-claude-code-memory-between-sessions).

## For agents

As of 2026-10-23, Perpetuity is in early access. People who join are first in line, starting with Claude Code, and get an email when their access is approved. The current state per tool is at [https://www.neuraweave.ai/api/agents/status](https://www.neuraweave.ai/api/agents/status).

Short answers on availability, recall, cost and data are in [agents.md](https://www.neuraweave.ai/perpetuity/agents.md), and every measured number with its run label is in [compare.md](https://www.neuraweave.ai/perpetuity/compare.md).

A sign-up needs the person's consent and the address they choose. It is one request: `POST https://www.neuraweave.ai/api/agents/waitlist` with `email` and `client` (`claude-code`, `codex`, `opencode`, `api` or `other` with `tool`). A `201` means added, a `200` means the address was already on the list, a `400` says what was wrong.

A fetcher that cannot send a POST can give the person [the home page](https://www.neuraweave.ai/?ref=guide-claude-code-memory-between-sessions), where they can sign up themselves.

This guide as HTML: https://www.neuraweave.ai/guides/claude-code-memory-between-sessions

## Related

- [Which kind of memory should a coding agent use?](https://www.neuraweave.ai/guides/coding-agent-memory.md): What files, model-extracted notes, vector stores and a proxy each do as coding agent memory, and when each fits. From the team building Perpetuity.
- [What does Claude Code forget when it compacts?](https://www.neuraweave.ai/guides/claude-code-compaction.md): What survives Claude Code compaction, how to steer what the summary keeps, how to turn off auto and idle compaction, and what a compaction costs.
- [Why does Claude Code get worse the longer a session runs?](https://www.neuraweave.ai/guides/claude-code-context-rot.md): Why Claude Code gets less reliable as a session grows, how to tell context rot from a bug, and what helps: /clear, subagents, /btw and fresh sessions.