Without memory, your agent starts every conversation from scratch. You re-explain who you are, what you prefer, and what you're working on. Every. Single. Time. Memory fixes that. Claude Code maintains a persistent file-based memory that travels with you across sessions, so the agent builds up context about your work the way a good employee does, a little more useful every week instead of starting from zero every Monday.
The mental model.
Claude Code's memory is a small folder of markdown files with a single index file called MEMORY.md. Each memory is one file, usually short (a few sentences to a page). The index lists them all with one-line descriptions. At the start of every session, Claude reads the index, so it knows what memories are available. When a memory becomes relevant, Claude opens the specific file for the full content.
That's the whole system. It's plain text, version-controllable if you want, inspectable, editable. Not a vector database or a magic layer. Just files.
The four kinds of memory worth keeping.
Not everything belongs in memory. There are four specific types that earn their keep:
~ four kinds of memory worth keeping ~
The split matters. User memories let the agent tailor its voice to you; feedback memories prevent repeated corrections; project memories give the agent context it can't derive from the code; reference memories point it at where external info lives.
What to save. What NOT to save.
This is the part most people get wrong. Over-saving bloats the index and kills signal-to-noise. Under-saving means the agent relearns the same things every session. Here's the test:
~ worth saving vs not worth saving ~
The rule behind the rule: if you can derive it from the code or the commit history, don't memorize it. Memory is for things that aren't written down anywhere else. The user's preferred response length isn't in git; memorize it. The fact that UserService has a create method IS in git; don't memorize it.
Memory hygiene. The stuff most people skip.
Keep the index under 200 lines. Claude reads the whole index at the start of every session. A bloated index costs tokens, costs attention, and makes the good memories harder to find.
Delete memories when they stop being true. "User is researching X" should die when X is done. Otherwise every future session starts with a slightly-wrong picture of you.
Organize by topic, not chronologically. Memory is not a journal. Rearrange so similar things live together.
Prefer specific over general. "User prefers shorter responses" is vague. "User rejects responses over 200 words; trim aggressively" is actionable. The more specific, the more the agent can actually follow it.
Include the WHY on feedback memories. "Don't mock the database in tests. Reason: last quarter a mock-passing test masked a broken migration in prod." The reason lets the agent apply the rule to edge cases, not just the literal case.
The three failure modes you'll hit.
Stale memory. A claim in memory stops being true. "User is working on auth rewrite" is saved; six months later, the auth rewrite shipped. The agent still acts as if auth is in progress. Fix: check the current state before acting on memory. If memory contradicts reality, trust reality and update the memory.
Context bloat. You've been using the agent for a year and have 80 memories. Every session starts with a wall of text. The signal-to-noise drops. Fix: prune aggressively. A memory that hasn't been relevant in 30 days is a candidate to delete.
Wrong inferences. The agent reads "user prefers React" and applies it to a backend-only question. Memories are snapshots; the agent needs to judge when they apply. Make your memories specific enough that misapplication is hard.
When memory really shines.
Memory isn't magic. But when it's working, the difference is huge:
Onboarding happens once. You explain your role, your preferences, your standards to the agent one time. Every session after that inherits all of it automatically.
Feedback compounds. A correction you give today, captured as a memory, shapes every session going forward. You stop repeating yourself.
Project context accumulates. On a multi-month project, the agent's understanding grows over time. The first week it's clueless; the third month it's genuinely helpful.
Team alignment via committed memories. If you check memory files into git, your whole team's agents pick up the same context. Onboarding a new team member's agent is a git pull.
How to control it manually.
You don't have to wait for the agent to capture things. Just tell it:
"Remember that I prefer X." → Claude writes a new memory.
"Forget what you know about Y." → Claude removes or updates a memory.
"Check your memory for Z." → Claude reviews and reports.
Explicit control is especially useful early on when you're still teaching the agent what matters. After a month or two, most memory management happens automatically - you just live your work and the agent captures the useful bits as they come up.
The bottom line.
Memory turns an agent from a stranger into a coworker. It's not the flashiest feature of Claude Code, but it's the one that makes the agent feel like it's yours. Spend a little time pruning and curating, and what you get back is an assistant that knows you, knows your work, and doesn't make you repeat yourself.