How I Set Up Claude Session Memory
(And What I Got Wrong First)

The problem: Claude forgets

If you've used Claude for anything longer than a single conversation — a real project, a multi-day writing task, a codebase you're building — you've hit the wall. Start a new session and Claude has no idea who you are, what you're building, or what you decided last Tuesday. You re-explain. You re-establish context. You re-answer the same clarifying questions.

This is the single biggest friction point for intermediate Claude users, and the solution is simpler than most people think. But I didn't find the simple solution first.

The wrong approach: the giant system prompt

My first attempt was a long system prompt — everything about the project stuffed into the instructions field. Current status, coding conventions, decisions made, background, constraints. It felt thorough. For about two weeks it worked fine.

Then it became a problem. The prompt grew to 1,200 words. I stopped updating it because it was tedious to edit. It fell out of sync with the actual project. I was spending more tokens on stale context than on actual work, and Claude was occasionally confused by contradictions between the old instructions and what I told it in the session.

The giant system prompt fails for one reason: it's hard to maintain. If keeping the context current requires effort, you won't keep it current.

The right approach: a small, updatable SESSION.md

What works is a small plain-text file — I call mine SESSION.md — that lives in the project root. It's short by design. Its job is to capture the current state of the project in the minimum words needed, so you can paste it at the start of any session and have Claude immediately oriented.

The file is not a history document. It is not a changelog. It captures now, not the story of how you got here.

Exactly what goes in the file

# Project: [name]
## Status
[1-3 sentences: what the project is, where it stands right now]

## Current task
[What you're working on this session — update this at the start of each session]

## Key decisions
- [Decision 1 — brief, outcome only, not the reasoning unless it affects Claude]
- [Decision 2]

## Constraints / always-remember
- [Things Claude must not do or must always do]
- [Stack constraints, style rules, off-limits areas]

## Files that matter right now
- [filename]: [what it does]
      

That's it. No history. No meeting notes. No "here's what we tried on May 3rd." The file is a snapshot, not an archive. The goal is to fit on one screen.

How to use it: paste at session start

At the start of each session, paste the file content followed by your first instruction. Claude reads it as part of your message and begins the session oriented.

No re-explaining. No re-establishing. You're working within thirty seconds.

The update ritual: end of session

Before closing a session, I ask Claude to propose an updated SESSION.md based on what we covered. This takes about ten seconds and keeps the file accurate.

"End of session. Please propose an updated SESSION.md reflecting what we built today — keep it under 30 lines, update the current task to reflect where we stopped."

Claude drafts it. I review it (takes 30 seconds), paste it back into the file, commit it. The next session starts clean.

Common mistakes

• Too long. If your session file is over two pages, it's capturing too much. Cut the history. Only the current state matters.
• Too much decision history. The file should capture outcomes, not reasoning. "We use Postgres" not "we evaluated Postgres vs SQLite for three days and landed on Postgres because..."
• Not updating it. A session file that's three weeks stale is worse than no session file — it actively misleads Claude. If maintenance feels heavy, the file is too long.
• One file for multiple projects. One file per project. They don't mix well.

One more thing: CLAUDE.md

If you're using Claude Code (the CLI tool), there's a companion approach worth knowing about. Claude Code reads a file called CLAUDE.md at the start of every session automatically — you don't have to paste anything. It's meant for persistent project instructions and conventions rather than current state, but you can layer both: CLAUDE.md for the stable context, SESSION.md for the current task.

That combination — stable instructions in CLAUDE.md, current state in SESSION.md — is as good as session memory gets without building something more elaborate.

This is one of the core topics in Book 1: Productivity. If you want the full treatment — including how to structure CLAUDE.md for a production project and how to build an automated update workflow — the first chapter is free.

Read Chapter 1 free →