Detailed content
🧠 The Three Levels of Memory
The idea is simple: the more relevant context Claude has about you and your project, the better the answers and code. But not all data is the same — some change all the time, others hardly ever. That's why we separate memory into three levels, each with a different "rate of change."
The mental model of short-, medium-, and long-term memory—and how all three fit into one system.
Without this map, people put everything into the conversation and get frustrated when the answers get worse. With it, you know where each piece of information lives.
Short = session · Medium = CLAUDE.md · Long-term = knowledge base on disk · each level has its own rate of change.
Short — the now
What you said in this conversation. It lives inside the session; it disappears when you open a new chat. It changes all the time.
Medium — the project manual
One CLAUDE.md at the root of the folder, it says what the project is, its goal, tech stack, and decisions. It changes sometimes, but remains stable overall.
Long-term — the living dead archive
Notes, decisions, and lessons learned stored on disk for you to consult months later. It almost never changes; it only grows.
🏢 The office analogy
A short-term memory is what’s scattered across your desk right now. The CLAUDE.md is the fixed board on the wall with the project rules—whoever enters the room reads it first. The knowledge base is the filing cabinet behind you: you don’t check it all the time, but you know where to find things.
⭐ The golden rule
The best memory system is the one that doesn't require you to be in a specific chat to work. If you open a new conversation from scratch, Claude should perform almost as well — because what's important is written in a file, not trapped in the previous conversation.
⏱️ Short memory and context rot
Short-term memory is the state of the current conversation plus the basics about you. It's the most fragile: disappears with every new chat. And there's a tricky side effect — when the conversation gets too long, quality drops. It's the context rot. That's why starting over is healthy, not a waste.
The state of the current conversation plus general instructions about you.
It’s the most fragile level—knowing that helps prevent frustration and teaches you when to start over.
Session context · general instructions · context rot (quality drops when the conversation gets too long).
✓ Concise conversation
- ✓Focus on one topic at a time—sharper answers.
- ✓Start over without fear when you change topics.
- ✓Durable context is already in a file, not in the conversation.
✗ Never-ending session
- ✗Drag everything into one chat—the quality keeps dropping.
- ✗Thinks a long conversation means more memory (it’s the opposite).
- ✗Loses everything when the chat closes, with nothing saved.
💡 Practical tip
When the conversation feels “heavy” or you notice the responses getting worse, open a new chat. If your CLAUDE.md and your knowledge base are in order, you won’t lose anything — starting over is part of the method.
🪣 Organize your life into “buckets”
Before writing a CLAUDE.md, you need where to put it. The foundation of average memory is dividing everything you do into 5–8 major areas — the buckets (buckets) — and turn each one into a folder.
Divide your workstreams into 5–8 buckets, each becoming a folder on your computer.
It’s the foundation of medium-term memory. Without buckets, there’s nowhere for a CLAUDE.md.
Bucket = cluster of related projects · one folder per bucket · start simple (pessoal, cliente-x, estudos).
Ask Claude to organize
Use the bucket prompt (Prompts section) to group your activities into 5–8 areas.
Create one folder per bucket
On your computer, a clearly named folder for each bucket.
Set aside a bucket pessoal
Always have a place for your own data and documents.
💡 Practical tip
Don’t look for the perfect taxonomy. Start with a few broad buckets and adjust later — it’s easier to split a large bucket than to combine ten small ones.
📋 CLAUDE.md — the project manual
O CLAUDE.md is a file in each folder’s root that explains the project to Claude. Only one per folder, short (~200 words). Claude reads this file automatically when it opens the folder — it becomes your “guiding star.” It’s the heart of medium-term memory.
A file CLAUDE.md at the root of the folder, a short description of the project for Claude.
It’s the heart of medium-term memory. Read automatically, it becomes the fixed reference for all the work in the folder.
What it is · objective (north star) · stack · fixed decisions · memory map · references. Decisions become rules (e.g., “no AI-generated posts”).
Template of CLAUDE.md (ready to copy)
# CLAUDE.md — <nome do projeto> ## O que é esta pasta <Uma frase: o que vive aqui e para quê.> ## Objetivo (north star) <O resultado que este projeto persegue. Toda decisão é medida contra isto.> ## Stack <Ferramentas, linguagens, serviços usados. Ex.: Next.js, Stripe, Supabase.> ## Decisões fixas - <Decisão 1 — ex.: tudo em português.> - <Decisão 2 — ex.: sem dependências pesadas.> - <Decisão 3 — ex.: nada de conteúdo gerado por IA sem revisão.> ## Mapa de memória - Base de conhecimento: ./conhecimento/ - Subpastas por tema: <ex.: decisoes, notas, referencias> ## Memória (memory save) Quando eu pedir para salvar/lembrar uma conversa, grave o essencial em ./conhecimento/ na subpasta mais relacionada ao tema. ## Referências - <link ou caminho de algo importante.>
Copy the template
Use the block above as a starting point.
Fill in the goal, stack, and decisions
Specific to each bucket. Save as CLAUDE.md at the root of the folder.
Ask Claude to interview you
It asks 3–5 questions and fills in what’s missing, keeping the file short.
✂️ Keep it lean
Aim for ~200 words—something that fits on one screen. If it gets too long, move the details to the knowledge base. The CLAUDE.md captures “the project today,” not the history.
🗄️ Long-term memory: the foundation that grows
Long-term memory consists of notes and decisions saved in text files (markdown) that you consult in the future. The CLAUDE.md takes care of "what the project is like today"; the knowledge base keeps the history and lessons learned.
Notes and decisions in linked markdown files, organized in topic-based subfolders.
It’s the project’s institutional memory—what you decided and learned, available months later.
Interlinked Markdown · subfolders by topic · hand-editable · tools like Obsidian only visualize the files (they're optional).
✓ Goes into long-term memory
- ✓Important decisions (with date and reason).
- ✓Frameworks and lessons that remain useful for months.
- ✓References and notes you’ll want to revisit.
✗ DOESN’T go there
- ✗The entire conversation copied and pasted.
- ✗Day-to-day details that keep changing.
- ✗Things that belong to
CLAUDE.md(the “today”).
🔭 Obsidian is optional
The knowledge base is just files .md in folders — you don’t need any app. Tools like Obsidian simply visualize and connect these files; the content remains yours, in text, on disk.
💾 "memory save": record what matters
O memory save is a routine: when you say “save this,” Claude records the essentials of the conversation in the right folder in the knowledge base. It turns good conversations into permanent knowledge— without manual copy and paste. It's what closes the loop between the three levels.
A routine where, when you say "save this," Claude stores the essentials in the right folder in the knowledge base.
Turns good conversations into durable knowledge, without manual work.
Memory section in CLAUDE.md · choose the right subfolder · save only what has lasting value (decisions, frameworks).
Add the section to the CLAUDE.md
Say where save when you ask (use the template’s "Memory" section).
Point to the database path
E.g.: ./conhecimento/ with subfolders by topic.
Ask Claude to choose the subfolder
Based on the conversation topic — and save only durable decisions and learnings.
Going deeper (optional): why starting over doesn’t lose anything
With CLAUDE.md + an orderly knowledge base, opening a new chat is safe: what matters is in files, not the session. You avoid context rot and keep performance stable. Memory can’t depend on the previous conversation — that’s the system’s final test.
Self-check (optional): where does the “guiding star” that Claude reads automatically when opening a folder live?
✏️ Exercises
1. Map your buckets (easy)
List 5 to 8 areas of your life/work. Criterion: each bucket is a distinct area, with little overlap.
2. Create a CLAUDE.md for real (medium)
Choose a real project and write a CLAUDE.md of no more than ~200 words. Criterion: has an objective, stack, and at least 2 decisions; fits on one screen.
3. New Chat Test (medium)
Start a new conversation and ask Claude to summarize the project using only the CLAUDE.md. Criterion: the summary matches what you wrote, without adding extra context.
4. Save to the knowledge base (medium)
Create a subfolder conhecimento/ and record 1 decision in Markdown. Criterion: the file exists, is dated, and is in the right folder.
5. Trim it down (medium)
Reread your CLAUDE.md and cut everything that isn’t durable. Criterion: no day-to-day conversation details; only what stays relevant for weeks or months.
⌨️ Ready-to-use prompts
These prompts build your medium- and long-term memory in practice. Copy them, adapt them to your context, and run them in Claude Code. The full library is in Library → Prompts.
Organize into buckets (canonical)
Based on everything you know about me and my work, organize my life into 5 to 8 “buckets.” Every project should fit into one bucket. Don’t make up facts: if information is missing, ask me. Keep it concise.
Original (EN):
Based on everything you know about me and everything I work on, organize my life into 5 to 8 buckets. Put any project into one of those buckets. Don't invent facts — ask me if something is missing. No fluff.
Apply the CLAUDE.md in each folder
Add a CLAUDE.md file to the root of each bucket folder, using the template I'll give you. Then ask me questions about each project to complete the full brief. Only one CLAUDE.md per folder.
Save to long-term memory ("memory save")
When I ask you to save, keep, wrap up, or remember a conversation, record the essentials in markdown in my knowledge base, in the subfolder most related to the topic. Save only lasting decisions and lessons, not the whole conversation.
CLAUDE.md template (ready to copy)
# CLAUDE.md — <nome do projeto> ## O que é esta pasta <Uma frase: o que vive aqui e para quê.> ## Objetivo (north star) <O resultado que este projeto persegue. Toda decisão é medida contra isto.> ## Stack <Ferramentas, linguagens, serviços usados. Ex.: Next.js, Stripe, Supabase.> ## Decisões fixas - <Decisão 1 — ex.: tudo em português.> - <Decisão 2 — ex.: sem dependências pesadas.> - <Decisão 3 — ex.: nada de conteúdo gerado por IA sem revisão.> ## Mapa de memória - Base de conhecimento: ./conhecimento/ - Subpastas por tema: <ex.: decisoes, notas, referencias> ## Memória (memory save) Quando eu pedir para salvar/lembrar uma conversa, grave o essencial em ./conhecimento/ na subpasta mais relacionada ao tema. ## Referências - <link ou caminho de algo importante.>
Tip: keep the CLAUDE.md around ~200 words. If it grows, move the details to the knowledge base.
⚠️ Common errors
- ✗Keep everything in the conversation. Rely on short-term memory and lose context when opening a new chat. Fix: write what matters in the
CLAUDE.md. - ✗
CLAUDE.mdhuge. Fill it with details that keep changing. Fix: keep it to ~200 words; the rest goes in the database. - ✗More than one
CLAUDE.mdby folder. Creates confusion about which one Claude reads. Fix: only one per folder, at the root. - ✗Save junk to long-term memory. Dump the entire conversation into the knowledge base. Fix: save only lasting decisions and lessons.
- ✗Dragging out one endless session. Thinking a long conversation means more memory. Fix: start over without fear; the file-based system preserves the context.
✅ Module summary
CLAUDE.md) and long-term (knowledge base); each with its own rate of change.CLAUDE.md lean by folder.Completion checklist
- ☐ I defined 5 to 8 buckets for my life/work.
- ☐ I created one folder per bucket.
- ☐ Each folder has one
CLAUDE.mdat the root, about ~200 words. - ☐ Each
CLAUDE.mdprovides an objective, stack, and at least 2 decisions. - ☐ I tested a new chat, and Claude summarized the project using only the
CLAUDE.md. - ☐ I created the subfolder
conhecimento/and saved at least 1 decision. - ☐ I added the "memory save" section to
CLAUDE.md.
Next module:
1.4 — Power Features: advanced features to get more out of Claude Code