Claude Memory System

What Claude actually retains

By default, Claude Code retains nothing between sessions. Each new conversation starts with no knowledge of your previous work, your project context, your preferences, or your open items. This surprises people who've been using Claude for months and assume it must know them by now. It doesn't — unless you've built a system that gives it that knowledge.

This isn't a bug to route around. It's a design constraint that, once understood, becomes workable. The memory system you need to build is actually straightforward: a few files, a consistent habit, and knowledge of which layer handles what. The full treatment is in and the upcoming Book 4 (Memory). The free first chapter covers the session file specifically.

In-context memory: what you paste

The simplest form of Claude memory is anything you paste directly into the conversation. Text you put in the context window is immediately available and influencing Claude's responses — but only for that session. When the session ends, it's gone.

In-context memory is best for: current task specifics, recent decisions, content Claude needs to process right now. It's not the right layer for things that should persist across sessions, because it requires you to manually paste it every time.

External file memory: the session file

A session file is a short plaintext document you maintain manually and paste at the top of each new Claude session. It contains: current open items, recent decisions, the active focus, and any context Claude needs to be immediately useful without a lengthy re-explanation.

The session file solves the re-orientation problem: without it, the first ten to fifteen minutes of any new session are spent catching Claude up. With it, Claude is productive within two turns. The discipline is simple — update the file at the close of each session before you close the tab. That update takes two to three minutes and pays for itself immediately in the next session.

Session files should be short. Two hundred words is enough for most working contexts. If yours is growing longer, split it — one file for the current sprint, one for stable background context.

Project-level memory: CLAUDE.md

Claude Code reads a file called CLAUDE.md automatically at the start of every session in a project directory. This is the right layer for stable, project-level context that should always be present: what the project is, how it's structured, what conventions Claude should follow, what to avoid. Unlike the session file, CLAUDE.md changes slowly — it's the permanent background layer Claude always has access to without any manual loading.

The distinction between CLAUDE.md and the session file is temporal. CLAUDE.md carries the things that are true for months. The session file carries the things that are true this week. Both together give Claude a working picture of your project without requiring you to re-explain either.

Auto-memory: file-based persistence

Auto-memory refers to any system where Claude writes its own context to a file that gets loaded in subsequent sessions. This can be configured via hooks: a Stop hook writes a structured summary to a memory file, and a session-start hook loads that file into the next conversation's context. The result is a memory that accumulates across sessions without manual maintenance.

Auto-memory is powerful but requires setup. It's the right layer for: tracking decisions across many sessions on a long project, building a knowledge base Claude adds to over time, or any situation where manual session-file updating isn't sustainable. The tradeoff is that auto-generated memory can drift — Claude's summaries aren't always what you'd write yourself. Regular review of the memory file keeps it accurate.

How memory degrades in a long session

Within a single session, Claude's context window is finite. As a conversation grows longer, earlier parts of the context become less influential on subsequent responses — a phenomenon sometimes called context decay. Instructions stated in the first message of a very long session can effectively fade as more content accumulates.

The practical defense is not to fight the context window but to work with it. Keep sessions focused on a single task or theme. Start a new session when you shift to a new problem. Restate the most important constraints when you notice Claude drifting from them. Shorter, focused sessions are more reliable than one very long one that tries to hold everything.

That exchange is only possible because the session file was loaded. Without it, the first exchange would have been: "What are we working on?" — and the next fifteen minutes would have been re-explanation.

Book 4 covers the full memory system

The memory system that makes Claude genuinely useful across weeks and months — session files, CLAUDE.md discipline, auto-memory hooks, decay management, and long-project context architecture — is covered in Patriola's Guide to Claude: Memory.