Claude Code doesn't need a longer context. It needs a memory.

Every Claude Code session is somebody's first day.

Yesterday it found the root cause. It ruled out two theories. It learned why you're not doing the obvious fix.

This morning, all of that is gone.

In part 1 I gave Claude a desk: a folder for each big piece of work, where the knowledge lives. This post gives it a memory, one that loads by itself before you type a word.

What a session forgets

Two things disappear when a session ends.

The work. What's done, what's in progress, what's blocked.

The knowledge. The findings that took real effort to get.

The usual fix is a TODO list in markdown. It rots in a day, because nothing keeps it honest.

A longer context window only delays the problem. The session still ends.

The tool: beads

beads ↗ calls itself "a memory upgrade for your coding agent". The command is bd.

It gives your project two things:

• A task tracker. Tasks, priorities, and what blocks what.
• A memory store. Facts the agent should know in every future session.

Both live in a small local database inside your project. You and Claude use the same commands.

And the part that matters most: it loads into every new session automatically. No copy-paste. No "remember, yesterday we found…".

Why not just put it in CLAUDE.md?

CLAUDE.md already loads into every session. So why add a tool?

Because they do different jobs. CLAUDE.md is the rulebook. beads is the logbook.

The difference shows up fast. Write "Dark mode: waiting on the new colour palette" in CLAUDE.md. The palette arrives, nobody edits the line, and every new session still thinks dark mode is blocked.

In beads, dark mode depends on the palette task. Close one, and bd ready offers the other by itself.

Two more reasons:

• Your rulebook stays clean. Day-to-day findings don't pile up in a file every teammate loads.
• Wrong facts are easy to fix. Each memory is its own entry, not a line buried in a long file.

Use both. CLAUDE.md says how to work. beads says where things stand.

What belongs in a memory

Not everything. A memory store full of trivia is just noise that loads every morning.

Leave out:

• How the code is structured. Claude can read the code.
• What changed when. That's what git history is for.

Put in:

• Findings that took real effort to establish.
• Corrections to things you used to believe.

Something like this:

bd remember "The signup form saves phone numbers without the country code.
Add it before sending any SMS. Found 2026-10-15 by checking real signups."

Say that took you an afternoon to figure out. Without the memory, tomorrow's session figures it out again, or doesn't. With it, every session already knows.

Set it up

Three steps. Beads does the wiring for you.

1. Install it once (not inside a project):

brew install beads
# or: npm install -g @beads/bd

2. Turn it on in your project. If you followed part 1, run this inside the project's / desk folder.

cd your-project
bd init

bd init creates the database and connects Claude Code for you. That means the hook that loads your tasks and memories at the start of every session, plus a short note in CLAUDE.md telling Claude to use it. You don't edit any settings by hand.

3. Check it worked.

bd setup claude --check

Two green ticks means you're done. If not, bd setup claude installs whatever's missing.

Try it

Give it one real thing to remember:

bd remember "<what you found>. Verified <how>, <date>."

Then close Claude Code, open a fresh session in the same folder, and ask:

What's open, and what do you already know about this project?

If it answers without you explaining anything, it works.

Gotchas

It's scoped to the project folder. Beads finds its data from the nearest git repo. Run it from the wrong folder and it writes to the wrong project, without an error.

Don't let an agent run bd edit. It opens a text editor and the agent sits waiting forever. Use bd update instead.

Wrong memories don't fade. A wrong one loads every morning with the same confidence as a true one. Fix it the moment you notice.

What it doesn't fix

Memory makes knowledge last. It doesn't make it true.

An agent that remembers a wrong conclusion will repeat it, confidently, every day. Verifying things is its own discipline, and it gets its own post.

Next in Claude Maxxing

The desk and the memory make a session start well.

Next is what it can see while it works: real code navigation instead of text search, and read-only access to the systems you'd otherwise copy and paste from.

If you set this up, I'd like to hear the first thing you told it to remember. Get in touch.