Claude Code memory resets every session. Each new session starts blank, so you explain your stack again and repeat yesterday's corrections. The fix is a set of files Claude reads at startup, kept in a private git repo so they survive a dead laptop.
TLDR
Claude has no memory between sessions. It has files, and it reads them in a fixed order at startup.
Five kinds of files carry everything: rules, identity, skills, tools and state.
Give each rule one source file and let a script write every copy.
Keep the master copy of every file in a private GitHub repo, and leave secrets out.
Test the restore before the laptop dies. My last new PC took 45 minutes.
A Dead Laptop Erases a Setup That Lives on One Disk
The same laptop dies in two setups. In the first, every rule and skill lived on that one disk. In the second, they lived in a private git repo.
Without the repo. Claude forgets your stack, and you rebuild each skill from memory.
Without the key list. Nobody wrote down which secrets each tool needs.
With the repo. You clone it, refill the keys and ask Claude for your top three rules.
The result. My last new PC went from a blank disk to a working Claude in 45 minutes.
Ten Terms Form One Connected System Around the Harness
A harness is everything you build around the model. It is Claude plus the files it reads when a session starts. Write those files once and Claude starts every session already knowing you.
Each term keeps one meaning from here on.
CLAUDE.md is a plain text file of rules that Claude Code reads at the start of every session.
Load order is the sequence in which Claude reads its files at startup.
Skill is a folder with a SKILL.md prompt that loads when a request matches its trigger.
MCP (Model Context Protocol) is the standard way to plug a tool or data source into Claude.
Hook is a script Claude Code runs on its own at a set event, such as after each file write.
State file is a file the agent edits to track progress, such as sent, pending and failed rows.
Routine is a workflow that runs on a schedule.
Second brain is your personal notes vault, which Claude can read as context.
Git repo is a folder whose full version history git tracks, and GitHub can store it online.
Most people run Claude with no harness at all. So a job that a harness finishes in 2 prompts takes them 20, because nothing corrects a lazy prompt before Claude acts.
Five Kinds of Files Give Claude a Memory
Claude has no memory between sessions. It has files, and five kinds of file carry everything it needs.
Rules. CLAUDE.md files hold how Claude behaves: format, tools, banned habits, your stack.
Identity. Identity files hold who you are, how you write and who you write for.
Skills. Each skill holds one repeatable job, with its prompt, its checks and its examples.
Tools. MCP config and a
.envfile, a private list of your API keys, connect Claude to services.State. State files record where the work stands, so the next session picks up there.
You write the first four, and the agent writes the fifth. Reference files sit beside them, holding examples a skill copies, and they never change during a session.
Watch out. Never hand-edit a state file. The agent trusts it to match what actually happened.
Claude Reads Files in a Fixed Load Order
Claude Code reads its files in the same sequence every time. Five layers load before you type a word.
Layer 1 is the system prompt, which Anthropic writes.
Layer 2 is the global
~/.claude/CLAUDE.md, with rules for every project.Layer 3 is the project CLAUDE.md in the folder you opened.
Layer 4 is skills, which load when a request matches their trigger.
Layer 5 is MCP tools and the environment.
When a session produces strange output, check which files loaded before you fix the prompt. If the wrong files loaded, throw the output away and start a new session.
Step 1. Give Each Rule One Source File and Generate Every Copy
Claude sees every layer at once. When two files disagree, no layer wins every time, so the output changes from run to run.
The obvious fix is to paste an important rule into every file that needs it. That fails within weeks.
You change the rule in one copy and forget the second.
Claude then obeys whichever copy it read last.
You cannot tell which copy that was.
So give each rule one source file, and let a script build every copy.
Keep one folder of rule files, one file per rule.
Let a short script write them into your global CLAUDE.md.
Rerun the script after every rule change.
Add a check that compares each copy with its source and fails when they drift.
Put a rule for one repo in that repo's CLAUDE.md, and never repeat a global rule there.
Rules written for an older model also go stale. My Rule Rewriter skill audits CLAUDE.md and skill files for those rules, then proposes a rewrite for each one.
It sits in the Skill Pack as Rule Rewriter, and nothing changes until you approve it.
Step 2. Route Claude to Every Project With One Registry Table
My global CLAUDE.md carries a table called the project registry. Each row maps the words I say to a local folder and its GitHub repo. So I say "my website" in any session, and Claude works in the right folder.
Four rules sit under the table, and each one stops a specific mistake.
When two rows match the same words, such as "the docs", Claude asks which one I mean.
Claude checks the current git branch before it edits, because some repos sit on long feature branches.
When Claude writes to another repo, it names the path in its reply.
A commit or a push still needs my yes.
To link a new project, add one row with three columns: the names you call it, its local folder and its GitHub repo.
Step 3. Commit the Harness to a Private Git Repo
Your harness lives in a few folders on one machine. A dead laptop, a lapsed subscription or a switch to a work account each wipe it.
The tools you use also keep copies on their own terms. Each of these is rented storage, and the owner can change the rules without asking you.
A routine saved inside a Claude account stays with that account.
A scheduling tool may keep an uploaded image for a few days, then delete it.
A chat history lasts until the app changes its plan.
So keep the master copy in a place you own, and give every tool a copy from it. Commit a file before you hand it to any tool, and a deleted upload costs you only a re-upload.
The backup takes four moves.
Create a private GitHub repo.
Copy your global CLAUDE.md, your settings and your skills folder into it.
Add a
.gitignorefile, which tells git which files to never save, and list.envand your login token file.Commit a
.env.examplefile that lists each key name with an empty value.
Rule of thumb. Commit after every change to a skill or a rule. A backup from last month restores last month's Claude.
Step 4. Test the Restore Before the Laptop Dies
A backup proves nothing until you restore from it. Most people find the gap on the day the laptop dies: a skill that never got committed, or a key whose name nobody wrote down.
Test the restore on a spare machine or a new user account while the old setup still works.
Install Claude Code and Git, then sign in.
Clone the repo back into your skills folder.
Copy the config files back into place.
Refill each key from the example file.
Reinstall the tools your skills call.
Ask Claude for your top three rules. A wrong answer means a file did not load.
I wrote a restore script for the copy and reinstall steps once, and it has paid for itself every time since. My last new PC took 45 minutes from a blank disk to a working Claude, apps included. My full checklist sits in the new PC migration guide.
Step 5. Keep Each Skill in Exactly One Folder
A skill is a folder, and each skill lives in exactly one of two places.
Global skills sit in
~/.claude/skillsand load in every project.Project skills sit in a repo's
.claude/skillsand load only inside that repo.SKILL.md holds the prompt, the trigger and the output format.
An optional scripts folder holds Python checks and scorers.
An optional references folder holds the examples the skill copies the style of.
Yarchi shares Addy Osmani's repo, where each skill states when to use it and the steps to follow.
Never copy a skill into both folders. Two copies drift apart, and then you fix a bug in the copy Claude never loads. When a skill goes missing from one folder, look in the other.
Read the git diff before every skill commit. Claude edits skills fast, and a one-line change to a trigger can stop a skill loading.
A good skill also interviews you. My Slack DM skill asks for the message, the channel and a confirmation, in that order. It cannot reach step 2 without step 1, so a vague request never sends a message.
Step 6. Save Every File Inside the Agreed Folders
Every check you build looks in known places. So a file saved anywhere else passes every check, because no check ever opens it.
A backup copies named folders.
A scorer scans the drafts folder.
A hook fires on files under one path.
A failed check shows up red. A stray file shows up as nothing, and nothing looks like a clean result. Claude makes stray files often, such as a draft on the desktop, and that file also misses the backup.
Agree on the folders once and write them into your CLAUDE.md. Tell Claude to save each kind of file only in its folder, and run a short check that lists any file outside them.
Advanced Users Keep Secrets, Routines and Brains Separate in Git
The steps above protect the average setup. Five more habits protect a setup that runs a business.
Redact before you commit. My backup script copies my Claude config into the repo and replaces every bearer token with a <REDACTED> marker.
It searches the copies for strings shaped like a live token.
On a match it stops and stages nothing.
On a clean run it stages the files, and I read the diff and commit.
Store routines as files. A routine registered only inside a Claude account vanishes when you switch accounts. So I keep each routine as a file in git, with its state beside it, and a new account re-registers every routine from those files.
Cloud connectors in Claude's Connections tab belong to the account. Local MCP servers belong to the machine config. Back up each one where it lives.
Keep two brains in two repos. My second brain holds my personal notes, my personal keys and my voice. A company brain holds the company's skills, a README written for agents, and the company voice. Never mix the two.
To give Claude your second brain in any session, mount the vault as an extra directory with the alias in the appendix.
Obsidian CEO Steph Ango raised this counterpoint about sending a vault to a model provider.
Block bad output with hooks. A rule in CLAUDE.md asks Claude to behave, and a hook enforces it. Mine runs a scoring script after every file write and blocks the save on a critical finding. In one session, 21 LinkedIn comments failed that scorer and never posted.
Tip. Grade with a fresh subagent. An agent will not reject its own earlier answer.
The same idea works as a self-evaluation loop, a cycle that grades output and regenerates it.
Define good and bad output.
Generate, then score.
Regenerate until it passes or hits 3 to 5 tries.
Use API keys in order. I keep several numbered keys per provider for tools such as Firecrawl. Key 1 runs until it is empty, then key 2. Round robin empties every key at the same rate and leaves no reserve.
The vault structure behind my second brain sits in my Obsidian setup.
Step 7. Spend the Last Five Minutes Writing Tomorrow's Memory
End each session by asking Claude to write its decisions and changes into your vault. Then commit. The next session reads those files at startup and starts where this one stopped.
That habit is the gap between my first month with Claude and now. The model did not get better at remembering me. I wrote down what it should know, and git kept every version.
If you want this capture to run on its own, Claude Mem records what happened in a coding session for the next one. It sits in the AI and agent section of my tool directory.
Five Questions Newcomers Ask About Claude Code Memory
Does Claude Code remember anything without these files? It remembers nothing between sessions. Everything it knows at the start comes from the files in the load order.
Should my API keys go in the git repo? Keep keys out of git. List .env in .gitignore, and commit a .env.example that names each key with an empty value.
What goes in the global CLAUDE.md versus a project CLAUDE.md? The global file holds rules for every project. A project file holds rules for that one repo and never repeats a global rule.
How often should I commit the backup? Commit after every change to a skill or a rule. An old backup restores an old Claude.
How do I know the restore worked? Ask Claude for your top three rules. A wrong answer means a file did not load.
Appendix Holds the Commands for the Backup and Restore
Mount your second brain in every session:
alias claude='claude --add-dir ~/path/to/your/vault'Keep secrets out of the backup repo with a .gitignore:
.env
.credentials.jsonRestore on a new machine:
git clone https://github.com/<you>/<your-private-repo>.git ~/claude-backup
cp ~/claude-backup/CLAUDE.md ~/.claude/CLAUDE.md
cp -r ~/claude-backup/skills ~/.claude/skills
cp ~/claude-backup/.env.example ~/.env # then fill in each keyRelated reading: Skills 2.0 and Building An AI Marketing Team with Claude Skills
