Persistent memory & session handoff for Claude Code

A Claude Code session is a brilliant collaborator with no long-term memory. It reads files, forms a mental model, makes decisions — and then the window closes and all of it evaporates. The next session re-reads the same files, re-derives the same constraints, and re-asks questions you already answered. You pay for that re-grounding in tokens and in your own time.

The problem: every session is session zero

There are three distinct losses when a session ends:

• Memory — the durable facts Claude wrote to its memory/ directory (preferences, project conventions, gotchas) live only on one machine and aren't versioned with the code they describe.
• Reasoning — the why behind a change (what was tried, what was rejected, what's still open) never makes it into the commit message.
• Handoff — when you switch machines, hand off to a teammate, or resume next week, there's no briefing. You start by asking Claude to re-read everything.

How h5i solves it

h5i treats agent memory and reasoning as first-class, versioned artifacts stored in Git refs alongside your code — refs/h5i/memory for memory snapshots and a per-branch context workspace for reasoning. Nothing pollutes a normal git push; teammates opt in with h5i pull.

• Memory snapshots capture Claude's memory/ state at a commit, so you can diff and restore it.
• The context workspace records OBSERVE / THINK / ACT steps and milestones, and is snapshotted automatically on every h5i commit.
• Resume briefings render a structured handoff from that history — the goal, what's done, what's open.

Commands

Snapshot Claude's memory after a meaningful session, then inspect and share it:

$ h5i capture memory --agent claude
✔  Snapshot b1c2d3e  memory/ → refs/h5i/memory  (7 files, 24 KB)

$ h5i recall memory log
b1c2d3e  2026-06-02  7 files   "after auth refactor session"
9a8b7c6  2026-05-30  5 files   "initial project conventions"

$ h5i recall memory diff
+ memory/auth-token-ttl.md      (new fact: tokens now cross requests)
~ memory/MEMORY.md             (index updated)

Resume next week from a briefing instead of a cold read, and restore memory to any past commit:

$ h5i recall resume

── Resume briefing · branch auth-refactor ──────────────────
  Goal:    move token validation behind a shared cache
  Done:    cache layer + 42 passing tests (commit a3f8c12)
  Open:    expiry edge case at cache boundary — see THINK note
  Memory:  3 project facts, last snapshot b1c2d3e

$ h5i recall memory restore 9a8b7c6   # roll memory back if needed

Worked example: a clean handoff

You finish a session that refactored authentication. Before closing, you snapshot memory and let the context workspace checkpoint. Tomorrow — or a teammate on another machine — pulls the h5i refs and gets the full picture without re-reading the diff:

$ h5i pull                 # brings notes, memory, context, msg
$ h5i recall resume auth-refactor
  …goal, done, open, and the rejected approaches — ready to continue.

Frequently asked questions

Does this give Claude Code memory across sessions automatically?

h5i stores memory snapshots and a reasoning workspace in Git refs. With the Claude Code hooks installed (h5i hook setup), prompts and reasoning traces are captured automatically; you snapshot the memory directory with h5i capture memory at the end of a notable session, and restore or resume it later.

Where is the memory stored — does it get pushed to GitHub?

Memory lives in refs/h5i/memory, not in your working tree. A plain git push ignores it, so it never clutters a normal remote. Run h5i push (or h5i share memory push) to share it, and h5i pull to receive it.

How is this different from Claude Code's built-in memory files?

Claude's memory/ directory lives on one machine and isn't versioned with your code. h5i snapshots it into Git so you can diff what Claude learned over time, restore an earlier state, and hand it to a teammate or another machine.

What does a session handoff actually contain?

h5i recall resume renders the branch goal, what was completed (with commit SHAs), what's still open, the approaches that were considered and rejected, and the latest memory snapshot — a structured briefing rather than a chat transcript.

Can I roll back memory if Claude learned something wrong?

Yes. h5i recall memory log lists every snapshot and h5i recall memory restore rolls the memory directory back to that state, the same way you'd reset code to a past commit.