Claude Session Continuity Kit

A small, project-agnostic kit for keeping a long-running Claude Code project coherent across sessions — so a new session starts knowing what's true, and the effort you spent last time isn't lost or silently contradicted.

It is one shared close-session skill plus a drift-detection kit. You install it once at the user level and adopt it per project with two small config files. No forked scripts.

---

The problem this solves

If you've built anything with an AI assistant over more than a handful of sessions, you've felt this: each new conversation starts cold. You re-explain the project, the assistant makes a decision you already made (differently), or it "remembers" something that stopped being true three sessions ago. Time and momentum leak away at every boundary.

Most people reach for more memory — a bigger context file, more notes. That helps, but it misses the real failure. The real failure is drift:

Drift = the gap between what is actually true about the project now, and what a fresh session believes is true when it starts.

Drift accumulates quietly. You edit a file outside a session. A session forgets to update a note. The context file describes a world that later work has changed. None of these are visible in any single session — and after enough of them, the assistant is confidently operating on false beliefs.

More memory doesn't fix drift. A memory you can trust hasn't drifted does. That's what this kit is: not a bigger memory, but a memory with an integrity check.

The pattern (the transferable part)

Four ideas do the work. They're worth understanding even if you never use this exact code.

1. Bucket A vs Bucket B. Split your context files in two. Bucket A (the context file + the handoff) is always rewritten at the end of every session — it's the session record. Bucket B (everything else the project tracks: specs, configs, reference docs, memory) is conditional — you only touch it when it actually changed. This keeps closes fast and keeps the always-loaded context small.

2. A ledger, not a memory. Bucket B's read-status lives in one file — bucket_b_ledger.txt — with a line per tracked file: path | STATUS | date | note. One copy, ever. (Two copies of the same roster will drift, which is the whole thing you're trying to prevent.)

3. Two staleness valves. The ledger is only useful if a stale entry gets caught:

   • Valve 1 (mtime): if a file's timestamp on disk is newer than its ledger date, it was edited outside a session — the drift event itself. Re-read it.
   • Valve 2 (calendar): if a file hasn't been reviewed in longer than its interval, re-read it once, then stamp it. Long-stable files get long intervals so the alarm doesn't cry wolf.

4. Fail closed, and meter it. The check is built so it can never print "clean" because it failed to look — a missing ledger, a bad date, a duplicate line all exit non-zero. And every startup appends one row to a log, because drift is an accumulation you can only see over time: a single clean session proves nothing; the trend does.

The most important word is honest. The ledger date means "known-reviewed-through" — the date someone actually confirmed the file. You advance it only when a file really changed or was really reviewed. Stamping a date you didn't earn is the one move that quietly breaks everything, so the tooling refuses to advance a date without a recorded reason.

What's in here

skills/close-session/SKILL.md   The shared session-close protocol (project-agnostic).
                                Reads each project's close_config.md for its own values.
ops/startup_read_check.py       The ledger + the two valves + --ack/--defer/--self-test/--log.
                                Fail-closed. Run by each project's SessionStart hook.
ops/drift_report.py             Reads the startup log; writes a plain-English drift report.
ops/bucket_b_ledger.template.txt  Ledger format + a place to seed your tracked files.
templates/close_config.example.md The per-project values the shared skill reads.
examples/                       A worked example for a fictional project.

Install

Once, at the user level (so every project shares one copy):

cp -r skills/close-session ~/.claude/skills/close-session
cp -r ops                  ~/.claude/ops

Per project (writes two small files + one hook line — no forked scripts):

1. Seed a ledger. Copy ops/bucket_b_ledger.template.txt to <project>/_handoff/bucket_b_ledger.txt and add one line per Bucket-B file you track:

   <repo-relative path> | UNCHANGED | 2026-01-15 | one-line what-this-is
   

2. Add a close config. Copy templates/close_config.example.md to <project>/_handoff/close_config.md and fill in your values (push policy, Bucket-A list, size caps, the drift-check command).

3. Wire the SessionStart hook. In <project>/.claude/settings.json, run the check at startup (its output is surfaced to the session):

   CLOSE_PROJECT_ROOT="<absolute project path>" python "$HOME/.claude/ops/startup_read_check.py" --log 2>&1 || true
   

4. Verify: from the project, python ~/.claude/ops/startup_read_check.py --self-test should print SELF-TEST PASSED, and a plain run should read your ledger cleanly.

To close a session, tell Claude to "close session" — the shared skill runs the protocol against that project's close_config.md.

Notes on fit

• Not every project needs the full kit. A document/deadline project (immigration paperwork, say) doesn't have "code drift" — its failure mode is a missed date. There, the same idea (a fail-loud check at startup, a single source of truth) is better served by a deadline monitor than by this ledger. Match the instrument to the real failure mode. Set drift_check: none in the config and lean on the close protocol alone.
• Push policy is respected. A privacy-sensitive repo can set push_policy: local-only and the close skill will commit but never push it.
• This is a niche tool for serious, long-running projects. If you close a project in one or two sessions, you don't need this. It earns its keep somewhere around session ten, when you can no longer hold the whole project in your head — or the assistant's.

Origin & credit

Built by Thinker1951 out of necessity across several real, long-running Claude Code projects (a valuation platform, a couple of small businesses, an immigration file) — the kind that run for dozens of sessions and where lost context has a real cost. Assembled by a self-taught builder with Claude's help; the discipline came from repeatedly losing work and refusing to lose more. Shared in case it saves someone else the same lesson.

Let's connect. If you're building something serious and long-running with an AI assistant, I'd genuinely like to hear how you handle continuity — what works, what doesn't, what this misses. Open an Issue or start a Discussion on this repo, or reach me through my GitHub profile. If it helps you, or you improve it, a note back is welcome.

License

MIT — see LICENSE. Use it, fork it, adapt it.