Session Relay 🏃‍♂️

Seamless session continuity — pick up exactly where you left off.

Core Principle

The user should never feel they lost progress when a session ends. Every new session should feel like waking up from a nap, not amnesia.

Phase 0: Session History Inheritance (First Thing on Startup)

On every new session startup, before doing anything else, pull recent conversation context so you're not starting blind.

Step 1: Fetch recent sessions

CODEBLOCK0

Step 2: Pull the last 3 sessions' conversation tail

For each of the 3 most recent sessions (excluding current), grab the final conversation turns:

CODEBLOCK1

Focus on the last ~10 user/assistant exchanges per session. Skip tool calls — you want the actual conversation flow.

Step 3: Save raw conversation tails to snapshot

Write the verbatim last 3 rounds (user message + assistant reply = 1 round) from each session into the snapshot file. This is the key difference from v1.1 — not a summary, but actual conversation text so you can see exactly what was said:

CODEBLOCK2

Step 4: Use conversation context naturally

Now you've literally "seen" what was discussed. When the user talks to you:

• - Reference the actual conversation: "上次你说希望把对话接续过来，我更新了 session-relay 的方案"
• Don't re-explain things already decided: If the last session already debated and resolved something, don't reopen it
• Continue mid-thought if appropriate: If the last message was about task X, you can proactively pick up task X

Rules:

• - Store verbatim conversation text, not summaries — summaries lose the "feel"
• 3 rounds per session max (6 messages) — enough for context, not too much for token budget
• If sessions are very old (> 24h), still store but note the time gap
• If the user's first message already states what they want, weave context in naturally
• Never block the user — if sessions_list/sessions_history fails, proceed normally
• Security: Strip any API keys/tokens that appear in conversation before saving

Phase 1: Context Monitoring

After completing significant work (file edits, multi-step tasks, key decisions), check context usage via session_status.

Begin incremental saves at 60% so the snapshot stays fresh throughout the session.

Phase 2: Rich Snapshots

Snapshot file: INLINECODE4

What makes a good snapshot (vs a bad one)

❌ Bad — too abstract:
CODEBLOCK3

✅ Good — actionable detail:
CODEBLOCK4

Snapshot Template

CODEBLOCK5

Snapshot Rules

1. 1. Be concrete: paths, commands, URLs, error messages — not summaries of summaries
2. Prioritize "In Progress": The most valuable section. What was the agent literally doing?
3. No secrets: Never store API keys, tokens, or passwords
4. Size target: 500-2000 words. If over, cut from Completed first (it's in the daily log anyway)
5. Overwrite, don't append: Only latest snapshot matters. But sync key items to daily log too
6. Include reproduction commands: If a task involves running something, include the exact command

Phase 3: Session Restore (Enhanced)

On new session startup:

1. 1. Run Phase 0 first — pull conversation tails from recent sessions
2. Then read existing memory/relay-snapshot.md — merge Phase 0 conversation tails with any saved snapshot data
3. You now have two layers:

1. 4. Respond as if you remember — don't announce "I restored context". Just naturally continue.
2. If the user says "fresh start", silently archive the snapshot

Archive

When snapshot is consumed or user starts fresh:

# scripts/archive-snapshot.sh handles this
mkdir -p memory/relay-archive
mv memory/relay-snapshot.md memory/relay-archive/YYYY-MM-DD-HHMMSS.md

Phase 4: HEARTBEAT Integration

If the workspace uses HEARTBEAT.md for periodic checks:

• - When context is in 🟠 Hot zone (75-85%), add a line to HEARTBEAT.md:

  # [AUTO] Session relay: context high, snapshot saved. Remove this line after reviewing.
  

• - This ensures even if the session dies unexpectedly, the next heartbeat will notice

Remove the HEARTBEAT line after a successful restore in the next session.

Phase 5: Daily Log Sync

Every time a snapshot is saved, also append a summary to memory/YYYY-MM-DD.md:

CODEBLOCK8

This ensures the daily log captures progress even if the snapshot gets overwritten later.

Critical Alert (> 85%)

When context exceeds 85%, append to EVERY reply:

CODEBLOCK9

Edge Cases

• - sessions_list/sessions_history unavailable → skip Phase 0, fall back to snapshot file only
• INLINECODE10 unavailable → skip monitoring, don't block user
• Snapshot corrupted/empty → treat as no snapshot, rely on session history
• User says "don't restore" / "fresh start" → archive and proceed clean
• Multiple compactions in one session → snapshot survives (it's a file, not context)
• Very short session (< 5 turns, no real work) → don't create a snapshot
• All recent sessions are from other users (group chat) → filter to main sessions only
• Session history returns tool-heavy turns → skip tool details, extract user intent + final outcome

What This Skill Cannot Fix

Be honest with users: session-relay is a best-effort bridge, not magic. Limitations:

• - Detailed reasoning chains are lost after compaction
• Session history API may not return full conversations
• The "feel" of a conversation can't be fully serialized
• If the agent doesn't run session_status, monitoring thresholds won't trigger

The goal is: 80% continuity is infinitely better than 0%. Perfect continuity requires platform-level support.