session-continuity

Cross-session memory for Claude Code projects. A skill Claude loads on its own, four plain-Markdown docs committed to your repo plus GitHub Issues for the work queue, nine slash commands — four of which cost no model calls in the common case, a hook intercepts and answers them directly, with a one-model-call fallback if it doesn't fire — 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, plus GitHub Issues labeled backlog for the queue. Four files hold the durable memory, nine slash commands keep them honest — four of them (backlog, learnings, help, update) answered at zero model calls by a hook, falling back to one call apiece if the hook doesn't fire — 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, .session-continuity/PROJECT_CONTEXT.md, .session-continuity/ROADMAP.md, and .session-continuity/LEARNINGS.md buy you, plus GitHub Issues labeled backlog for deferred work: the ability to close the laptop at any point, come back cold, and have a new session up to speed without 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 four-file pattern plus the GitHub Issues queue, 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/PROJECT_CONTEXT.md	Stable repo context — layout, conventions, module table. Changes rarely, only when the project's shape itself changes.
GitHub Issues (backlog label)	Explicitly deferred follow-ups and decisions. Identity is #N. Title + 1-3 sentence cap. Close once the code shows it shipped.
.session-continuity/ROADMAP.md	Strategic direction — Now/Next/Later. Freeform, no numbering, rewritten wholesale as direction changes.
.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, split, 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:doctor	Read-only diagnostic: is the install actually wired up — hooks registered, four files present and not stale, GitHub backlog reachable, plugin root resolved and not a stale cache, gate scripts executable.
/session-continuity:backlog	Render open GitHub Issues labeled backlog. Zero model calls when the prompt-intercept hook fires, one call as fallback.
/session-continuity:learnings	Render LEARNINGS.md's entries. Zero model calls when the prompt-intercept hook fires, one call as fallback.
/session-continuity:update	Print the commands to pull and activate this plugin's latest published version.
/session-continuity:help	Explain what the plugin does, why, and what each of the four files plus the GitHub queue is for.
/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, an evidence-preservation gate for smoke design, a flaky-claim gate, a multi-backend-parity gate, 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 the talgolan catalog as a plugin marketplace, then install this plugin from it:

/plugin marketplace add talgolan/claude-plugins
/plugin install session-continuity@talgolan

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 four files, plus the queue

Everything else is machinery around these documents. Each has a different update contract.

.session-continuity/SESSION_PRIMER.md is the high-churn current-state snapshot: latest commits, working state. 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/PROJECT_CONTEXT.md is stable reference material: repo layout, module table, workflow conventions, test expectations, "where to look for what." It changes rarely — only when the project's shape itself changes — so a fresh session skims it once and doesn't need to re-check it every turn.

GitHub Issues labeled backlog are the tactical queue: explicitly deferred decisions and follow-ups, not current state. Identity is the issue number #N. Close an issue once the code shows it shipped. Each item is capped at a title plus 1-3 sentences; anything longer belongs in a linked spec, not inlined in the issue body. Origin must be github.com; /session-continuity:doctor warns if gh or auth is missing.

.session-continuity/ROADMAP.md is strategic direction, independent of the tactical queue — Now/Next/Later, freeform. No numbering, no permanence rules, no length cap; rewrite it wholesale as direction changes rather than editing around old entries.

.session-continuity/LEARNINGS.md is the opposite of the rest: 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.

The four files ship as templates. The backlog does not — it lives on GitHub.

The commands

/session-continuity:primer

One command, six behaviors, dispatched on the repo's current state:

• No primer yet → copies the templates into .session-continuity/, fills every placeholder it can derive (project name, latest commits, working directory, test command), asks you for the rest, files named follow-ups as GitHub Issues labeled backlog when origin is github.com, and stages four files. Any field you skip becomes TBD rather than a leftover {{PLACEHOLDER}}.
• Primer exists but not yet split → partitions its stable sections (layout, conventions, module table, "where to look for what") into a new .session-continuity/PROJECT_CONTEXT.md, leaving the primer with only the volatile shortlist. One-time content move, no file move.
• Primer has an inline Outstanding items section, or a leftover OUTSTANDING_ITEMS.md / BACKLOG.md → migrates that markdown queue to GitHub Issues labeled backlog when origin is github.com, then deletes the file. Without a github.com origin, the file is left as a fossil and doctor warns.
• Primer exists but drifted → regenerates the git log --oneline -5 block, re-runs the primer's test commands (retrying flaky suites up to three times so a single bad sample doesn't cry wolf), surfaces every commit since the last refresh as a candidate, and prompts you for backlog changes before staging.
• Primer current → reports a four-line status (HEAD, last refresh, backlog count, learnings count) and exits without touching anything.

Drift is detected by diffing the stored git log block against reality, not by file mtime, because formatters and save-on-blur bump mtime without changing content.

/session-continuity:learning

Appends a properly formatted entry. It prompts for the recipe fields, lets you pick or create a section, and computes the next number by taking the true maximum across all existing entries (not "one after the most recent," which breaks when an old entry was edited last). Before writing, it scans for duplicate numbers and refuses to append on top of a corrupt file. Entries can carry an optional Trigger: line that makes them fire before a matching action later (see hooks below).

/session-continuity:end-session

The close-out ritual, bounded to at most two prompts in the common case:

1. Refresh the primer, but only if it actually drifted. If the git log block already matches reality, this step checks whether any backlog item now looks resolved (verified against actual code, never guessed) — if so, it offers a lightweight prompt to close it; otherwise it's a silent no-op.
2. Mine the session for learnings. It reads the session transcript (falling back to the live context window when the transcript isn't reachable) and runs four deterministic detectors: a retry burst (the same command run three or more times), a revert/reset (hard reset, checkout, revert, or rm -rf on a tracked file), an error recurrence (the same normalized error three or more times across 15+ minutes), and a fix burst (a fix: commit preceded by a long investigation). Candidates are pre-drafted into full LEARNINGS entries and presented in one batch for a single confirm.
3. Print a state checklist. Staged, unstaged, untracked, and unpushed are each enumerated file by file, with a suggested commit message and a terminal sign-off so you know the ritual is done.

It never commits and never pushes. The checklist flags what's outstanding; you decide.

/session-continuity:doctor

Read-only, zero-arg diagnostic: is the install actually wired up? Five ✓/⚠️ rows — install mode (plugin vs. vendored), hooks registered, all five .session-continuity/ files present with the primer's staleness re-checked, CLAUDE_PLUGIN_ROOT resolves and isn't a stale plugin-cache dir, gate scripts executable. Never mutates anything; every fix is a printed command you run yourself.

/session-continuity:spike-check

Emits a five-question stand-in checklist before a spike is built, so the spike is designed to exercise the real binary and the real auth/lifecycle/fixed-port path rather than a hand-rolled stand-in that passes cleanly and proves nothing. It is the proactive complement to the proven gate: answers 2 and 5 become the Real path: and Stubbed: fields the proven gate requires at claim-time. Pass an optional one-line spike description to frame each question.

/session-continuity:backlog

Zero-arg, read-only: lists open GitHub Issues labeled backlog as N. #NUMBER Title. A UserPromptSubmit hook intercepts the matching natural-language and slash-command forms and answers directly at zero model calls; this command's own body is the one-call fallback for when the hook doesn't fire.

/session-continuity:learnings

Zero-arg, read-only: renders .session-continuity/LEARNINGS.md's entries, grouped by section, in their existing numbering. Same hook, same zero-turn-in-the-common-case, one-call-as-fallback shape as /session-continuity:backlog.

/session-continuity:update

Prints the three commands to pull this plugin's latest published version and activate it in the current session — nothing more. There's no tool that lets the assistant invoke /plugin or /reload-plugins on your behalf, so this command doesn't try; it's a static reminder, not automation.

/session-continuity:help

Zero-arg, read-only: explains what the plugin is for, why it exists, and what each of the four .session-continuity/ files plus the GitHub queue is responsible for, plus a live command list built from every command's own frontmatter description — not hand-duplicated prose, so the list can't drift out of sync with the commands themselves.

The hooks

The hooks are bash scripts wired through hooks/hooks.json. They split into two philosophies.

React after the fact:

• SessionStart reminder points a fresh session at the primer before it touches anything, and prints a quick freshness status line.
• Commit nudge (PreToolUse, scoped to Bash(git commit *)) fires only on real git commit calls. If code is staged but the primer isn't, it injects a non-blocking reminder to consider refreshing the primer in the same commit.

Fire before the action:

• Action-keyed retrieval (learnings-surface, PreToolUse on Bash/Write/Edit) is the mechanism that turns LEARNINGS from a read-after-symptom file into a read-before-action gate. When a LEARNINGS entry carries a Trigger: <tool> /<regex>/ line and the command you're about to run (or the file you're about to write) matches that regex, the hook names the relevant entry so you read it before repeating the mistake. Entries without a trigger never fire, so there's zero cost to omitting one.
• Smoke gate (smoke-gate, PreToolUse on Write/Edit, plan files only) blocks writing a plan that touches binary/engine/container work but marks its smoke task optional or omits it entirely. Override with an explicit Smoke: N/A — <reason> line. It enforces mechanically what a passive note kept failing to enforce.
• Proven gate (proven-gate, PreToolUse on Write/Edit, spec/plan files only) blocks writing a spec or plan that makes a "proven / verified / spike conclusive" claim unless the same content carries Real path: + Stubbed: fields naming what actually ran versus what was a stand-in. Claim-words match on word boundaries (unproven/improven/confirmed do not trigger). Override with Proven-gate: N/A — <reason> for quoting, a glossary, or a doc about the gate.
• Occurrence gate (occurrence-gate, PreToolUse on Write/Edit, LEARNINGS.md only) blocks a LEARNINGS entry that records the 2nd-or-later occurrence of a mistake-class (Occurrence count: N of M, N ≥ 2) unless the same content names an end-state Invariant: line — the thing that, enforced at the reconciler/entry gate, makes the whole class impossible rather than patching one more trigger. A first occurrence (or no count) never fires. Override with Occurrence-gate: N/A — <reason>.
• Evidence gate (evidence-gate, PreToolUse on Write/Edit, spec/plan files only) blocks a spec/plan's smoke-design prose if it tears down a test subject without first saying the failure diagnostic is captured, or polls for success only instead of watching for both success and failure signals. Override with Evidence-gate: N/A — <reason>.
• Flaky gate (flaky-gate, PreToolUse on git commit and on Write/Edit to LEARNINGS.md) blocks a commit message or LEARNINGS entry that calls a failure "flaky" / "transient" / "CDN blip" without naming the deterministic mechanism behind it (a race, shared state, an environment dependency). Override with Flaky-gate: N/A — <reason>.
• Backend-parity gate (backend-parity-gate, PreToolUse on Write/Edit, plan files only) blocks a plan that frames its smoke coverage as multi-backend (mentions "backend"/"backends") but names only one concrete backend, instead of naming a second for parity coverage. Only fires when the plan text itself uses the word "backend" — single-backend projects are never touched. Override with Backend-parity: N/A — <reason>.

Stay fresh:

• Weekly version check makes one unauthenticated GitHub API call per machine per seven days and nudges you inside Claude when a new release ships. Opt out with SESSION_CONTINUITY_SKIP_UPDATE_CHECK=1.
• Performance logging times every hook invocation and the heavier operations inside /session-continuity:primer and /session-continuity:end-session, appending JSONL lines to .session-continuity/performance.log (auto-gitignored). Read it directly — jq, grep, bat — there's no summary command yet.

Usage

New project:

/session-continuity:primer

Detects no primer exists, copies templates into .session-continuity/, fills derivable placeholders, asks you for the rest, and stages four files.

Before a commit:

/session-continuity:primer

Detects drift, regenerates the git log block, prompts for backlog updates, and stages the refreshed primer. Commit it alongside your substantive change, not in a primer-only commit.

After a painful bug (15+ min to diagnose):

/session-continuity:learning

Prompts for trap, symptom, fix, and diagnostic signal. Appends the entry at the top of the section you pick with the next sequential number.

Ending a work session:

/session-continuity:end-session

Refreshes the primer, proposes LEARNINGS candidates drawn from this session, and prints a checklist so nothing is forgotten before you close the laptop. Stages changes; does not commit.

Scope note. End-session's reflection sees only the current session. For a bug you remember from yesterday or one that lived in a different Claude instance (a subagent or parallel worktree), use /session-continuity:learning directly.

Picking up an existing project:

The SessionStart hook reminds Claude to read .session-continuity/SESSION_PRIMER.md first. Follow its "First things first" list before touching anything.

What goes where

Observation	Where
"The latest commit is X"	.session-continuity/SESSION_PRIMER.md → Current state
"We should follow up on X"	GitHub Issue labeled backlog
"Where is this headed next quarter"	.session-continuity/ROADMAP.md → Now/Next/Later
"How is this repo laid out"	.session-continuity/PROJECT_CONTEXT.md → Repo layout
"What are our workflow conventions"	.session-continuity/PROJECT_CONTEXT.md → Workflow conventions
"Bun replaces the CA trust store"	.session-continuity/LEARNINGS.md → new numbered entry
"Always use Bun"	CLAUDE.md (durable project convention)
"Last session tried X and rejected it"	.session-continuity/LEARNINGS.md → Anti-patterns

Do not put in these files: secrets (ever — use <redacted>), information trivially rederivable from code, narrative fluff.

Why four files plus GitHub Issues

Most memory systems lump everything together: notes, decisions, observations, bug reports, all blended in a searchable soup. That fails in a specific way for software projects, because current state, stable context, deferred decisions, strategic direction, and accumulated wisdom have different update contracts.

The primer is high-churn. Yesterday's commit is already out of date; next week's priorities will look different again. It needs to be overwritten freely, refreshed with every substantive change, and short enough to re-read on every session start. A primer that accumulates forever becomes a scroll tomb.

PROJECT_CONTEXT is low-churn. Repo layout, module boundaries, and workflow conventions don't change every commit — they change when the project's shape itself changes. It's still overwritten (not append-only) when it does change, but a fresh session only needs to skim it once, not re-check it every turn like the primer.

LEARNINGS is the outlier: append-only, numbered, preserved, and local. Each entry is hard-won knowledge that would cost the same hours again if lost, and the fire-before-action hook greps it on every tool call. That path cannot hit the network.

The backlog is a queue, so it lives in GitHub Issues (label backlog). Close semantics, comments, PR links, and stable #N identity come with that tracker. A leftover BACKLOG.md is a fossil, not a fallback.

ROADMAP is the least ceremonious: no numbering, no permanence, no length cap. It exists because "what's the tactical backlog" and "what's the strategic direction" are different questions with different lifespans.

Blending any of these forces bad tradeoffs. Current-state notes drown stable context or accumulated wisdom; wisdom gets edited away when someone trims "stale" entries. Keeping them in separate stores with separate update contracts means the primer answers "what is true right now," PROJECT_CONTEXT answers "what is true about this project generally," GitHub Issues answer "what have we deliberately deferred," ROADMAP answers "where is this headed," and LEARNINGS answers "what should I know to avoid rediscovering pain."

What it is not

Understanding what this plugin deliberately avoids is as useful as understanding what it does.

Not automatic. The slash commands require you to invoke them. The hooks nudge or gate; they don't write files themselves. Automatic memory capture sounds appealing but has a predictable failure mode: noise, contradictions, and stale state that Claude confidently believes is current. A memory system is only useful if its contents can be trusted, and trust comes from deliberate capture.

Not a framework. There's no extension API, no plugin architecture, no abstraction layer waiting for you to subclass it. The surface is one skill, nine commands, and a handful of hooks, and that's the whole product. The surface stays deliberately small — a new command needs a concrete failure mode behind it (like /session-continuity:doctor's "a mechanism silently never fired and nobody could ask why"), not speculative convenience. PRs that add surface without one will be declined.

Not a replacement for CLAUDE.md, vector search, or MCP memory servers. Each solves a different problem. CLAUDE.md is for durable project conventions ("always use Bun, never commit to main"). Vector search is for semantic retrieval across large unstructured corpora. MCP memory servers are for cross-project context that needs rich querying. This plugin is for the questions above, in a single project's repo, with plain text in git for durable memory and GitHub Issues for the queue. When one of the other tools fits your need better, use it instead.

Not an LLM-only tool. Every file is human-readable and human-editable. You can open .session-continuity/LEARNINGS.md in any editor, add an entry by hand, and Claude will see it on the next session. The slash commands are conveniences, not gates.

Team-wide use

The four in-repo files are checked-in artifacts, not gitignored. Commit them under .session-continuity/ and the whole team benefits:

• Add a line to the project's CLAUDE.md pointing every session at the primer and the maintenance rules.
• LEARNINGS doubles as a living post-mortem log for human teammates, not just Claude.
• The primer is a ready-made onboarding handoff for anyone joining the project.

Platform notes

Hooks are bash scripts and rely on git on PATH. On Windows, use Git Bash or WSL. Native PowerShell support is not planned.

Updating

To pick up newer versions, refresh the marketplace and reload:

/plugin marketplace update talgolan
/reload-plugins

The weekly freshness check in SessionStart will nudge you inside Claude when a new GitHub release ships. Opt out with SESSION_CONTINUITY_SKIP_UPDATE_CHECK=1.

Contributing

Issues and PRs welcome at github.com/talgolan/session-continuity. See CONTRIBUTING.md for the full guide: scope policy, local development, authoring conventions for commands and hooks, and the release process. TL;DR: this plugin ships a five-file pattern, not a framework. PRs that fit the existing shape will move quickly; PRs that expand scope will be declined or redirected.

Privacy

See PRIVACY.md. Short version: nothing leaves your machine except one weekly, unauthenticated GitHub API call for version checks, which you can disable with SESSION_CONTINUITY_SKIP_UPDATE_CHECK=1.

License

MIT — see LICENSE.