12-step guide to persistent memory for Claude agents

I have combined everything that actually works about Claude memory -official docs, the Dreaming research preview, real production setups - into one walkthrough.

Follow my Substack to get fresh AI alpha: movez.substack.com

Bookmark this. Save it. By the end you will have an agent that remembers permanently - not "within a chat," but across weeks.

That is not hyperbole. Until March 2026 this was impossible for normal users. Now it takes 12 steps.

Why every agent you have built is a goldfish.

Every time you open a new Claude chat, it starts from zero.

It does not know your name. It does not remember the three corrections you made yesterday, the workaround it discovered last week, or the fact that you hate bullet-point summaries.

Each session it rediscovers the same things, makes the same mistakes, and asks the same questions you already answered.

This is not a flaw in how Claude is marketed. It is a fundamental property of how language models work: each session starts fresh unless you explicitly feed context back in.

For a chatbot, that is fine. For an agent running real, repeating work, it is the single biggest reason your setup plateaus. An agent with no memory is exactly as useful on run 100 as it was on run 1.

Layer 1 is a sticky note. Layer 4 is an employee who reflects on the week every Friday and comes back sharper. These 12 steps build all four, in three parts.

1. Turn on Claude's built-in memory

Start with the thing most people do not realize already exists. In March 2026, Anthropic rolled out persistent memory, called "Chat Memory" - to every Claude account, free and Pro alike.

Claude now remembers your preferences, ongoing projects, and working style across every conversation, automatically, until you tell it to forget.

Click your profile icon → Settings → Capabilities → scroll to the Memory section, and confirm "Generate memory from chat history" is on.

Under the hood it runs Memory Synthesis - Claude distills your conversations into a profile roughly every 24 hours. This is the baseline everything else builds on.

2. Seed your memory deliberately instead of waiting

The counterintuitive part the docs are explicit about: do not wait for Claude to infer your preferences from history - that synthesis only runs once about every 24 hours.

Tell it directly in a fresh conversation. Explicit beats inferred every time, and it lands immediately instead of a day later.

Remember the following about me for future conversations:

- I work in [field] and my main projects are [X, Y]
- I prefer [direct prose / no bullet points / short replies]
- My writing style is [describe it]
- Never [the thing you always have to correct]

Claude writes these into memory. The next conversation starts already knowing them. One message eliminates an entire category of repeated explanation.

3. Create a Project as your agent's home

A Project is a persistent workspace where the instructions stay loaded across every conversation inside it. This is Layer 1 in its strongest form.

Go to Projects → New Project. Name it after the job, not the topic. Then fill the custom instructions box with the agent's role, standards, and constraints. Every chat inside that Project inherits them.

4. Understand what Projects do NOT remember

This is where most people get burned. Projects persist instructions. They do not persist conversation memory by default.

You set up a Project, give it detailed context, work for a few conversations - then start a new chat in the same Project, and everything you discussed before is gone.

The architecture decisions, the half-finished task, the debugging session -vanished. The Project remembers its instructions, not your history.

5. Add a living memory file

The simplest persistent memory that actually works is a single file the agent reads at the start and appends to at the end.

In Claude Code this is CLAUDE.md; for any agent it can be a memory.md in Project Knowledge.

The rule the docs hammer on: keep it lean. A fresh session can spend roughly 20,000 tokens loading instructions before you type anything.

Do not treat this file like a wiki dump. If you use Claude Code's /init to generate a starter file, the counterintuitive next step is to delete most of what it generates - it states obvious things the model already sees.

6. Turn on auto memory

Claude Code has an auto-memory mechanism: it writes notes to itself based on your corrections and preferences, and loads them at the start of every session.

Toggle it with /memory in a session, or set autoMemoryEnabled in project settings.

Now the agent does light self-documentation. When you correct it, the correction can survive into the next session instead of evaporating.

7. Structure the memory file so it stays useful

A memory file that grows without structure becomes noise. Give it sections:

## Preferences
- Bullet summaries over prose for status updates
- Always cite the source file for any claim

## Decisions
- 2026-04-18 - chose Postgres over Mongo (relational reporting)

## Known workarounds
- Export tool chokes on files >50MB; split first

## Recurring mistakes to avoid
- Do not auto-approve PRs touching the auth module

Each entry earns its place. This is the file the agent consults to stop repeating yesterday's mistakes.

8. Decide what is worth remembering

Not everything should be saved. The discipline here is the whole game. After each significant session, the agent reviews what happened and extracts only what is worth keeping: a decision, a workaround, a preference, a failure mode. Everything else is forgotten on purpose.

A good filter: would this change how the agent acts next time? If yes, store it. If no, let it go. Memory that stores everything is as useless as memory that stores nothing.

9. Understand what Dreaming actually is

On May 6, 2026, at Code with Claude, Anthropic shipped Dreaming as a research preview for Managed Agents. The name is borrowed from neuroscience on purpose: when humans sleep, the brain consolidates the day's experiences into long-term memory. Dreaming does the same for an agent.

It is a scheduled background process. It reads the agent's existing memory store plus past session transcripts, then produces a new, reorganized memory store: duplicates merged, stale entries replaced with the latest value, and genuinely new insights surfaced.

One condition matters before you bother: Dreaming only helps agents that run the same kind of task repeatedly. It consolidates patterns across many sessions, so a one-off agent has nothing to consolidate. Run it on a workhorse, not a tourist.

10. Run a dream - the exact API procedure

Dreaming is a research preview, so there are three prerequisites before you write any code: a Managed Agents API key, access to Dreaming requested through Anthropic's form (it ships gated), and a Python or TypeScript environment with the latest Anthropic SDK.

Every dream call needs two beta headers stacked together - the SDK sets both automatically if you are on the dreaming-aware version:

anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21

The call itself takes two kinds of input: the existing memory store you want to consolidate, and up to 100 session IDs - recent agent runs Claude will mine for patterns.

You can also pass instructions to steer what the dream focuses on:

dream = client.beta.dreams.create(
    inputs=[
        {"type": "memory_store", "memory_store_id": store_id},
        {"type": "sessions", "session_ids": [session_a, session_b]},
    ],
    model="claude-opus-4-7",
    instructions="Focus on coding-style preferences; "
                 "ignore one-off debugging notes.",
)
print(dream.id)  # drm_01...

Supported models during the preview are claude-opus-4-7 and claude-sonnet-4-6. Dreams are billed at standard API token rates for the model you pick, and cost scales roughly linearly with the number and length of input sessions.

The docs are explicit: start with a small batch of sessions, scale up once you are happy with the curation quality.

11. Inspect the output store before you commit

The input memory store stays read-only the entire time. The dream produces a separate output store, and its ID appears in the dream's outputs[] array once the run starts:

# After the dream ends, the output holds the rebuilt store
output_store_id = next(
    output.memory_store_id
    for output in dream.outputs
    if output.type == "memory_store"
)

Now read it. Check that merged entries are correct, that replaced entries actually were stale, that the surfaced insights are real and not noise.

This review step is the difference between an agent that gets smarter and one that quietly drifts. Because the output is a brand-new store you opt in to, a dream can never silently corrupt what you already have.

12. Swap it in, schedule it, let it compound

Once you trust the output, the switch to production is a one-line change - point your agent at the new store ID instead of the old one.

Then put dreaming on a schedule: nightly or weekly, depending on how much the agent runs.

Now the loop is closed. The agent works during the day, dreams between runs, and comes back sharper each cycle, with no retraining and no manual reconfiguration.

Archiving an old dream never touches its output store -you manage those separately through the Memory Stores API.

The proof it works at scale: legal-AI company Harvey reported roughly a 6x increase in agent task-completion rates after enabling Dreaming for legal-drafting workflows.

The same jobs that used to fail because Claude kept forgetting filetype quirks and tool workarounds between sessions suddenly started finishing reliably.

The mistakes that break agent memory.

• Treating Projects as memory. Projects persist instructions, not conversation history. Assume otherwise and you will lose context without understanding why.
• Dumping everything into CLAUDE.md. A bloated memory file wastes tokens and buries the signal. Lean and structured beats long and complete.
• Storing memory with no filter. If everything is worth remembering, nothing is. Save only what would change future behavior.
• Auto-deploying dream output. The whole point of the separate output store is review. Skip it and you lose the safety net.
• Running Dreaming on a low-frequency agent. Dreaming consolidates patterns across many sessions. An agent that runs twice a month never accumulates enough.

Conclusion:

Most people will keep opening Claude the way they always have - a fresh, forgetful chat every time, re-explaining themselves on every run, wondering why their agent never gets better.

The ones who build the four layers will have something different: an agent that knows them, accumulates what it learns, and rewrites its own memory to get sharper every week.

Pick the first four steps. Set them up tonight. That alone will change how your next session feels.