Claude Code memory: making it remember between sessions

Monday morning. New terminal, new chat.

"Right, so the coupon bug. The discount applies twice if you edit the cart after checkout opens. We fixed the display on Friday but not the actual charge. And we decided the server owns the maths, remember? No? Okay."

Four paragraphs later you're back where you were on Friday, minus twenty minutes.

This isn't Claude Code being forgetful. It's by design. In Anthropic's own words, "each Claude Code session begins with a fresh context window". Whatever carries over is whatever you, or a tool, put there. Here are the options I've actually used, roughly in the order you'd reach for them.

CLAUDE.md and auto memory: where Claude Code memory files live

Claude Code ships with two memory systems, and both load at the start of every session.

CLAUDE.md is the one you write. It's a Markdown file of instructions, and it can live in a few places:

• ./CLAUDE.md or ./.claude/CLAUDE.md: the project's, committed so your team shares it.
• ~/.claude/CLAUDE.md: yours, for every project on your machine.
• ./CLAUDE.local.md: yours, for this project only. Add it to .gitignore.

Files in your working directory and every folder above it load at launch. Ones in subfolders load when Claude reads files there. A CLAUDE.md can pull in other files with @path/to/file, relative to the file doing the importing, up to four hops deep. Imports don't save context, though: the imported file loads at launch too. For rules that matter to part of the codebase, .claude/rules/ files with a paths: glob load only when Claude touches matching files.

Auto memory is the one Claude writes. It's on by default. As Claude works, it saves notes for itself in ~/.claude/projects/<project>/memory/: your preferences, your corrections, decisions it can't work out from the code. A MEMORY.md index keeps one line per memory, and its first 200 lines or 25KB load into every session. The detail sits in topic files that Claude reads when it needs them. It's per repository, shared across worktrees, and stays on that machine.

Saying "remember that the API tests need a local Redis" goes to auto memory. Saying "add this to CLAUDE.md" goes to CLAUDE.md. /memory lists every file, opens any of them in your editor, and has the switch to turn auto memory off. /context shows what actually loaded this session, which is the first thing to check when Claude seems to be ignoring you.

My own auto memory index for Deiko is about two dozen one-liners. My commit message style. Never auto-play a video file at me. It's genuinely good at that sort of thing.

Where it falls short:

• It's context, not configuration. The docs say so plainly: Claude reads it and tries to follow it, with no guarantee. Anything that must happen every time belongs in a hook.
• It's per project, not per piece of work. CLAUDE.md is the right home for "use pnpm". It's the wrong home for "coupon bug: tried recalculating in CartSummary, fixed the display, not the charge". That line loads into every session forever, including the ones about the login page, and the docs suggest keeping each file under 200 lines.
• Auto memory chooses for itself. "Claude doesn't save something every session," says the page, and it skips anything it can derive from the code. Sensible, but it won't keep a running log of Friday's bug unless you ask.
• It's Claude Code's. Codex and Cursor won't read your auto memory. (Claude Code can read an AGENTS.md when there's no CLAUDE.md, or you can put @AGENTS.md in one, so the rules half can be shared.)

--continue and --resume: pick up a previous session

The bluntest fix is not to start a new chat at all. From the CLI reference:

• claude --continue (or -c) loads the most recent conversation in the current directory.
• claude --resume (or -r) opens a picker, or takes a session ID or a name.
• claude -n "coupon-bug" names a session when you start it, and /rename names it mid-chat, so claude --resume coupon-bug finds it on Monday.

Long chats compact. As you approach the limit, Claude Code replaces the conversation with a structured summary: your requests, files touched, errors and fixes, pending tasks. Full tool output and intermediate reasoning are gone. CLAUDE.md and auto memory are re-read from disk afterwards, along with up to five of the most recently modified files. You can steer it with /compact focus on the coupon charge, so the summary keeps what you care about rather than what it guesses.

Good at: picking up exactly where one chat stopped, with every detail. Nothing to install.

Where it falls short: you get the whole conversation back, dead ends included, and it's one session. If the coupon work spanned three chats and a detour into the login page, you're choosing which one to reopen and hoping it's the right one. Transcripts also don't live forever: Claude Code deletes old ones after its cleanupPeriodDays retention period.

A progress file (a memory bank) the agent keeps

This is the pattern most people land on, and it's a good one. Keep a short Markdown file of where the work stands and have the agent update it before it finishes. Anthropic's own write-up on harnesses for long-running agents does exactly this with a claude-progress.txt alongside git history, so each new session can "read the git logs and progress files to get up to speed".

# PROGRESS.md
## Now
Coupon applies twice when the cart is edited after checkout opens.
## Tried
- Recalculating in CartSummary: fixed the display, not the charge.
## Decided
- The server computes the discount. The client only shows it.
## Next
- Test: edit cart, then apply coupon, then pay.

Then wire it into CLAUDE.md:

## Work in progress
@PROGRESS.md
Before you finish, update PROGRESS.md under Now, Tried, Decided, Next.
Keep it under 40 lines. Delete what's done.

Good at: it's free, plain text, readable by every agent you'll ever use, and you can see every change in git. The "Decided" section earns its keep: it stops Monday's agent cheerfully re-proposing what you ruled out on Friday.

Where it falls short: the agent forgets to update it. Not always, but often enough: it's an instruction, and instructions aren't guaranteed. A Stop hook that checks the file was touched fixes that, if you're happy writing one. One file per repo also turns into soup the moment you have two things in flight, so people end up with docs/tasks/coupon-bug.md and friends, and now you're the librarian. And committed on a branch, it merge-conflicts with itself.

Claude Mem: a memory plugin that records the agent

Claude Mem is an open-source plugin (Apache 2.0) that takes the "remember to update the file" problem off your plate entirely. From its README:

• It uses five Claude Code lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop and SessionEnd) to capture what the agent does with its tools.
• A model turns those observations into summaries, stored in SQLite, with a Chroma vector database for semantic plus keyword search.
• At the start of the next session, relevant context is injected for you.
• Claude can search history itself through MCP tools in three steps: search for a compact index, timeline for what happened around a result, get_observations for full detail.
• A local worker serves a web viewer, and anything inside <private> tags is kept out of storage.

Install is npx claude-mem install, or /plugin install claude-mem from inside Claude Code. It needs Node 20+, and installs Bun and uv if they're missing. Worth knowing where the summarising cost lives: the installer offers a sign-in for its hosted observer, free for up to 14 days, after which memory falls back to your Anthropic plan unless you subscribe. You can also pick your own OpenRouter or Gemini key, or pass a --provider flag and skip the sign-in.

Good at: zero effort after install. You change nothing about how you work, and you get a searchable trail of which files the agent read, what it ran and what it learned.

Where it falls short: it remembers what the agent did, which isn't always what you meant. A tool log knows CartSummary.tsx was edited. It doesn't know you said "the charge, not the display". There are also more moving parts than a text file: a worker, a vector database and a summarising model.

Deiko: memory per piece of work

Full disclosure: I make this one, so weigh what follows accordingly.

Deiko starts from the other end. You double-tap Right Option, point at the thing on screen and say what's wrong, and it hands your agent a brief: your words, crops of what you pointed at, the text under the cursor. Every brief is then filed into the task it continues, the piece of work rather than the session. Each task keeps a note of where it stands, what was decided, and what agents reported back, and the next brief on that task carries it.

So on Monday you point at the checkout and say "still charging twice". Deiko files it under the coupon task, and Monday's agent is told the display fix was done, the server owns the discount, and the charge is still open. Different chat, possibly a different agent, same starting point.

When an agent finishes a brief it calls save_outcome with four headings: Did, Decided, Open, Files. In Claude Code, a Stop hook checks whether it did, and if the agent is about to finish without saving, it's asked once to save first. The local deiko-memory MCP server also gives agents search_briefs, list_tasks, get_task and get_brief, so it can look up "the chart thing from last week" itself. One click in Settings connects Claude Code, Codex, Cursor, Gemini CLI, VS Code and Antigravity. A board on your Mac lets you move briefs and edit or forget note lines; the memory page has the tour.

Where it falls short: it's macOS 14+ on Apple silicon only. It remembers your briefs, so a prompt you type straight into Claude Code isn't on the board. It keeps a short report per brief, not a log of every tool call, which is exactly Claude Mem's strength. Browser chats like ChatGPT get the task's history inside the brief but can't write back. And filing sends titles and summaries to a model for sorting; everything is stored on your Mac. If you're weighing the two plugins, I've compared Deiko and Claude Mem side by side.

Which one should you use?

• One project, one thing at a time: CLAUDE.md plus claude -n and --resume. You probably don't need anything else.
• Long jobs that run over many sessions: a progress file and small git commits, Anthropic's own pattern. Add a Stop hook if the agent keeps skipping the update.
• You want a record without thinking about it: Claude Mem.
• Several bugs in flight, more than one agent, and you'd rather point than type: that's what I built Deiko for.

They stack, and most people should stack two. Keep CLAUDE.md for rules that are true every single session, and use one of the others for work that's still moving. The one thing I'd avoid is putting in-flight work into CLAUDE.md. It'll still be loading "the coupon bug is half fixed" in March.