Part 1 of Claude Code, Beyond the Prompt — patterns from running a live automated trading system on Claude Code. Start with the intro.
You know the loop.
You open Claude Code. You explain your project — the stack, the conventions, the module that's half-refactored, the database that's named something weird for historical reasons. Claude gets it. You do good work for an hour. You close the terminal.
Next session: blank slate. All of it, gone. So you explain it again. And again the session after that.
Most people accept this as the cost of working with an AI. It isn't. Claude Code has a memory system built in. The problem is that a lot of people don't use it — and most of the people who do use it wrong, by dumping everything into one file that slowly rots into something nobody trusts.
The fix is almost embarrassingly simple. It's the highest-return change in this whole series, and the first version took me about ten minutes. Here it is.
Claude reads a file before every session
Drop a file called CLAUDE.md in your project root. Claude Code loads it into context automatically at the start of every session. Whatever's in it, Claude knows — without you saying a word.
That's the entire mechanism. (There's also a user-level file at ~/.claude/CLAUDE.md for things that apply across all your projects, but project-level is where the action is.)
So the real question was never "how do I make Claude remember." The mechanism is already there. The question is what you put in it — and that's where almost everyone goes wrong.
The mistake: one file for everything
The natural instinct is to put everything in that one file:
We use Postgres, never SQLite. Tests run with
make test. Currently mid-refactor on the payments module. Staging DB is down. TODO: migrate the auth service.
Looks reasonable. It's a trap.
You've just mixed two things with completely different lifespans. "We use Postgres, never SQLite" is true for a year. "Currently mid-refactor on payments" is true for three days. "Staging DB is down" might be false by this afternoon.
When they share a file, two things break:
- The stable rules get buried in a stream of transient status updates.
- The whole file loses trust. When half of it is stale — wait, is the payments refactor still happening? — you stop believing any of it. And a memory you don't trust is worse than no memory, because now you have to re-verify everything anyway.
The fix: split by how often it changes
Two files:
-
CLAUDE.md— the stable stuff. Rules, architecture, conventions, hard do-nots. Changes maybe once a month. This is your project's constitution. -
MEMORY.md— the dynamic stuff. What's in flight right now, what changed recently, what's next, deadlines. Changes every session.
The split is not by topic. It's by change frequency. That's the whole trick.
Now each file has a clear update cadence and a clear trust level. CLAUDE.md is stable ground truth. MEMORY.md is "here's the current situation, and it's expected to move." You never again have to wonder whether a line is still valid — the file it lives in tells you.
The 10-minute starter
Copy these. Fill in the blanks. You're done.
CLAUDE.md
# CLAUDE.md — <Project Name>
## Stack
- <language / framework / database / key libraries>
## Conventions
- <how you name things, how files are organized>
- Run tests with `<command>`
## Rules (do / don't)
- Use <X>, never <Y> — because <reason>
- Never touch <thing> directly
- <the mistake you keep having to correct>
## Architecture (the 30-second version)
- <entry point> → <core module> → <data layer>
- Key files: <file — what it does>
## Memory
- Read MEMORY.md at the start of a session for current state.
- Update MEMORY.md at the end of any session that changed something.
MEMORY.md
# MEMORY.md — current state
## Now
- Working on: <the thing in flight>
- Watch out for: <this week's gotcha>
## Recently changed
- <date>: <what changed>
## Next
- <what's queued>
That last block in CLAUDE.md — the one telling Claude to read and update MEMORY.md — is what turns two static files into a system. (The habit that keeps it honest is the entire subject of Part 2.)
How I scaled it
My CLAUDE.md is a genuine constitution: rules, architecture, and the critical do-nots — the things that would cause real damage if forgotten. Which files are the live ones versus one-off scripts. What must never be run against production. The deploy discipline. It changes maybe monthly, and every line earns its place.
My MEMORY.md is a living dashboard. A Now section lists every active workstream in one line each. A small table tracks upcoming deadlines. An archive holds the resolved stuff. It changes every single session — because in a system with a dozen things running and experiments that resolve on specific dates, "current state" is the product.
Under that sits a second tier: MEMORY.md is an index — one line per topic — and the deep context for each topic lives in its own file, loaded only when it's relevant. That keeps the always-loaded file skimmable while the depth stays one link away. (Why "skimmable" matters for your token bill is Part 7.)
The five rules that make it work
The templates are easy. These are the lessons that took me longer, and they're what separate a memory system from a text file that rots:
Split by change frequency, not by topic. This is the core. If you remember one thing, remember this one.
Give each file a cadence — and close the loop. A memory file only works if it's current. I update
MEMORY.mdat the end of every session that changed something. Skip the habit and the file rots within a week, and you're back to re-explaining everything. (Part 2 is entirely about making this automatic.)One fact, one place. Link, don't duplicate. The moment the same fact lives in two files, they drift — and now you don't know which is true. Write it once; reference it everywhere else.
Have a precedence rule. When the stable file and the dynamic file disagree, the dynamic one wins — it's newer by definition. Put that rule in writing so Claude knows which to trust in a conflict.
Treat memory as a snapshot, not gospel. This is the one people miss. A memory file records what was true when you wrote it. Code moves. Before Claude acts on a remembered fact — "the config flag is called
X" — have it verify against the actual code. I keep a literal line in myCLAUDE.md: before citing a memory fact in an action, verify it with a read. It has caught a dozen would-be mistakes where a remembered detail had quietly gone stale.
What it's worth in practice
Not "10x productivity." I'm not going to insult you with that.
Concretely: you stop re-explaining your project. Claude's first suggestion in a session is already context-aware instead of generic. Reviews land closer on the first try because it knows your conventions. And — a bonus I didn't expect — the file becomes genuinely useful to you. MEMORY.md is the fastest way for me to remember what I was doing three days ago.
It isn't magic. It's a text file Claude reads. But it's the difference between an assistant with amnesia and one that picks up exactly where you left off.
Next
A memory file is only as good as your habit of keeping it current — and "remember to update it" is not a habit, it's a wish. Part 2 is the ritual that makes it automatic: a session start-and-close routine that grounds Claude in current state before it touches anything, so precision comes from state rather than from hoping you wrote a good enough prompt.
Part 1 of a series on running real systems on Claude Code. The deeper agent-memory research is open source — see RE-call. Part 2 lands next week.
Top comments (0)