session-continuity
Cross-session memory for Claude Code projects. A skill Claude loads on its own, two plain-Markdown docs committed to your repo, three slash commands, and a set of session hooks that surface the right knowledge at the right moment.
Why this exists
LLMs start every session cold. Claude doesn't remember yesterday's debugging, last week's refactor, or the three-hour bug you eventually cornered. The usual fixes reach for clever infrastructure: vector databases, MCP memory servers, auto-generated notes stored in vendor-specific ways that hide the knowledge outside the repo, away from human eyes and tangled with whichever tool happens to be installed.
This plugin takes a different route: plain Markdown files, committed to git, alongside the code they describe. Two files hold the memory, three slash commands keep them honest, and a handful of hooks nudge or gate when the habit slips. That's the whole system.
The choice buys three properties most AI memory systems lack. Humans and Claude read the same files, so there's no opaque layer between you and what's remembered. Every change is a git commit, so history is auditable and every edit has an author. The storage is plain text, so it's portable: any tool that reads Markdown can use it, including future LLMs that don't exist yet.
There's a second reason, less obvious than the first: shorter Claude Code sessions are better sessions. Less accumulated context means lower cost per turn, better accuracy, and less context rot. Retrieval accuracy at large context sizes varies sharply by model, and every model degrades as the window fills. A workflow that lets you end a session and start a fresh one without losing context isn't just convenient; it's how you keep Claude sharp across a long-running project. That's what .session-continuity/SESSION_PRIMER.md and .session-continuity/LEARNINGS.md buy you: the ability to close the laptop at any point, come back cold, and have a new session up to speed in two file reads instead of rebuilding context by re-prompting.
What's in the box
| Component | What it does |
|---|
session-continuity skill | Claude loads it automatically based on the task. It teaches Claude the two-file pattern, the maintenance rules, and the decision tree for what belongs where, even before you run any command. |
.session-continuity/SESSION_PRIMER.md | The current-state snapshot. What's true about the project right now. |
.session-continuity/LEARNINGS.md | Append-only wisdom. A numbered graveyard of bugs that were painful enough to never want to rediscover. |
/session-continuity:primer | Init, refresh, or check the primer. State-dispatching. |
/session-continuity:learning | Append a new LEARNINGS entry interactively, with stable numbering. |
/session-continuity:end-session | Close-out ritual: refresh the primer, mine this session for new learnings, and print a state checklist. |
/session-continuity:spike-check | Emit the stand-in spike checklist before a spike, so it's designed to hit the real binary + auth/lifecycle/fixed-port path. |
| Session hooks | A SessionStart reminder, a non-blocking commit nudge, an action-keyed retrieval gate, a smoke-task gate for plan files, a proven-claim gate for specs/plans, an occurrence-counter gate for LEARNINGS, and a weekly freshness check. |
Nothing here writes a file behind your back. Commands stage, they never commit. Hooks remind or gate, they never edit your files.
Install
From inside Claude Code, add this repo as a plugin marketplace, then install the single plugin it hosts:
/plugin marketplace add talgolan/session-continuity
/plugin install session-continuity@session-continuity
Run /reload-plugins once the install finishes. Once the plugin is live on the official Anthropic marketplace (claude-plugins-official), you'll also be able to discover it via /plugin → Discover; until then, the two-step sequence above works on any recent Claude Code install.
The two files
Everything else is machinery around these two documents. They have opposite shapes on purpose.
.session-continuity/SESSION_PRIMER.md is the high-churn current-state snapshot: latest commits, outstanding items, test counts, working directory, workflow conventions. It's the fastest path for a fresh session to get productive. Refresh it alongside substantive commits so it always reflects what's true right now. It's meant to be overwritten freely and short enough to re-read on every session start.
.session-continuity/LEARNINGS.md is the opposite: append-only, numbered, preserved. Each entry is a bug that took 15+ minutes to diagnose, written as a recipe (the trap, the symptom, the fix, an optional diagnostic signal). Numbers are stable so cross-references never rot. New entries go to the top of their section but take the next available number.
