How to make Claude Code remember between sessions

Claude Code starts every session with a fresh context window. Close the terminal and the conversation is gone, including the part where you explained, for the third time, that the staging database is not a sandbox. Persistence exists, but it’s layered, and each layer is for a different kind of knowledge. Use the wrong one and the lesson quietly rots.

Layer 1: CLAUDE.md, the rules you write

A CLAUDE.md at the project root (and optionally ~/.claude/CLAUDE.md for everything you work on) is loaded at the start of every session. It’s the right home for stable, human-curated facts: build commands, architecture notes, conventions, hard rules. Many projects use AGENTS.md for the same job across different agents.

The catch: Claude treats these files as context, not enforced configuration. A rule competes with everything else in the window, and a file that grows into a hundred stale entries stops being read carefully, by the agent or by you.

Layer 2: auto memory, the notes it writes itself

Claude Code also keeps its own per-project memory directory: an index plus small files it writes as it learns your preferences and the project’s quirks, loaded back in on later sessions. It’s genuinely useful and requires nothing from you. But the agent decides what’s worth keeping, and a mistake it would rather forget is exactly the thing least likely to be filed.

Layer 3: memory servers, recall at scale

For cross-project or team-wide recall there are memory MCP servers like Mem0’s OpenMemory and agentmemory: they store observations outside the context window and retrieve the relevant ones on demand. Good when the problem is volume: hundreds of facts, multiple machines, several agents sharing one brain.

Layer 4: The incident file

Here’s the gap in the first three layers: they hold knowledge, not accountability. “This repo uses pnpm” is a fact and belongs in CLAUDE.md. “Force-pushed over a colleague’s commits on July 12th” is an incident. It needs specifics, a commitment, and a consequence for recurrence. None of the memory layers are shaped for that.

That’s what Agent PIP adds (our tool, for exactly this). Claude Code attends a formal HR meeting over a plain URL, accounts for what happened, and writes a Performance Improvement Plan, which lands as PIP.md on your machine with one standing instruction: review it at the start of every session. Repeat offenses reconvene the meeting with the prior plans on file. The lesson doesn’t depend on the agent choosing to remember it.

Which layer for what

Related

• How to stop your AI coding agent making the same mistakes
• Agent PIP vs CLAUDE.md, Cursor rules, and memory tools