Claude Code forgets everything when you close it. Fix that.

You spent Friday walking Claude Code through your deploy pipeline: which flags the script needs, why the ORM is pinned, what order the migrations run in. Monday morning you open a fresh session and it asks you how deploys work.

That is not a bug. Claude Code sessions are stateless by design. Everything it learned lives in the session transcript, and the transcript dies when the session ends. If you want it to remember, you have to build the memory yourself. Here is how, in about ten minutes.

Why it works this way

A session's context is expensive. Every token of history rides along in every subsequent request, so the session boundary is also a cost boundary: when you close it, the slate wipes clean and the next session starts cheap. The tradeoff is amnesia. Nothing you decided, tried, or ruled out survives unless it was written somewhere the next session can read.

So persistent memory for Claude Code is really two separate problems: where does durable knowledge live, and how does each new session find it?

Layer 1: a memory file in the repo

Claude Code reads CLAUDE.md files automatically at session start — from the working directory, its parents, and your home folder. This is the zero-infrastructure layer, and it covers everything that rarely changes.

Put this kind of thing in it:

• How to build, test, and lint the project
• The deploy sequence and its quirks ("migrations run before the web deploy, never after")
• Pinned versions and why they are pinned ("ORM stays on 2.x — 3.x broke the migration runner in March")
• Conventions and hard rules

What does not belong: anything that changes week to week. A memory file is a poor diary. It will not tell next month's session that you abandoned the background-worker approach, because nobody updates a markdown file with that kind of news. For the stuff that happens during work, you need layer 2.

Layer 2: memory that follows you between machines

A memory file lives wherever the file lives. If you want memory that follows you — laptop to desktop to cloud dev box — it has to live somewhere central, with the agent reading and writing through a defined interface. That is what an MCP memory server gives you: save/recall tools that any session can call, backed by one store.

The mental model is simple. Session start: the agent pulls a briefing ("what do I know about this project and the current task?"). Session end: the agent files a report ("what did we decide, what failed, where did we stop"). The store accumulates; the sessions stay cheap and stateless.

The 10-minute setup

1. Choose the store. A local file-backed MCP memory server keeps everything on your disk. A hosted one means zero syncing and memory that works from any machine.
2. Wire it into Claude Code. Add the server to your MCP config. Verify its tools show up — save, recall/search, list, delete.
3. Teach the agent the read habit. One line in CLAUDE.md or your project rules: "At the start of each session, search memory for context relevant to the current task before acting."
4. Teach the agent the write habit. A second line: "Before finishing, save durable outcomes to memory: decisions, failed approaches, and current status."
5. Prove it. Kill the session, start a new one, and ask: "What do you know about this project's deploy process?" If it answers from memory instead of asking you, you are done.

Steps 3 and 4 do all the real work. Without them you have a database nobody queries — which is the same as amnesia with extra steps.

What to save and what to skip

Use the future-you test: would future me pay to re-learn this? If yes, save it. Concretely:

• Save: architectural decisions and their reasons, dead ends ("tried the worker-queue approach, dropped it — ordering guarantees were wrong"), environment quirks, the current state of multi-session work.
• Skip: step-by-step transcripts, anything already in CLAUDE.md, temporary debugging noise.
• Revisit: once a month, delete what is stale. An agent that trusts outdated memory will confidently do the wrong thing.

One hosted shortcut

If you would rather not run the infrastructure, Vilix AI is a cloud-hosted memory layer over MCP — one store that every session and every connected tool reads from, so there is nothing to sync or maintain. The tradeoff is straightforward: it is cloud-only, so local-only setups should look elsewhere. (vilix.ai)

---

What is your setup? CLAUDE.md only, a local MCP memory server, something hosted, or are you still re-briefing every Monday? Curious what is actually working for people.