Why Claude Code forgets - and why that is not a flaw
The Claude Code Memory Bank is the fastest fix for the most common builder frustration: you close a session, open a new one the next day, and Claude has no idea what you built yesterday. Every conversation starts blank. This is not a bug. Claude Code works in context windows - it processes everything you tell it in one session, but when the session ends, so does its memory. The model itself retains nothing between runs.
For small scripts and one-off tasks this is fine. For anything with real scope - a product you are iterating on, a client codebase, a set of design decisions that took three conversations to land - re-establishing context every morning is a real cost. The Memory Bank solves this by keeping that context in a file Claude can read instead of making you retype it.
What a Memory Bank actually is
A Memory Bank is a plain markdown file - or a small set of files - that lives in your project directory and contains the information Claude needs to work effectively from the first message of a new session. Think of it as a handoff doc written by yesterday's you for today's Claude.
The reason it works is that Claude Code reads your project directory when you start a session. If you reference the Memory Bank files in your CLAUDE.md, Claude picks them up automatically. You do not have to paste context in manually every time.
- It captures decisions that are not obvious from the code itself - why a certain approach was chosen, what was tried and rejected.
- It carries the current state of open work - what is done, what is in progress, what is waiting.
- It holds preferences and constraints - tech stack choices, style rules, client-specific requirements.
The two files every Memory Bank needs
After running this system across a dozen active projects, two files carry almost all the value. One file for the current state, one file for the reasoning.
| File | What goes in it | How often updated |
|---|---|---|
| memory/project.md | Current state: what is built, what is in progress, what comes next. Written in plain present-tense sentences. | After every significant session - 5 minutes maximum. |
| memory/decisions.md | Reasoning log: key choices made, alternatives rejected, constraints discovered. One short entry per decision. | When you make a choice worth remembering - not every session. |
Some builders add a third file for client-specific context or repeated reference material. Start with two and add more only when you feel a clear gap.
How to set up your Memory Bank in ten minutes
Open Claude Code and navigate to your project. Create two files in the root: memory/project.md and memory/decisions.md. Then add a single instruction to your CLAUDE.md file pointing at them.
Fill project.md with the current state of your project. Three sections cover most cases: what exists and works, what is currently being built, and what comes next. Keep sentences short and factual. This is a status snapshot, not a design doc.
Fill decisions.md with choices you have already made that future Claude should not revisit. Include the decision, a one-sentence rationale, and the date. Example entry: 'Using Supabase for auth - 2026-07-15. Chose over Clerk because we already have a Supabase project for the database and did not want a second vendor.'
The three habits that keep it working
The Memory Bank only stays useful if you update it. Three habits keep it accurate without becoming a maintenance burden.
- End-of-session update: before you close Claude, spend two minutes updating project.md to reflect what changed. What moved from in-progress to done, what new work opened up.
- Decision logging: when you make a real choice - a tech decision, a scope change, a rejected approach - write one line in decisions.md immediately. Two sentences maximum.
- Monthly review: once a month, read both files and remove anything that is no longer true. An accurate slim file beats an exhaustive stale one.
The end-of-session update also acts as a forcing function to close out work clearly. It is harder to write 'the auth flow is done' if it is not quite done. Builders inside the Club who run this system say it surfaces incomplete work they would have forgotten.
Join Claude Code Club
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Does Claude Code have built-in memory?
Not between sessions. Within a session, Claude holds everything in its context window. Once you close and reopen, the context resets. The Memory Bank system fills that gap with a structured file Claude reads at the start of each new session.
What is the difference between a Memory Bank and CLAUDE.md?
CLAUDE.md is for instructions and preferences about how Claude should work. The Memory Bank is for the current state of your project - what is built, what is in progress, what decisions have been made. Both can live in the same project, and CLAUDE.md can tell Claude to read the Memory Bank files.
Does the Memory Bank slow Claude down?
Only marginally. Reading two short markdown files adds a few seconds to the first message of a session. The time saved re-explaining context far outweighs it, especially on projects you return to regularly.
Can I use the Memory Bank across multiple projects?
Yes. Each project gets its own memory directory. The CLAUDE.md in that project points to its own files. There is no cross-project bleed.
What should I not put in the Memory Bank?
Passwords, API keys, or any secrets. The Memory Bank files are plain text read into Claude's context. Store secrets in environment variables or a secrets manager, not in files Claude reads.
Last reviewed by David Iya on July 29, 2026
