CLAUDE.md and MEMORY.md: The Two Files That Stop You From Repeating Yourself
I spent about three weeks re-explaining the same things to Claude at the start of every chat before it occurred to me there might be a better way. My tone preferences, my build commands, the fact that I use Proton instead of Gmail – all of it, retyped, every session, because a new chat starts from absolute zero and has no idea who you are. Turns out there’s a fix, and it’s about as low-tech as it gets: two markdown files.
CLAUDE.md and MEMORY.md. Once they’re sitting in your project folder, Claude reads both automatically before your first message even lands. No plugin, no toggle buried in settings. Here’s what they actually do, and what I got wrong setting mine up.
CLAUDE.md is the rulebook
You write this one yourself. It’s a list of instructions Claude follows every session — this is a real feature of Claude Code (Anthropic’s terminal tool), and it works the same way in Cowork. Drop a CLAUDE.md at the root of a project folder and Claude loads it before touching anything else. Anthropic’s documentation describes it as “a behavioral contract,” which sounds like something a lawyer wrote, but it’s not wrong — Claude treats the file as ground truth for the whole session.
The part I underestimated at first: vague instructions barely work. “Format code properly” doesn’t tell Claude anything it can check itself against. “Use 2-space indentation” does. The same thing applies outside of code – “keep it concise” is a suggestion; “under 300 words unless I ask for more” is a rule.
This is a trimmed-down piece of my own file, built off Jeff Su’s Cowork Toolkit:
## Preferences
– Write in a professional but conversational tone. If it sounds like a corporate memo, rewrite it.
– Keep responses concise, under 300 words unless I ask for more detail.
– Give me one strong recommendation. Don’t give me 3 options unless I specifically ask for alternatives.
## Rules
– Always ask clarifying questions before starting a complex task.
– If you’re not sure about something, say so. Don’t guess.
– Before drafting a new email, check if a related thread already exists with that recipient.
Doesn’t look like much. Saves me from typing the same three corrections every single time, though, and that adds up faster than you’d think.
MEMORY.md is the logbook
If CLAUDE.md is the rules, MEMORY.md is the running list of facts — what I’m working on right now, decisions I’ve made, anything I’ve told Claude to hang on to. One line in my CLAUDE.md ties the two together: “When I say ‘remember this,’ write the information to MEMORY.md immediately.” That’s the entire mechanism. Nothing automatic about it. Claude doesn’t guess what’s worth saving; I tell it, and it writes it down.
A piece of mine, mildly embarrassing typos and all:
## Active Projects
– Creating and running a Claude website — Create a website about
how to use Claude and post multiple times a week
## Core Memory
– Signed up for Jeff’s Cowork Toolkit and finished D1 setup
(root CLAUDE.md and MEMORY.md).
– I use Google Workspace and Proton for email and calendar.
That first bullet is the reason this post exists, actually. I told Claude to remember the website project weeks ago and mostly forgot about it, and when I finally asked for a draft, it already knew what the site was, who it’s for, and roughly what I’d been building toward. Didn’t have to explain any of it twice.
The part that confused me for a bit
Claude Code has its own native “auto memory” feature, separate from any of this, and the naming collision had me going in circles for a while. Auto memory is Claude writing its own MEMORY.md based on what it notices during a session — no “remember this” required, no input from you at all. It lives in a hidden project folder, caps out around 200 lines or 25KB, and Claude decides on its own what’s worth keeping.
What I’ve described above is the manual version of that same idea. You write the file. You decide what goes in. Nothing gets saved unless you say so, out loud, in those words. I’d rather have that than the automatic version, honestly — I want to know exactly what Claude thinks it knows about me, not trust that it guessed right. If you’re using Claude Code and a MEMORY.md shows up somewhere you didn’t put one, that’s probably why.
Setting it up
Takes about ten minutes.
- Create a CLAUDE.md at the root of your project or workspace folder.
- Add a “Preferences” section and a “Rules” section. Keep the instructions specific enough that Claude could actually check its own work against them, and keep the whole file under 200 lines — longer files load in full every session, which eats context and (per Anthropic’s docs) tends to make Claude follow them less reliably anyway.
- Create a MEMORY.md next to it. An “Active Projects” section and a general notes section is plenty to start.
- Add one line to CLAUDE.md telling Claude to write to MEMORY.md whenever you say “remember this.”
- Test it before you trust it. Tell Claude to remember something small, open a fresh session, and ask what it knows. If the answer’s wrong or blank, check that both files are actually sitting in the folder Claude is working from – not a subfolder, not a different project. That was my mistake the first time around, and it took me longer to notice than I’d like to admit.
Where it doesn’t hold up
Neither file enforces anything. Claude reads them and tries to follow them, but there’s no hard rule stopping it from ignoring one if two instructions contradict each other — it’ll just pick one, and it might not tell you it did. Worth reading back through both files every so often, especially once a project’s been running a while and the notes start piling up.
Calling it a memory upgrade oversells it a little. It’s closer to a habit: you stop retyping the same three sentences at the start of every conversation. Small thing. Doesn’t feel like much the first week. After a month of not re-explaining yourself, it starts to feel like the obvious way this should’ve worked all along.