Memory and Sessions: Continuity Across Days
Auto-memory, session resume, and building an agent that remembers your project's history.
The LLM (large language model) behind Claude Code remembers nothing between calls. Every sense of "memory" is built from files on disk, and it helps to know exactly which files, because each one behaves differently.
Claude Code keeps continuity across days with three things. Session transcripts record what happened in each conversation, so you can resume one. CLAUDE.md files, which you write, hold what Claude should know in every session. And auto memory holds short notes Claude writes for itself as it works. None of them is a hidden search index: when you resume a conversation, Claude Code reloads it, and when you start a new one, only your instruction files and the start of Claude's memory index come along.
Where does Claude Code store your conversations?
Every exchange is saved as you work to a transcript file at ~/.claude/projects/<project>/<session-id>.jsonl, in your home folder rather than in the repository. The format is JSONL (JSON Lines): each line is one JSON object for a message, a tool use or a metadata entry, so the file holds every prompt you typed, every tool call the agent made, and every response. Anthropic's session documentation notes that the line format is internal and changes between versions, so read sessions through /export or claude -p --resume rather than parsing the files yourself.
Transcripts do not last forever. Claude Code deletes them after 30 days by default, silently, in a background sweep. The cleanupPeriodDays setting changes that, and claude purge deletes a project's transcripts and related state right away. (You may also see a ~/.claude/sessions/ folder. It only holds small files that track which sessions are running, so Claude Code can detect crashes; your conversations are not there.)
A typical session for our web app might record a schema change, a debugging session, and the decision to keep SQLite for development. These transcripts are episodic memory: a raw, time-ordered log of what actually happened. They are the record you go back to, not something Claude searches on its own.
How does resuming a session actually work?
Resuming brings back one conversation, whole. There is no retrieval step and no search across your other sessions. According to the docs, a resumed session restores "the full history, including tool calls and results," along with state saved in it such as the model it was using.
You have a few ways in:
claude --continue(or-c) reopens the most recent session in the current folder.claude --resumeopens a picker of past sessions;claude --resume <name>jumps straight to one./resumeswitches to a different session from inside a running one.
Names make this easy. Start a session with claude -n auth-refactor, or run /rename auth-refactor during it, and tomorrow claude --resume auth-refactor takes you back. If you want to try a different approach without losing the current one, /branch copies the conversation so far into a new session and switches you into it; from the shell, add --fork-session to --continue or --resume.
In our running example, after a weekend away you run claude --continue in the web app folder. Friday's whole conversation comes back, including the debugging of a CSRF token mismatch, so you can ask "What was that edge case we found in the login flow?" and Claude can see the answer in its own history.
How does long-term memory get built across sessions?
Two systems carry knowledge from one session to the next, and Anthropic's memory documentation draws the line simply: CLAUDE.md files are written by you; auto memory is written by Claude. Both load at the start of every conversation, and Claude treats both as context, not enforced configuration.
CLAUDE.md files are the instruction files from Part 2: project conventions, build commands, architecture notes. They change only when you edit them, or when you explicitly ask Claude to, for example "add this to CLAUDE.md." Claude never quietly rewrites them on its own.
Auto memory is Claude's own notebook. In the docs' words, "Auto memory lets Claude accumulate knowledge across sessions without you writing anything." As it works, Claude saves four kinds of notes: who you are and how you like to work, corrections you have given it, project context it cannot work out from the code (such as a deadline or a decision), and pointers to outside resources like an issue tracker. It skips anything it can derive from the codebase and anything your CLAUDE.md files already say, and it does not save something every session.
These notes live in ~/.claude/projects/<project>/memory/: a MEMORY.md index with one line per memory, plus one topic file per memory. At the start of every conversation, Claude Code loads the first 200 lines or 25 KB of MEMORY.md, whichever comes first. The topic files are not loaded up front; Claude reads one when it needs it. When you see "Saved 2 memories" or "Recalled 2 memories" in the interface, that is Claude writing or reading this folder.
A few properties matter in practice. Auto memory is per repository: all worktrees and subfolders of the same git repository share one memory folder. It is machine-local, so it does not follow you to another computer or into cloud sessions. And it is exempt from the 30-day transcript cleanup; its files stay until you or Claude edit or delete them.
You stay in control. To ask for something to be remembered, just say it in a session: "remember that the API tests need a local Redis instance." To see what has been saved, run /memory, which lists your memory files and opens the auto memory folder; everything there is plain Markdown you can read, edit or delete. The same /memory screen has a toggle to turn auto memory off; you can also set autoMemoryEnabled to false in a project's settings, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
What happens under the hood when you start a new day?
When you open your laptop and run claude in your web app repository, you get a fresh conversation. Claude Code loads your CLAUDE.md files (from your home folder, the project, and the folders above it, as Part 2 described) and the first part of MEMORY.md. Yesterday's conversation is not part of it. Those files are the always-available backbone; everything else Claude learns by reading your code again.
If you want yesterday's thread instead, you resume it with claude --continue or claude --resume, and the whole conversation comes back. Because Claude Code runs on your machine, all of this is read directly from local files.
After each response, the turn is appended to the current transcript. If Claude learned something worth keeping, such as a correction you gave it, it may also add or update a memory file, and you will see it say so.
Why don't older sessions blow up the token budget?
Because nothing loads an old session unless you resume it. A new session starts with only your instruction files and the start of the memory index, no matter how many sessions your project has had.
A resumed session is different: it brings its full history back, and a long conversation can fill the context window. Compaction keeps that in budget. When the context nears its limit, Claude Code summarizes older messages automatically, keeping key decisions while dropping transient detail, and it re-reads your project-root CLAUDE.md afterwards. You can also run /compact, optionally with a focus such as /compact keep the auth decisions, to do it on demand. If you would rather start clean, /clear begins a new, empty conversation and keeps the old one saved for /resume. And /context shows what is using the context right now. The chart sums up what the session documentation and the memory documentation say enters the context in each case.
- Your CLAUDE.md files
- First 200 lines or 25 KB of MEMORY.md
- No earlier conversation
- The full earlier conversation, tool calls included
- Compaction summarizes it when the context fills
- /clear starts over; the old session stays saved
The result is that your project can have a hundred sessions and a new one still starts small. What carries forward is what you or Claude deliberately wrote down.
Quick Reference
| Property | Value |
|---|---|
| Session transcripts | ~/.claude/projects/<project>/<session-id>.jsonl |
| Transcript retention | 30 days by default (cleanupPeriodDays) |
| Continue the latest session here | claude --continue (or -c) |
| Pick or name a session to resume | claude --resume, claude --resume <name>, /resume |
| Name a session | claude -n <name>, or /rename <name> |
| Branch a conversation | /branch, or --fork-session with --continue or --resume |
| Instructions you write | CLAUDE.md files (Part 2) |
| Auto memory Claude writes | ~/.claude/projects/<project>/memory/ (MEMORY.md plus topic files) |
| Loaded at session start | CLAUDE.md files, first 200 lines or 25 KB of MEMORY.md |
| View, edit or toggle memory | /memory |
| Turn auto memory off | "autoMemoryEnabled": false, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 |
| Manage context | /compact, /clear, /context |
| Delete a project's transcripts | claude purge [path] |
Frequently Asked Questions
Q: Can Claude Code use memories from a different project?
Auto memory, no: each repository has its own memory folder, shared only by that repository's worktrees and subfolders. Your own instruction files are a different story. ~/.claude/CLAUDE.md and the rules in ~/.claude/rules/ apply to every project on your machine, so anything you put there follows you everywhere.
Q: How can I make Claude Code forget something it automatically remembered?
Run /memory and open the auto memory folder. Find the topic file that holds the note, then edit or delete it, and remove its line from MEMORY.md. If the same fact is in a CLAUDE.md file, edit that too and commit the change. Claude reads the current state of these files in every new session.
Q: Does resuming a session pull in memories from that session or just the transcript? Resuming reloads that conversation's full history, tool calls included. Nothing is searched or retrieved from other sessions. Your CLAUDE.md files and auto memory are separate files on disk, and they keep applying as usual.
Q: Can I prevent a particular session from being used later?
Old sessions are never pulled into new ones; a session's content comes back only if you resume it. Transcripts age out after 30 days by default, and claude purge deletes a project's transcripts sooner. Anything Claude saved to auto memory from that session stays until you remove it.
Q: How does Claude Code avoid showing me stale memories that are no longer correct?
It does not invalidate them automatically. Claude Code records when each memory file was last written, which helps you and Claude judge how current a note is, but a wrong fact stays until someone changes it. Correct Claude when it repeats something outdated (corrections are one of the things it saves), and edit or delete the stale file through /memory.
Test yourself
Our web app switched its test runner from Jest to Vitest last month, but Claude Code keeps suggesting Jest configuration, apparently from something it remembered weeks ago. How do you make sure it stops?
Answer: First find where the old fact lives. Open /memory and check two places: your CLAUDE.md files, and the auto memory folder, where MEMORY.md lists the topic files. Delete or rewrite the topic file that mentions Jest, and remove its line from MEMORY.md. Then put the current fact where it belongs: add "Tests use Vitest; run npm test" to the project's CLAUDE.md, because that is a convention you want in every session and every teammate's session. Since auto memory skips what CLAUDE.md already says, the two will not fight. If the old advice came from a long conversation you keep resuming, the outdated discussion is still in that history, so start a fresh session (or /clear) once the files are fixed. From then on, every new session loads only the corrected files.
Next: Headless Claude Code: CI, Scripts, and Automation. It shows how to run Claude Code without a person at the keyboard, in scripts and pipelines.
If you want this kind of breakdown every week, how real systems actually work under the hood, subscribe to Internals Decoded at internalsdecoded.com.
Sources
- How Claude remembers your project
- Manage sessions
- Explore the .claude directory
- All settings
- CLI reference
