Table of Contents
What this lesson is about
Claude Code has two distinct kinds of memory — one that lasts only for the current conversation, and one that persists permanently between sessions — and understanding the difference changes how effectively you can work with it. This lesson explains how both types of memory work, how to control what Claude remembers and forgets, and how to keep your memory files accurate and useful over time.
Core concept: the meeting and the notebook
Think about a colleague who is excellent at their job. When you are in a meeting together, they are fully present — they remember everything said at the start of the meeting when something comes up at the end, they connect ideas, they build on context as the conversation develops. That is in-session memory: sharp, complete, and active while the conversation is open.
But when the meeting ends and you come back the next day, they have moved on to other things. They do not automatically carry forward what was discussed — unless someone wrote it down. If you left them a clear written note — “We decided to use blue for the new branding, client prefers formal tone, do not suggest price changes without approval” — they would read it first thing the next morning and act on it immediately.
That written note is cross-session memory: a plain text file that Claude reads at the start of every new conversation to re-establish context that would otherwise be lost.
In-session memory: what it is and how it works
What Claude holds in its head during a conversation
While a conversation is open, Claude remembers everything — every instruction you gave, every decision made, every preference you mentioned, every file it looked at. You do not need to repeat yourself. If you said “use formal English” at the start and come back to it twenty messages later, Claude still knows.
This works because each message you send includes the full history of the conversation so far. It is not that Claude has an independent memory — it is that the entire conversation is sent to it each time, so it always has the full picture.
The limit to in-session memory
Very long conversations can eventually hit a limit — there is only so much text that can be included in a single exchange. For most business users working on day-to-day tasks, this limit is rarely a practical concern. But it is worth knowing that if a conversation runs extremely long, earlier context may start to fade. The solution is simply to start a new session and bring forward what matters — ideally by having Claude update your memory files before you close.
Cross-session memory: how Claude remembers between conversations
How it works
When a new conversation begins, Claude Code reads one or more memory files — simple, plain text files stored on your computer — before it does anything else. These files contain facts, preferences, and context that you want Claude to carry into every future session. After reading them, Claude behaves as if you had already told it all of that information at the start of the conversation.
You can think of these files as a standing briefing document that Claude consults automatically every time it starts work.
Where the files are stored
Memory files live in your project folder or in a dedicated memory folder that Claude sets up. The structure typically looks like this:
your-project/
├── CLAUDE.md ← The main memory file Claude reads automatically
├── memory/
│ ├── preferences.md ← Your working style and format preferences
│ ├── project-context.md ← Background on the project itself
│ └── decisions.md ← Key decisions made so far
└── (your other project files)
The file called CLAUDE.md is the one Claude Code looks for by default. It is a markdown file — a plain text document that uses simple symbols like # for headings and - for bullet points. You do not need to know markdown to work with it; it reads perfectly well as ordinary text, and you can open and edit it in any text editor, including Notepad on Windows or TextEdit on a Mac.
What Claude automatically saves to memory
Over the course of working sessions, Claude will save things like:
| What Claude saves | Example |
|---|---|
| Format and style preferences | “Client always wants documents in formal South African English” |
| Project background | “This is a e-commerce site selling handmade ceramics, target audience is gift buyers” |
| Decisions already made | “We decided on a two-tier pricing model in week one — do not revisit this” |
| Feedback you give | “User prefers shorter paragraphs and dislikes bullet-point-heavy responses” |
| Recurring instructions | “Always check the brand colour guide before suggesting design changes” |
Asking Claude to remember something specific
You do not have to wait for Claude to decide what is worth saving. You can tell it directly — at any point in a conversation — to record a specific fact, preference, or decision for future sessions.
Here is a real prompt you could use:
Please remember for all future sessions that:
- Our company's primary brand colour is #1B4F72 (a deep navy blue)
- The client's name is Sipho Dlamini and he prefers email over phone
- We never use exclamation marks in client-facing copy
- Invoices always go to accounts@example.co.za
Save these to my CLAUDE.md memory file now.
Claude will update the file immediately and confirm what it wrote. From that point on, every new session will begin with these facts already loaded.
Asking Claude to forget something
If something in your memory files is no longer true — a decision was reversed, a client moved on, a preference changed — you can ask Claude to remove it just as easily.
Please remove the note about Sipho Dlamini from my memory file.
That project has ended and his details should not carry forward.
Also update the brand colour entry — we've moved from navy to forest green (#2D6A4F).
Claude will find the relevant entries, remove or update them, and confirm the changes. You do not need to open any files yourself, though you always can if you prefer to make the edit directly.
Editing memory files directly
Because memory files are plain text, you can open and edit them yourself at any time — no special tools required. This is useful when:
- You want to do a thorough clean-up of outdated information
- You want to paste in a block of context from another document
- Something Claude wrote is slightly off and you want to correct the wording precisely
To open CLAUDE.md, navigate to your project folder in Finder (Mac) or File Explorer (Windows), find the file, and double-click it. It will open in your default text editor. Make your changes, save the file, and the next time you start a Claude Code session, it will read the updated version.
A memory file is just a text document — there is nothing technical about editing it. If you can edit a Word document, you can edit a memory file.
What NOT to store in memory
Not everything belongs in a memory file. Some information should stay out of these files entirely.
| Do not store | Why |
|---|---|
| Passwords and login credentials | Memory files are plain text — anyone who can open the file can read them |
| API keys or access tokens | Same risk — sensitive keys should go in a dedicated secure store, never in text files |
| Personal identity information | ID numbers, banking details, and similar data should never sit in an unencrypted text file |
| Frequently changing information | If something changes weekly, a memory file becomes a source of outdated instructions rather than helpful context |
| Information specific to one session | If it only matters today, there is no reason to persist it — leave it in the conversation |
Memory files work best for stable, durable facts — things that will still be true in three months.
A real example: a memory file built up over a week
Here is what a realistic CLAUDE.md file might look like after a week of working with Claude Code on a small business website project:
# Project Memory — Thandi's Ceramics
## About the business
- Client: Thandi Mokoena, owner of Thandi's Ceramics
- Business: Hand-thrown ceramic homewares, based in Cape Town
- Target audience: Gift buyers and home décor enthusiasts, primarily women aged 30–55
- Tone: Warm, artisan, never corporate — think boutique not chain store
## Brand guidelines
- Primary colour: Terracotta (#C06B3A)
- Secondary colour: Off-white (#F5F0E8)
- Font: Never specify fonts in copy — the designer handles this
- Always refer to products as "pieces" not "items" or "products"
## Decisions made
- Decided on 15 April: No wholesale pricing on the website — enquiries only
- Decided on 17 April: The shop page will use a masonry grid layout (designer confirmed)
- Decided on 18 April: Shipping is flat-rate R95 nationwide, free over R1 200
## Working preferences
- Thandi reviews all copy before anything goes live — never mark anything as final without her sign-off
- Short paragraphs preferred — no block of body text longer than 3 sentences
- South African English throughout (colour, organised, licence, etc.)
- Oxford comma: yes
## Contact and admin
- Primary contact email: thandi@thandisceramics.co.za
- Accountant handles all VAT queries — do not include VAT advice in any copy
- Hosting is managed by a third-party agency — do not touch server settings
## Ongoing notes
- The About page copy is in draft — do not treat it as approved
- Product photography arriving week of 28 April — hold any image-related decisions until then
This file took shape over a week of natural working sessions. Each time something important was decided or a preference was stated, it was added. The result is a briefing document that means the next session starts informed — no re-explaining, no repeating yourself, no context lost.
Practical Exercise
In this exercise you will set up a memory file for a real or practice project and test that it persists correctly into a new session.
a. Start a new Claude Code conversation in your project folder and ask Claude to create a memory file from scratch:
I'd like to set up a CLAUDE.md memory file for this project.
Please create it and add the following information to start with:
- Project name: [your project name]
- My preferred tone: [formal / conversational / friendly — choose one]
- One decision we've already made: [describe something already decided]
- One thing I never want you to do: [describe a preference or restriction]
Once Claude confirms the file has been created, ask it to show you the contents so you can confirm everything was written correctly.
b. Close the conversation completely. Then open a fresh new Claude Code conversation in the same project folder — do not carry the old conversation forward. Type only this:
What do you know about this project so far?
Claude should be able to describe your project, tone preference, the decision you noted, and your restriction — all from the memory file, without you having said anything in this session. If it can, your cross-session memory is working correctly.
c. Now practise updating and removing a memory entry:
Please do two things to my memory file:
1. Add a new entry: [add any new fact or preference relevant to your project]
2. Remove the entry about [whichever item you want to delete]
Show me the updated file contents when you're done.
Read through the updated file. If anything is worded incorrectly, open the file directly in a text editor, fix it, save it, and start a new session to confirm Claude reads the corrected version.
Common problems and how to fix them
Claude does not seem to remember things from the last session
The most common cause is that CLAUDE.md does not exist yet in your project folder, or the session ended before Claude had a chance to save anything. Ask Claude directly: “Do you have a memory file for this project? If not, please create one and I’ll tell you what to add.” Going forward, end each working session by asking Claude: “Before I close, please save any new decisions or preferences from today’s session to the memory file.”
The memory file contains something incorrect or outdated
Open CLAUDE.md in any text editor, find the line or section that is wrong, edit it, and save. Alternatively, tell Claude: “The entry about [topic] in my memory file is outdated — please update it to say [correct information].” Either approach works; use whichever is faster.
Claude is ignoring a preference that is in the memory file
This can happen if the preference is worded vaguely or buried in a long file. Ask Claude: “Can you read my CLAUDE.md file and confirm you have noted [specific preference]?” If the preference is there but Claude missed it, rephrase it more directly in the file — lead with the instruction, not the explanation.
The memory file has grown very long and disorganised
A memory file that is too long or poorly structured can become harder for Claude to use effectively. Ask Claude: “My CLAUDE.md is getting cluttered. Can you read through it, remove anything that is outdated or redundant, and reorganise the remaining entries under clear headings?” Claude will tidy it up and show you the revised version for approval before saving.
You are not sure what is currently in the memory file
Ask Claude: “Please read my current CLAUDE.md file and summarise everything it contains.” Claude will give you a plain English summary of all active memory entries. You can then decide what to keep, update, or remove.
What you have learned in this lesson
- Claude has two types of memory: in-session memory (sharp and complete while a conversation is open) and cross-session memory (persisted to a file and loaded at the start of every new session)
- Cross-session memory is stored in plain text markdown files — primarily
CLAUDE.md— that live in your project folder and can be opened and edited in any text editor - Claude automatically saves preferences, project context, key decisions, and feedback you give it during working sessions
- You can ask Claude at any time to remember something specific or forget something that is no longer relevant, using plain English instructions
- Memory files can also be edited directly — they are ordinary text files with no technical requirements
- Passwords, API keys, personal identity information, and frequently changing details should never be stored in memory files
- A well-maintained memory file means every new session starts informed — no re-explaining, no repeated context, no lost decisions