How to give Claude Code memory between sessions

Why Claude Code forgets

Claude works inside a context window: your conversation, the files it read, command output, and its instructions. Each new session starts with a fresh context window, without the conversation history from earlier sessions. Source

Long sessions forget too. As the context fills up, Claude Code compacts the conversation into a summary on its own. The summary keeps your requests and key code, but detailed instructions from early in the conversation may be lost. Source

So anything you want Claude to know next time has to be written down somewhere it reads at the start.

What Claude Code has built in

• CLAUDE.mdMarkdown files of instructions you write. Claude reads them at the start of every session. Use them for build commands, conventions, project layout and rules. Source
• Where they liveJust you, every project: ~/.claude/CLAUDE.md
  The project, shared with your team in git: ./CLAUDE.md or ./.claude/CLAUDE.md
  Just you, this project: ./CLAUDE.local.md (add it to .gitignore)
  Organizations can also install a managed CLAUDE.md for every user on a computer. Source
• ImportsA CLAUDE.md can pull in other files with @path/to/file, for example @README. Imports help you organize, but the imported text still takes up context. Source
• Auto memoryNotes Claude writes for itself from your corrections and preferences, on by default in local sessions. They are stored per repository in ~/.claude/projects/<project>/memory/, with a MEMORY.md index. The first 200 lines or 25KB of that index load in every session. Auto memory stays on that one computer. Source
• /memoryRun it in a session to list your CLAUDE.md and memory files, open one in your editor, turn auto memory on or off, and open the auto memory folder. Ask Claude to "remember" something and it saves it to auto memory; ask it to add something to CLAUDE.md and it goes there. Source
• CompactionYour project root CLAUDE.md survives compaction: Claude Code reads it again from disk afterwards. Instructions you only typed into the chat may not. You can steer a summary with /compact and a focus, like /compact focus on the API changes. Source Source
• --continue and --resumeclaude --continue (or -c) reopens the most recent conversation in the current folder. claude --resume (or -r) opens a session by ID or name, or shows a picker. Name a session with claude -n "my-feature-work" to find it later. Source

Start there. Run /init to have Claude write a first CLAUDE.md for your project, keep it short, and add to it whenever you catch yourself explaining the same thing twice. Source

Where the built-ins fall short

• Decisions and whyCLAUDE.md is for rules you want followed every time. A running log of what was decided, when, and why, does not fit well in a file that loads in full each session.
• To-dos across sessionsResuming brings back one conversation. A list of open work that any session can pick up and close needs a place of its own.
• Other appsCLAUDE.md and auto memory are read by Claude Code. If you also use Cursor, ChatGPT, Claude Desktop or Grok, each of them starts from nothing.
• Several agentsWhen more than one agent or computer works on a project, auto memory stays on the computer that wrote it, and nothing records which agent did what.

Add an MCP memory server

MCP (Model Context Protocol) lets Claude Code connect to outside tools. Source A memory server is one of those tools: Claude calls it to save a note, a decision or a to-do, and to read back what is already there. The notes live in the server's own store, so they outlast any session, and every app connected to the same server sees the same ones.

FlowState is one such server. It is free and open source, and keeps your project memory in one file on your computer. When an AI starts on a project it gets a short brief of where things stand, and as it works it logs decisions, changes, problems and to-dos, each marked with the AI that wrote it.

The easy way to set it up: paste this into Claude Code and let it follow FlowState's own instructions.

Set up FlowState for me from https://github.com/dialectforge/FlowState by following its AGENTS.md.

By hand, in a terminal (quit Claude Code first; on Windows type python for python3). The first setup line only shows what would change; the second makes the change and checks that FlowState answers.

git clone https://github.com/dialectforge/FlowState.git FlowState
cd FlowState
python3 setup_flowstate.py --clients claude-code --schedule-backups --no-offsite --install-skill --dry-run
python3 setup_flowstate.py --clients claude-code --schedule-backups --no-offsite --install-skill --verify

Or add it to Claude Code yourself with your own paths. --scope user makes it available in all your projects:

claude mcp add --transport stdio --scope user flowstate -e FLOWSTATE_DB=/path/to/flowstate.db -e PYTHONPATH=/path/to/FlowState/mcp-server -- /path/to/FlowState/.venv/bin/python -m flowstate
claude mcp list

Not sure about the paths or the format? The MCP config builder writes this command for you, and the same entry for Claude Desktop, Cursor and VS Code. Full steps are in the setup guide and FlowState's AGENTS.md.

FlowState is not the only option. Other open-source MCP memory servers exist, with different storage and features, and the same claude mcp add command works for any of them. Pick the one that fits how you work.

Local or remote

Claude Code on your computer can start FlowState locally, as above. That is free, and your data stays in one file on your computer.

Apps that cannot start programs on your computer, like ChatGPT and claude.ai in the browser, need a server they can reach by URL. FlowState Relay (in beta) gives your own computer a private address without setting up a tunnel, and your data stays on your computer. Hosted (in beta) keeps your memory on our server instead, for people who would rather not run it at home. Claude Code on another computer can then connect with:

claude mcp add --transport http flowstate https://<handle>.fsmcp.com/mcp --header "Authorization: Bearer $FLOWSTATE_TOKEN"

Keep the key in an environment variable, not in a file you share. Both plans are optional; see pricing.

Questions

• Does Claude Code remember previous sessions?Not the conversation itself. Each new session starts with a fresh context window. What carries over is what is written down: your CLAUDE.md files and the auto memory notes Claude saves for itself. You can also reopen an earlier conversation with claude --continue or claude --resume.
• Where are Claude Code memory files stored?Your personal CLAUDE.md is ~/.claude/CLAUDE.md. A project CLAUDE.md is ./CLAUDE.md or ./.claude/CLAUDE.md, and personal notes for one project go in ./CLAUDE.local.md. Auto memory lives in ~/.claude/projects/<project>/memory/, with a MEMORY.md index. Run /memory in a session to see and open them.
• Why does Claude Code forget things in a long session?When the context window fills up, Claude Code compacts the conversation into a summary. Detailed instructions from early in the conversation can be lost. Anthropic suggests putting rules that must last in CLAUDE.md instead of the chat.
• What is an MCP memory server?A small program that Claude Code connects to over the Model Context Protocol. It gives Claude tools to save and look up notes, such as decisions and to-dos, in a store that lives outside any one session or app.
• Can Cursor or ChatGPT read Claude Code's memory?CLAUDE.md and auto memory are files for Claude Code. Other apps do not load them on their own. An MCP memory server connected to each app gives them the same notes. ChatGPT and claude.ai in the browser can only reach a remote server by URL.
• Is FlowState free?Yes. FlowState is free and open source (MIT) and runs on your computer. Relay and Hosted are optional paid plans for reaching it from apps that need a URL, like claude.ai and ChatGPT.