Skip to content

README.md

Latest commit

 

History

History
175 lines (107 loc) · 5.82 KB

README.md

File metadata and controls

175 lines (107 loc) · 5.82 KB

session-continuity

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-continuity

Open a project in Claude Code and start working. That's it.

How it works

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.

What's captured

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.

Requirements

CLI (setup and management)

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

pin_decision vs save_session

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.

delete_session_permanently

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.

Pinning decisions

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.

.gitignore recommendation

Session state is personal — add this to your project's .gitignore:

.claude/session.md
.claude/session.md.tmp

Troubleshooting

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.

How sessions are bounded

  • Rolling window: 3 sessions kept, newest first. Older sessions roll off.
  • Pinned decisions: Never trimmed — use sc decide for anything you want to keep long-term.

Pairs with

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-manager

Roadmap

  • PostToolUse incremental checkpointing (crash safety without sc rotate)
  • sc history — list past session headers
  • sc diff — show git diff since last snapshot
  • Configurable rolling window size

Feedback & Discussion

Something didn't work, felt missing, or you found a better workflow?

→ GitHub Discussions

License

PolyForm Noncommercial License 1.0 — free for personal and non-commercial use.