The handoff.md I told Claude to stop writing

1 · The ritual

If you drive a coding agent for anything longer than a quick fix, you've felt this. An agent's context window is its whole working memory, and when the session ends, that memory ends with it. The next session starts blank. It has forgotten the architecture you walked it through, the dead end you already ruled out, the reason that one file is weird.

So I built a ritual around the gap. At the end of every session I'd have Claude write a handoff.md: a changelog of what changed and, more importantly, why I'd decided things the way I did. At the start of the next one I'd feed it back in. It worked. But it was a ritual. A step I had to remember to trigger, a file I had to shepherd, and a snapshot that was already going stale the moment I closed the terminal.

2 · What changed

claude-mem is a Claude Code plugin that gives the agent persistent memory across sessions. Install it and the ritual disappears. It captures what happens in a session on its own, then feeds the relevant pieces back into the next one automatically, before I type anything.

The practical effect is that the ritual is gone. I don't ask for a handoff at the end, I don't shepherd a file, and I don't paste anything back in at the start. The agent already knows. The first thing I see in a new session is a compact digest of prior work: the decisions, the discoveries, the things that bit us last time, sitting in context and ready to use.

3 · How it works

It's hooks plus a local database, and it's worth knowing the shape of it.

As you work, hooks record what the agent is doing. When a session ends, a Stop hook summarizes the work into observations and stores them. Each one is a small, typed record: a decision, a bugfix, a discovery. When the next session starts, a SessionStart hook selects the observations most worth remembering and injects them as that opening digest.

Two details matter. First, selection isn't just "most recent." It ranks by recency and semantic relevance, using local vector embeddings, so what you get is related to what you're actually doing. Second, it's all on your machine: a SQLite database and a vector store under ~/.claude-mem, with embeddings computed locally. Your project history doesn't leave your laptop.

4 · Two skills worth knowing

claude-mem ships a pile of skills, but two earn their place in everyday use.

learn-codebase front-loads an entire project into memory before you start. It reads every source file in full and records an observation for each. Instead of the agent rediscovering the codebase one grep at a time, the structure is already there on day one. I run it once when I pick up an unfamiliar repo.

mem-search is the other direction: asking memory a question. "Did we already solve this?" "How did we set up the deploy last time?" It searches your observation history and pulls back the specifics, the answer you'd otherwise have to reconstruct from scratch.

5 · The honest cost

The digest isn't free. It spends some of the context window up front, every session, before you've asked for anything, and like any standing context it grows as your history does. It's worth being clear-eyed about that.

But the trade is lopsided in its favor. The header on my own session today read 26 obs (9,451t read) | 190,341t work | 95% savings. That's roughly nine and a half thousand tokens of digest standing in for a hundred and ninety thousand tokens of prior work. That's the whole pitch: carry a cheap summary always, pull full detail only on demand. I'll take that every time over babysitting a handoff.md that's stale before I've closed the lid.