How to give Claude Code memory across sessions

Claude Code is very good inside a session and has no memory between them. Close the terminal on Tuesday, open it on Friday, and it doesn't know which feature you were halfway through, which approach you ruled out, or that the login bug is fixed but the password-reset email still isn't sent. You end up re-explaining the project every time, or worse, it confidently redoes work that was already done.

This guide covers what Claude Code actually carries from one session to the next, where that stops being enough, and a setup that keeps a project's plan and progress somewhere every new session reads first.

What Claude Code remembers on its own

There are three things Claude Code gives you out of the box. Each solves a different part of the problem.

CLAUDE.md files

When a session starts, Claude Code reads CLAUDE.md files and puts them in its context. The common places are:

• CLAUDE.md in the repository root, checked in, shared with everyone on the project
• ~/.claude/CLAUDE.md in your home directory, your personal preferences across every project
• CLAUDE.md files in subdirectories, read when Claude works in that part of the tree

You can open and edit them from inside a session with the /memory command. This is the right home for things that are true for a long time: how to run the tests, the package manager, naming conventions, "never edit generated files", the deploy command.

Resumed conversations

claude --continue (or claude -c) reopens your most recent conversation in the current directory, and claude --resume lets you pick an older one. The full transcript comes back, so Claude sees what it did and why.

That's useful for picking a task back up the same day. It gets worse with time: long transcripts get compacted, you rarely remember which of twenty sessions had the decision you need, and a resumed conversation only knows what happened in that one conversation, not in the three others you ran in parallel.

Compaction

When a conversation gets long, Claude Code summarises earlier turns so it can keep going (/compact does it on demand, /clear starts over). Compaction keeps a session alive; it isn't a record you can come back to next week.

Where it breaks down

The built-in tools cover how to work in this repo and what happened in this one conversation. What's missing is the project's state:

• The plan. Which features exist, which stories make them up, and in what order.
• Progress. What's done, what's half-done, what's blocked and on what.
• Decisions. "We tried server actions for the upload and went back to a route handler because of the body size limit."
• Hand-offs. Things only you can do: the API key you still need to create, the DNS record, the dashboard toggle.
• Other agents. If you also use Cursor or Codex on the same repo, Claude Code has no idea what they changed.

People usually try to fix this by stuffing it into CLAUDE.md. It works for a week. Then the file is 600 lines of stale todo items, half of them done, and every session pays for reading it.

Three ways to keep project state

1. A progress file in the repo

The simplest version is a PROGRESS.md (or TODO.md) that you ask Claude to update at the end of every task, plus a line in CLAUDE.md telling it to read the file first.

## Project state
Read PROGRESS.md before starting. When you finish a task, update it:
move the task to Done, add anything you learned, and note what's next.

It's free and it's in git. The downsides show up quickly: Claude forgets to update it when a session ends abruptly, merges between branches conflict on it, and it's hard to see at a glance what's actually in flight.

2. Issues in GitHub, Linear or Jira

If the project already lives in an issue tracker, connecting that tracker to Claude Code over MCP lets it read and update issues. This works well for teams with an established process. For a solo builder it's often more ceremony than help: tickets are written for people, not agents, and nothing tells Claude which issue to pick up or when it's allowed to call something done.

3. A board built for agents

The third option is a project board that the agent itself reads and writes through MCP, with the structure an agent needs: stories with acceptance criteria, a claim so two agents don't take the same work, a review step before anything is called done, and a short "where I stopped" note at the top of every project.

That's what Klio is. The rest of this guide shows that setup, but the habits in the last section apply whichever option you pick.

Setting up Klio with Claude Code

Connect the MCP server

Run this once. --scope user makes Klio available in every repo.

claude mcp add --scope user --transport http klio https://klio.dev/api/mcp

Then start Claude Code, run /mcp, pick klio and choose Authenticate: your browser opens Klio's approval screen. (Or add a token from Settings with --header "Authorization: Bearer <token>".) The full steps are in Use Klio with Claude Code.

Tell CLAUDE.md to use it

A short section makes every request go through the board, not only the first one:

## Klio (project board)
This repo is tracked in Klio; the Klio MCP server is connected.
- All coding work goes through Klio. For anything new, add it first
  (create_issue, or create_feature for a bigger piece).
- If I just say "continue", call get_next_work.
- start_issue before you start, check_criterion as each acceptance
  criterion passes, complete_issue with a short summary when done.

Plan a feature

Describe what you want in a sentence: "Add password reset by email." Claude calls brief_feature to read the project's stack and existing features, proposes a feature split into stories with acceptance criteria, and saves it with create_feature once you agree. Now the plan lives outside the conversation.

What a new session looks like

On Friday you open a new terminal and type "continue". Claude calls get_next_work, which returns:

• the project's resume note ("Password reset: the token table and the request form are done; the email isn't sent yet because RESENDAPIKEY isn't set in production")
• what changed since this agent last looked, including work other agents did
• the next story, already reserved for this agent so a parallel session doesn't grab it

It calls start_issue, which claims the story and returns its acceptance criteria and the files likely involved. It works, ticks criteria with check_criterion as they actually pass, and finishes with complete_issue, which moves the story to review and rewrites the resume note. You never re-explained anything.

Comparing the options

There's no wrong answer. A solo weekend project is fine with a progress file. A team already on Linear should probably connect Linear. If you run agents most days across several projects, a board built for them saves the most time.

What a good resume note looks like

Whichever option you pick, the most valuable single piece of state is a short note at the top of the project. It should answer three questions in two or three sentences: what's done, what's in progress, and what's blocked or next.

Password reset: tokens and the request form are done (APP-21, APP-22).
The reset email is built but not sent in production: RESEND_API_KEY
isn't set there yet (in your inbox). Next: the "set new password" page.

Notice what's not in it: no history, no explanation of the architecture, no list of every file. A new session reads it in a second and knows where to start. If you keep one by hand, rewrite it rather than appending to it; a note that grows becomes another transcript.

Habits that make any setup work

Whatever you use to hold project state, these make the difference:

1. Small stories. A story an agent can finish in one session is a story whose progress is never ambiguous. "Build auth" isn't a story; "Email + password sign-up with a verification link" is.
2. Acceptance criteria up front. "Done" should be checkable: "a wrong password shows an inline error", not "login works". Agents stop when the criteria pass instead of when they feel finished.
3. Write decisions down where they happened. A one-line comment on the story ("using a route handler, server actions cap the body at 1 MB") saves the next session an hour.
4. Hand off what only you can do. Secrets, DNS, billing and dashboards are yours. Make the agent say so explicitly instead of leaving a TODO in the code.
5. Review before done. Let the agent mark work ready for review, and keep "done" as your call. It keeps the board honest.
6. Keep CLAUDE.md short. Instructions, conventions, commands. If you're editing it every day, that content belongs somewhere else.

Common mistakes

• Using one giant session for a week. Compaction quietly drops details. Short sessions with state written down beat one long one.
• Letting the agent decide what's next. Without a queue, it picks what looks interesting. A board with an order makes "continue" mean something.
• Two agents, no claims. Running Claude Code and Cursor on the same repo without a claim on each task means duplicated or conflicting work. See running several agents on one repo.