Memory / Handoff
Zero-infra file memory the next session picks up cold — persists decisions, constraints and gotchas, not what the repo already records.
v1.0.0 · ~518 tokens · ⬇ 0 · Updated July 6, 2026
What it does
File-based project memory with no service or webhook: persists what isn't recoverable from code/git (decisions + why, non-obvious constraints, in-flight state, hard-won gotchas), one fact per note with a cheap index. Resume protocol verifies notes against current code before acting. Refuses to store what a grep answers, or secrets.
Example uses
Write an end-of-session handoff
You are stopping mid-feature and tomorrow's session should not have to re-derive everything you learned today.
Wrap up this session with a handoff file: we shipped the Stripe webhook handler, next up is retry logic for failed charges, we're blocked on the finance team for the refund policy, and we chose idempotency keys over a dedupe table because retries come from Stripe's side. Include the gotcha that test-mode webhooks fire twice.Hand off a branch cold
You are leaving on vacation and a teammate picks up your branch with zero shared context.
Write a handoff note for the teammate taking over the search-migration branch: what's done, the exact next action, what's blocked and on whom, plus the two gotchas we hit — Elasticsearch mappings can't be changed in place, and the staging index is full of stale test data. Convert every relative date like 'next Tuesday' to the actual date.Resume after two weeks away
You open the project after a break and cannot remember where you left off or why.
Read the handoff notes in docs/handoff/ and get me back up to speed: what was done, what's next in priority order, and what's still blocked. Before we act on anything, verify the files and branches the notes mention still exist — the notes reflect when they were written, not now.Install
# 1. Create the skill folder in your Claude setup mkdir -p ~/.claude/skills/memory-handoff # 2. Download SKILL.md into it (or move the file you just downloaded) # → ~/.claude/skills/memory-handoff/SKILL.md # 3. Claude Code auto-discovers it on next launch.
Inside the skill
---
name: memory-handoff
description: Persist project context between sessions with zero infrastructure — a file-based memory the next session (or agent) can pick up cold. Use when wrapping a session, handing off work, or asked "save context", "remember this", "write a handoff", "where was I". No database, no webhook.
---
# Memory / Handoff (zero-infra)
Give the next session (yours or a teammate's) what it needs to continue without re-deriving
everything. Plain files in the repo — no service, no daemon, loaded on demand only.
## What to persist (and what NOT)
Persist what is NOT recoverable from the code or git:
- **Decisions + the WHY** ("chose X over Y because Z") — the reasoning dies otherwise.
- **Non-obvious constraints** (this API rate-limits at N; that field is legacy; don't touch W).
- **In-flight state**: what's done, what's next, what's blocked and on what.
- **Gotchas discovered the hard way** (the bug that ate an hour, the flaky test's real cause).
Do NOT persist what the repo already records: file structure, what a function does, commit
history, anything a `grep` answers. Duplicated memory rots and misleads.
## Format (one fact per file, or one running handoff)
```
# Handoff — <date>
## Done
- <shipped, with where>
## Next (priority order)
- <the very next action, concrete>
## Blocked
- <what + on whom/what>
## Decisions
- <decision> — because <why>
## Gotchas
- <trap> → <how to avoid>
```
Keep an index file (one line per note) so recall is cheap. Convert relative dates to
absolute ("tomorrow" → the date). Link related notes by name.
## On resume (read this first)
Load the index → read the handoff → verify anything it names still exists in the code
before acting on it (memory reflects when it was written, not now). Then continue.
## Rules
- One fact per note; a note that says five things is impossible to update or trust.
- Update the note when the fact changes; delete it when it's wrong. Never let stale memory accumulate.
- Never store secrets in memory files (they're in the repo/history — see secrets-guardian).
Changelog
- v1.0.02026-07-03Initial clean-room write.
Frequently asked questions
Is Memory / Handoff free?
Yes. Memory / Handoff is free to download and MIT-licensed.
Where do I install Memory / Handoff?
Place the SKILL.md file in ~/.claude/skills/memory-handoff/ and Claude Code auto-discovers it on next launch.
How many tokens does Memory / Handoff use?
About 518 tokens — it is designed to be token-lean.
We're developers and SaaS builders who use these tools daily in production. Every review comes from hands-on experience building real products — DealPropFirm, ThePlanetIndicator, PropFirmsCodes, and many more. We don't just review tools — we build and ship with them every day.
Written and tested by developers who build with these tools daily.