Session Relay

Automatic session continuity and task handoff across context window boundaries. Use when: (1) context token usage exceeds 70% of the model's context window,...

Security Scan

The skill's stated purpose (persisting recent conversation to allow session handoff) matches most of its instructions, but it asks the agent to save verbatim conversation text and reproduce commands/paths to disk and includes a detected prompt-injection pattern — these behaviors increase the risk of secret leakage and injection attacks and warrant caution.

Purpose & Capability

The skill's name and description align with its actions: it pulls recent session history and writes snapshots for continuity. The included archive script and snapshot format reference are coherent with a relay/snapshot feature. No unrelated credentials, binaries, or install steps are requested.

Instruction Scope

The SKILL.md instructs the agent to fetch verbatim conversation tails (user+assistant) and to save reproduction commands, file paths, URLs, and error messages into workspace/memory/relay-snapshot.md. Although it states 'No secrets' and 'Strip any API keys/tokens that appear in conversation,' that sanitization is left to the agent and cannot be enforced. Writing verbatim history and commands to disk increases the risk of accidental secret capture and exfiltration. It also mandates performing the fetch 'before doing anything else' on startup, which broadens the action scope and could run automatically if the agent is allowed to invoke the skill.

Install Mechanism

No install spec (instruction-only) and a small, transparent shell script for archiving snapshots. Nothing is downloaded from external URLs and no archives are extracted. Low install risk.

Credentials

The skill requests no environment variables, credentials, or external config paths. That is proportionate to its purpose. However, its behavior of capturing verbatim messages and reproduction commands means it may inadvertently capture secrets present in conversation content despite claiming not to.

Persistence & Privilege

always:false (not force-included). The skill prescribes automatic behavior at session startup (fetch history before doing anything else) which implies it expects autonomous invocation; that is allowed by default but increases privacy exposure if the agent invokes it without explicit user consent. The skill writes snapshot files into {workspace}/memory and archives them — this is normal for persistence but means local disk storage must be trusted and protected.

Scan Findings in Context

[unicode-control-chars] unexpected: The pre-scan detected Unicode control characters in SKILL.md. These are not needed for a session-relay feature and can be used for prompt-injection or to alter how downstream processors interpret the instructions. This is suspicious and should be investigated or removed before trusting the skill.

What to consider before installing

This skill does what it says (pulls recent sessions and saves snapshots) but it saves verbatim conversation text, commands, file paths and reproduction steps to disk. That makes it easy to accidentally capture API keys, passwords, private URLs, or other secrets even though the document says to 'strip' them — stripping is not enforced. Before installing, consider: (1) restrict or review what session content can be fetched (prefer summaries instead of verbatim tails), (2) require user confirmation before automatic startup fetches, (3) ensure snapshot files are stored in an encrypted/private workspace and not uploaded or backed up publicly, (4) audit the SKILL.md for the Unicode-control-chars finding and remove any suspicious characters, and (5) test in a sandboxed agent with no sensitive data to verify sanitization works. If you cannot guarantee secure storage and reliable secret-stripping, treat this skill as higher-risk and avoid enabling it for sessions containing credentials or private data.

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

sessions_list(kinds: ["main"], limit: 5, messageLimit: 3)

Step 2: Pull the last 3 sessions' conversation tail

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

sessions_history(sessionKey: "<key>", limit: 15, includeTools: false)

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:

# Session Relay — Conversation Context
> Generated: {timestamp}
> Sources: last 3 sessions

## 📎 Last Session Conversation Tail ({session_key}, {date})

**[User]** 能不能做到把最近的三段会话内容直接继承过来
**[Assistant]** 好想法，利用 sessions_list + sessions_history 直接拉...
**[User]** 我说的是上一次会话中的几轮对话接续
**[Assistant]** 啊明白了，你说的不是拉历史做摘要，而是把上个session最后几轮实际对话...

## 📎 Session -2 Conversation Tail ({session_key}, {date})
{same format, last 3 rounds}

## 📎 Session -3 Conversation Tail ({session_key}, {date})
{same format, last 3 rounds}

## 📋 Carry-Forward State
{Merged from conversation context + existing snapshot}
- Active work: ...
- Key decisions: ...
- Pending: ...

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.

Usage	Action
< 60%	No action
60-75%	🟡 Warm: Start incremental snapshot — append new progress to memory/relay-snapshot.md
75-85%	🟠 Hot: Full snapshot refresh — rewrite snapshot with complete current state
> 85%	🔴 Critical: Force-save + warn user + sync to daily log

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

---

Phase 2: Rich Snapshots

Snapshot file: {workspace}/memory/relay-snapshot.md

What makes a good snapshot (vs a bad one)

❌ Bad — too abstract:

- [x] NuwaAI Demo — Codex generated index.html

✅ Good — actionable detail:

- [x] NuwaAI Demo — `nuwa-demo/index.html` generated by Codex
  - Serves via `python3 -m http.server 8082`
  - Uses NuwaAI WebSocket API, needs API key in page
  - NOT YET TESTED — next step is open browser and verify connection

Snapshot Template

# Session Relay Snapshot
> Auto-saved by session-relay | {ISO-8601 timestamp}
> Model: {model} | Context: {used}/{max} ({pct}%)
> Session duration: ~{minutes} min | Compactions: {count}

## 🔥 In Progress (was actively working on this)
{What you were literally doing when the snapshot was taken.
Be specific: file paths, commands run, error states, next immediate step.}

## ✅ Completed This Session
- {Task}: {outcome + key file paths}

## 📋 Pending / Next Steps (priority order)
1. {Specific action} — {why, any blockers}
2. ...

## 🧠 Key Decisions & Context
- {Decision}: {rationale, so next session doesn't re-debate it}

## 🗂️ Working Files
{Files created/modified this session, with brief purpose}
- `path/to/file` — {what it is}

## 💬 User Preferences Discovered
{Anything learned about how the user likes to work}

## ⚠️ Gotchas & Warnings
{Things that tripped you up, so next session avoids them}

Snapshot Rules

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. 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:
   • Conversation tails = what was literally said (the "feel" and flow)
   • Snapshot data = structured state (tasks, files, decisions)
4. Respond as if you remember — don't announce "I restored context". Just naturally continue.
5. 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:

### Session Relay Auto-Save ({HH:MM})
- Context at {pct}%
- Active: {one-line summary of in-progress work}
- Completed: {bullet list of done items}

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:

---
⚠️ 上下文 {pct}%，建议 /compact 或 /new 开新会话。当前进度已自动保存。

---

Edge Cases

• sessions_list/sessions_history unavailable → skip Phase 0, fall back to snapshot file only
• session_status 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.