Project Memory Basics

Every time you start a new Claude Code session, Claude begins with an empty context window. It does not remember yesterday's conversation. That has a cost, and in this lesson we see exactly what it is and how to fix it.

Seeing the problem

Start Claude Code in the project and ask:

What is this project about?

Press Ctrl+O to open the transcript view and watch what Claude does. It searches for files, opens index.html, app.js and styles.css, maybe looks for a package.json, and only then writes a summary:

• It is the Telusko Workflow Engine, a Kanban board for video production
• Cards move through stages like code_ready, recorded, editing, uploaded, published
• There are roles: Admin, Content, Editor, Uploader
• Only the frontend exists. Data is in memory and the API calls fail on purpose

That is a decent summary. Now close the session, start a new one, and ask the same question.

Claude scans the files again. Different order, similar result, same cost. On this tiny project it takes seconds. On a project with hundreds of files, it means minutes of waiting and a lot of tokens, every single session.

The junior developer analogy

Imagine a new junior developer joins your team. On day one you spend two hours explaining the project. They read files, connect the dots and finally understand it.

Now imagine they come back the next day and ask, "Can you explain the project again?" And the next day. And the next.

A human remembers. Claude, by default, does not carry yesterday's session into today's. This is called the cold start problem.

The fix: CLAUDE.md

CLAUDE.md is a plain markdown file where you write down what Claude should know about your project. Claude Code reads it automatically at the start of every session and keeps it in context.

A good CLAUDE.md typically contains:

With this file in place, Claude no longer needs to rediscover the basics. It reads the file, understands the project, and only opens the specific files a task requires.

The .claude folder

You will also notice a hidden folder called .claude. It does not exist in a fresh project. Claude Code creates it the first time it needs to save something, for example when you choose "Yes, and don't ask again" on a permission prompt.

There are two .claude folders to know about:

Here is what can live in the project's .claude folder:

.claude/
├── settings.json        # shared settings and permission rules (commit this)
├── settings.local.json  # your personal settings and saved approvals (gitignored)
├── CLAUDE.md            # alternative location for the project CLAUDE.md
├── agents/              # custom sub-agents (Section 7)
├── skills/              # custom skills (Section 9)
└── rules/               # topic-specific rules, optionally scoped to file paths

Open .claude/settings.local.json after the earlier demos and you will find the allow rules you created by choosing "don't ask again", such as permission to run start commands. You can clean these up any time. Deleting the file simply means Claude will ask again.

How a session starts

1. You run claude
2. Claude Code loads your CLAUDE.md files (user, project and others)
3. It loads the first part of the auto memory index (covered in Testing Project Memory)
4. The session starts with that context already in place

You still pay for the tokens of CLAUDE.md in every session, because it is loaded into context every time. That is why it should be short and focused, which we cover next.

Official references

• How Claude remembers your project
• Explore the .claude directory
• Explore the context window

Written By: Shramik Masti