CLAUDE.md: The Project's Memory Bank

Transcript

SPEAKER_1: Alright, so last time we established that the real shift with Claude Code is moving from chat to orchestration—setting objectives and letting the agent own the loop. But I've been thinking about something that came up: if Claude is running autonomously across sessions, how does it actually remember anything about the project? SPEAKER_2: That's exactly the right thread to pull. And the answer is a single file called CLAUDE.md. Claude Code automatically loads it at the start of every session—no prompt required, no setup ritual. It's the mechanism that bridges the gap between one session and the next. SPEAKER_1: So it's like... the project's standing brief? SPEAKER_2: Precisely. Think of it as the operating manual for the agent. It defines the project's purpose, architecture preferences, coding standards, and behavioral instructions. Without it, every session starts cold. With it, the agent is productive from the first command. SPEAKER_1: What actually goes inside it, though? Someone listening might assume it's just a README with a different name. SPEAKER_2: Common assumption, and it's wrong. A README is for humans navigating the repo. CLAUDE.md is for the agent's reasoning. A well-structured file starts with a project overview—two to four sentences on what the project does and where the main code lives. Then the tech stack, key architecture decisions, and coding conventions. That's the stable core. SPEAKER_1: How does the 'Conventions' section differ from something like a 'Commands' section? Because those sound like they'd overlap. SPEAKER_2: Good distinction. Conventions are the rules—naming patterns, file structure, how errors are handled, what style guide is enforced. Commands are executable instructions: the exact build command, the test runner invocation, the deploy script. One tells Claude how to write; the other tells it how to run. Both need to be there, and they serve completely different purposes in the agent's decision-making. SPEAKER_1: And how long should this file actually be? Because I could imagine someone writing a novel in there. SPEAKER_2: That's a real failure mode. The guidance is 300 to 600 words, focused on high-value, stable context. The reason is practical: Claude truncates loaded content after 200 lines or 25 kilobytes. So if someone writes 2,000 words of project history, the agent may never see the critical build command buried at the bottom. SPEAKER_1: That's a hard constraint. So what happens when a project genuinely has more context than fits in 600 words? SPEAKER_2: That's where the memory directory pattern comes in. The CLAUDE.md file itself stays lean, but it references a .claude/memory/ directory containing separate files—MEMORY.md for current sprint context, decisions.md for architectural choices, patterns.md for recurring code patterns, debugging.md for known issues. The main file acts as an index; the detail lives in the branches. SPEAKER_1: So CLAUDE.md is pointing to those files rather than containing everything itself. That's an index-plus-detail pattern. SPEAKER_2: Exactly. And it matters because of that truncation limit. If Claude hits 200 lines in MEMORY.md, it stops reading. So the index tells it where to look, and each detail file stays focused enough to be fully consumed. SPEAKER_1: Now, Claude Code apparently has a three-layer memory system. What are the other two layers beyond CLAUDE.md? SPEAKER_2: Session memory is the first—it's everything Claude holds in context during a single run, but it's gone the moment the session ends. CLAUDE.md is project memory, which persists across sessions automatically. The third is auto memory: Claude can save notes to itself—build commands it discovered, debugging insights, preferences it inferred—and those persist indefinitely. Auto memory is enabled by default. SPEAKER_1: Wait, so Claude is actively writing to its own memory? That's... a different mental model than most people have. SPEAKER_2: It is. And it's why the correction protocol Boris Cherny documented is so powerful. When Claude makes a mistake, the instruction isn't just 'fix this'—it's 'update your CLAUDE.md so you don't make this mistake again.' The file self-improves. Every correction compounds into future sessions. SPEAKER_1: That connects back to what we covered last time—the CLAUDE.md as a shared knowledge base that gets smarter weekly. But here's what I'm wondering: why wouldn't a developer just rely on a system prompt instead? What does CLAUDE.md challenge about that assumption? SPEAKER_2: A system prompt is ephemeral and lives outside the repository. CLAUDE.md is plain text, Git-checked-in, and survives updates, reinstalls, and machine changes. The whole memory stack does. So when Anvesha or anyone on a team clones the repo, the agent's institutional knowledge comes with it. A system prompt can't do that. SPEAKER_1: And everything in those memory files is just plain text, so there's no proprietary format to maintain. SPEAKER_2: Right. Plain text is the whole point. It's portable, diffable, reviewable in pull requests. The team can debate an architectural decision in decisions.md the same way they'd debate code. The agent's memory becomes a first-class artifact of the project. SPEAKER_1: So for our listener, what's the single thing they should walk away building after this lecture? SPEAKER_2: Start a CLAUDE.md file in the root of their most active repository today. Four sections: project overview, tech stack, build and test commands, and coding conventions. Keep it under 600 words. That file is the highest-ROI investment they can make for that project—it eliminates repetitive context explanation permanently, and every session from that point forward starts with the agent already knowing the rules.