Claude has no memory between sessions. You spend the first few minutes of every new session re-explaining the codebase, the branch, the decisions, and what comes next.
session-continuity fixes that — automatically.
claude mcp add session-continuity npx session-continuityOpen a project in Claude Code and start working. That's it.
Claude calls five MCP tools — you do nothing.
| Tool | When | What it does |
|---|---|---|
load_session |
Session start | Restores context — status, decisions, next steps, branch |
save_session |
Session end | Captures a snapshot of what happened — status, decisions, next steps, blockers, branch. Example: save_session({ status: "Auth done", decisions: ["JWT over sessions"], next_steps: ["Add refresh tokens"], blockers: "None" }) |
pin_decision |
Mid-session | Records key architectural choices the moment they're made — persists even if save_session is never called |
list_projects |
On demand | Shows all projects with session history and last-saved timestamps |
delete_session_permanently |
On demand | Fully erases Claude's memory of a project — irreversible, no undo |
One-time setup. Claude handles load and save automatically, every session.
Every snapshot is an AI-generated briefing written to .claude/session.md:
## Session — 2026-06-05 | feat/auth
Status: JWT refresh token flow — middleware done, route in progress.
Decisions made:
- httpOnly cookies (not localStorage) — prevents XSS
- 15-min access token TTL
Next steps:
- Wire /auth/refresh route
- Add token rotation on refresh
Blockers: None- Git state — branch, status, recent commits
- Status narrative — one sentence on where things stand
- Decisions + why — key choices made this session with reasoning
- Next steps — ordered, most important first
- Pinned decisions — architectural choices that survive the rolling window
Up to 3 sessions are kept. Older sessions roll off. Pinned decisions never expire.
- Node.js ≥ 18
- Claude Code CLI
| Command | Description |
|---|---|
sc status |
Show what's currently saved for this project |
sc rotate |
Force a snapshot (e.g. before a crash or force-quit) |
sc decide "<why>" |
Pin a permanent decision that survives the rolling session window |
sc clear |
Reset session history |
save_session is a snapshot at the end of a session. pin_decision is a safety net during one — it records a choice the moment it's made so it's safe even if the session ends unexpectedly. Pinned decisions also never get pruned; they persist indefinitely, unlike session history which rolls off after 3 sessions.
Call it as soon as you reach a meaningful fork. Claude does this automatically.
Completely erases all session memory for a project — context, decisions, history. Use when the old context is actively wrong or the project has fundamentally changed direction. There is no undo. Claude will warn you before calling it.
If you just want to update what Claude knows, use save_session with fresh content instead.
Use sc decide to record architectural choices, tradeoffs, or rejected ideas that should survive past the 3-session rolling window:
sc decide "Chose Postgres over SQLite — need concurrent writes in production"
sc decide "Rejected Redis for session storage — adds ops complexity we don't need yet"Pinned decisions appear at the top of session.md and are never trimmed.
Session state is personal — add this to your project's .gitignore:
.claude/session.md
.claude/session.md.tmp
Context not loading in new sessions
Check that Claude's CLAUDE.md instructions include load_session. If you registered the MCP with claude mcp add, Claude should call it automatically on session start.
Narrative says [unavailable]
The claude CLI is not in your PATH. Check with claude --version. Without it, snapshots still capture objective git state — just no AI-generated narrative.
Session ended without a snapshot (crash / force-quit)
Run sc rotate manually to write a snapshot from the current git state.
- Rolling window: 3 sessions kept, newest first. Older sessions roll off.
- Pinned decisions: Never trimmed — use
sc decidefor anything you want to keep long-term.
Waypoint — session-continuity captures where you left off. Waypoint captures where you are in the process — across 14 guided steps from first idea to ship. Together, Claude knows both what was being worked on and where it sits in the build journey.
claude mcp add waypoint npx @waycraft/waypoint-mcp@waycraft/mcp-manager — if session-continuity drops mid-session, mcp-manager can restart it without leaving the conversation. No lost context.
claude mcp add mcp-manager npx @waycraft/mcp-managerPostToolUseincremental checkpointing (crash safety withoutsc rotate)sc history— list past session headerssc diff— show git diff since last snapshot- Configurable rolling window size
Something didn't work, felt missing, or you found a better workflow?
PolyForm Noncommercial License 1.0 — free for personal and non-commercial use.