AI Session Handoff Between Machines: Pick Up Where You Left Off

You end the evening at the desktop with Claude Code fully up to speed on the refactor. Next morning you open the laptop, type "keep going," and get a polite blank stare. Nothing broke -- your assistant's brain just didn't make the trip. Here's why that happens, and three ways to fix it, from a committed markdown file to fully automatic.

Why your assistant forgets between machines

Cloud chat products sync your conversation history, which hides this problem. Coding agents don't work that way. Claude Code, Cursor, and their peers are local-first: the context that actually shapes their behavior is a pile of files on one specific disk. Your global ~/.claude/CLAUDE.md, per-project instruction files, rules directories, memory files, session transcripts -- all of it lives on the machine where it was written.

The sync tools you already use don't cover it. Editor settings sync moves keybindings and themes, not agent memory. Git doesn't help by default either, because most of this state deliberately lives outside the repo: global preferences, session logs, half-formed plans you'd never commit. So when you switch machines, the code travels -- you pushed it -- but the understanding doesn't. The assistant on the laptop has the same model, the same tools, and none of the context. It's a new hire with your repo checked out.

Mitigation 1: a handoff file in the repo

The simplest fix is the one teams have always used for shift changes: write it down. Keep a HANDOFF.md at the repo root, update it before you switch machines, commit it with the rest of your work.

## Current state
Migrating job queue to idempotency keys.
Worker side done; producer half done.

## Next
- [ ] Update producer in services/billing
- [ ] Backfill keys for in-flight jobs (plan in PR #212)

## Decisions
- Keys are ULIDs, not UUIDs -- sortable, same collision story

What works: it's versioned, it travels with the repo, and any tool can read it -- add "read HANDOFF.md before starting" to your instruction file and the agent picks it up on its own. What fails: you have to remember to write it at the exact moment you're most tired, the end of a session, and one skipped update makes the whole file suspect. It also only covers that one repo. Your global preferences and anything spanning projects stay stranded on the other machine.

Mitigation 2: paste-forward

End each session by asking the agent to write its own handoff -- "summarize where we are, what's decided, and what's next" -- then paste that into your notes app and paste it back on the other machine tomorrow. The summaries are genuinely good; models are better at this than humans at 11pm. But it's manual twice per handoff, lossy in both directions, and depends entirely on a discipline you will not maintain during a bad week. This is a decent habit, not a system.

Mitigation 3: sync the state files yourself

The infrastructure version: symlink ~/.claude into Dropbox or iCloud, or track your instruction files in a dotfiles repo. Now the files really do exist on both machines. The catches are real, though: file-sync services conflict on files that are being actively written mid-session, everything sits in plaintext on someone else's servers, symlinks behave differently across operating systems, and a blanket sync can't tell durable memory from disposable transcript noise. The dotfiles-repo variant avoids the conflicts but needs commit discipline -- congratulations, you've reinvented mitigation 1 with more plumbing.

The memoir approach: handoff as a side effect

memoir treats the handoff as something that shouldn't require remembering. As you work, session state gets captured where it happens: goals, next actions, and decisions are saved through MCP by the agent itself or explicitly by you, as plain files on your disk. At the start of the next session, memoir renders that state directly into CLAUDE.md -- a "continuing from where we left off" section listing your current goals, open next actions, and recent decisions -- so the assistant boots already briefed, without you prompting it to go read anything.

The cross-machine part: that memory syncs between your machines, encrypted on your device before it leaves. Open the laptop, and the same goals and decisions are waiting in the same place; the session starts where the desktop session stopped. To be clear about scope: memoir does not move uncommitted code -- git remains the tool for that. It moves the assistant's understanding, which is the part git was never going to carry. The project continuity use case walks through a real multi-week example, session by session.

Which one should you use?

• One repo, occasional switching: a committed HANDOFF.md is honestly fine. Cheap, visible, versioned.
• No install allowed (work machine, client hardware): paste-forward. Ritualize it -- same prompt every time.
• Several projects, switching daily: automate it. Manual handoff discipline is exactly the kind that decays, and it decays silently -- you only notice on the morning the laptop draws a blank.