How Claude Code Remembers Your Project (and What Breaks When You Move Folders)

You've probably noticed Claude Code picks up context between sessions — things you've told it about your project, preferences, even past decisions. That memory doesn't live in your project folder. It lives elsewhere, keyed to the exact path of your project. Move the folder, and Claude forgets everything.

The jargon

Absolute path — the full address of a folder from the root of your drive, e.g. C:\Users\Brian\Projects\acme. Not relative. Not ../acme. The whole thing.

Project state — Claude Code's stored memory for a specific project: conversation history, custom instructions, and tool preferences it has learned.

The lesson

Claude Code identifies projects by their absolute path on disk. When you start a session in a folder, it hashes or directly uses that path as a key to look up stored state. The state itself lives in ~/.claude/projects/ on Mac/Linux — on Windows that's C:\Users\<you>\.claude\projects\. Each project gets a subfolder named after a sanitised version of its path.

There's also a .claude.json file that can sit inside your project folder. This holds project-level instructions you've explicitly saved — things like "always use British English" or "this project uses Python 3.11". This file does travel with the project because it's inside it.

The mismatch is the problem. .claude.json moves when you rename or reorganise. The state in ~/.claude/projects/ does not — it stays behind, tied to the old path. Claude Code won't error. It will simply create a fresh state entry for the new path and act as if it has never seen this project before.

How it works

Open PowerShell and look at what's stored:

Get-ChildItem "$env:USERPROFILE\.claude\projects\" | Select-Object Name

You'll see folders whose names are mangled versions of your project paths. If you've moved C:\Projects\acme to C:\Clients\acme, you'll see an entry for the old path sitting unused, and a new empty one for the new path once you start a session there.

If you want to carry state across a move, you can rename the state folder manually to match the new path. It's fiddly and undocumented, so test it on something low-stakes first.

When to reach for it / when not to

Check ~/.claude/projects/ when Claude suddenly seems to have forgotten everything about a project you've been working on for weeks. The answer is almost always a path change — a Dropbox reorganisation, a drive letter shift, moving from one machine's sync to another.

Don't rely on ~/.claude/projects/ for anything critical. It's a cache, not a source of truth. Important project instructions belong in .claude.json, which travels with your project and is safe to commit to git.

Try it

Pick an active project and run the command above. Find its state folder. Note the exact name Claude Code has given it. Then open .claude.json inside the project itself and see what's there (it may be empty or absent if you've never saved explicit instructions). Knowing where both live means you'll recognise immediately what's happened the next time Claude seems to have lost its memory.