ldm-session-handoff

Session Handoff

The goal is to enable the next session to verify against the raw record and quickly restore decisions, outputs, progress, and to-dos.

Choose deliverables based on the user's request

• Full handoff: full conversation transcript, router, restant prompt.
• When the user explicitly says "only export the raw text": generate only the full conversation transcript.
• When the user explicitly says "only update the router": read the existing record and outputs, then update the router.
• When the user explicitly says "only the restart prompt," "no export needed," or "do not create files": provide only the prompt; if reliable context is missing, clearly state what information is pending.

When the user says "load the Handoff Skill," "use the Handoff Skill," "session archive," "save the conversation," or "prepare to exit and restart," default to a full handoff; even if the same sentence also mentions "give me a restart prompt," you must not skip the full conversation transcript and router because of that. Only when the user narrows the scope with explicit wording such as "only," "just," "no export needed," or "do not create files" should you switch to a single deliverable.

Full handoff process

1. Confirm the current session, topic, and save directory. Prefer the archive root directory the user has configured; otherwise use an explicit directory in the current workspace.
2. Read the raw user/assistant text through the platform's native export capability or this Skill's script. Do not generate a "full transcript" from memory.
3. Generate a router, keeping only the decisions, outputs, progress, to-dos, and new lessons needed to resume the task.
4. Verify that the files exist, the message counts are reasonable, and the source labels are accurate.
5. Report the absolute paths of all deliverables, and finally provide a copyable restart prompt directly.

For the format, see references/formats.md. Read only when you need to choose or troubleshoot an export backend references/export-backends.md。

Raw-text authenticity

• The "full conversation transcript" must come from a verifiable conversation data source.
• By default, keep the visible user/assistant text, and filter out tool calls, tool outputs, reasoning records, environment injections, and empty placeholders.
• Do not label summaries, routers, or model recollections as raw text.
• If the export is incomplete, state the scope obtained and "pending supplementation"; do not claim that the data necessarily persists permanently.
• Truncating individual entries loses raw text; truncate only when the user requests volume control or platform limits make it unavoidable, and record the threshold and count in the file header.

Router

The router is the main force for restoring context; the restart prompt is only the entry point; the raw text is responsible for lookup, and the router is responsible for restoration. It is navigation, not a retelling of the entire conversation. At minimum, state clearly:

• Key decisions and their reasons.
• Checkpoint: list in chronological order the milestones completed and confirmed, along with their evidence, so the new session can see at a glance how far things have gone.
• Absolute paths and status of completed outputs.
• Resource versions: write only the dependencies and their versions where using the wrong version at restoration time would cause mistakes (skills, asset libraries, templates, tools); write undecided statuses and undone work into to-dos or next steps.
• Work in progress, next steps and their prerequisites (what must be in place or confirmed before starting).
• Unresolved issues and explicit to-dos.
• Only lessons newly learned this time that are reusable.

For external links, record only the final entry points that need to continue being used. Do not write sensitive credentials into the router.

Export tool

• Hermes SQLite：scripts/export_transcript.py
• Claude Code / Codex JSONL：scripts/export_jsonl_transcript.py

The script is only responsible for exporting the original text, not for generating the router. First use --list to find the session, then specify the session and output path; when multiple backends exist on the machine, do not guess.

Currently active sessionwill not appear in --list . Export steps:session_search search for keywords in the current conversation → extract from the results session_id → export_transcript.py --session <id> --output <绝对路径>. This path works equally well for active sessions and ended sessions.

Completion check

• The delivered content matches the scope of artifacts requested by the user.
• The header of the full record file states the data source, session identifier, time range, message count and export method.
• For a complete handover, the absolute paths of both files have been reported, and the restart prompt has been sent directly to the user.
• Failures and truncations are marked truthfully; no summary is passed off as original text.

Pitfalls

1. Never claim "it cannot be exported" (practical lesson from 2026-09-04/09-08)

When the user explicitly requests an export, do not give up on the grounds of "currently active session". Export path:session_search extract session_id → export_transcript.py --session <id>. This trick works for both active sessions and ended sessions.

This mistake has already enraged the user twice. If --list cannot be found, switch to session_search; if session_search also cannot be found, report truthfully, but try both paths first before saying so.

2. Absolute paths must be used in restart prompts and routers (practical lesson from 2026-09-04/09-08)

• ❌ ~/Documents/Hermes_Workspace/...（~ is not an absolute path, and the user will be enraged)
• ✅ /Users/likai/Documents/Hermes_Workspace/...

All file paths must begin with /Users/likai/ . This includes restart prompts, router output lists, and guidance given by the user. The user has corrected this issue multiple times.

3. Do not filter full-record exports by active = 1 (practical lesson from 2026-09-11)

Context compression marks already-compressed old messages as active = 0, but thoseare still the real original text from before compression, and the full record must retain them. Filtering by active = 1 will export a long session as one tenth of its size (in one measured session only 34 entries were exported, while the actual original text had 162 entries) — exactly the earliest part, the part most needed for later review, is what gets lost.

Only exclude lines of _compressed_summary = 1 : that is an AI summary generated by compression for the model to read, not the original text.export_transcript.py has been fixed (commit 5844ac6); when you really need to see only the currently active context, use --active-only. Context reconstruction also re-inserts entire historical blocks into the database repeatedly (the same message is reinserted over and over as [Note: ...] prefixed variants); the script has built-in deduplication: block replays (3 or more consecutive entries with the same order and same text) are removed as a whole block, repeated long assistant texts keep only the first occurrence, and user messages are not globally deduplicated (sending "1" repeatedly is real conversation). The file header will state the number of entries removed in each of the two categories.

After exporting, the entry count must be verified: the message count written in the file header should match "user entries + assistant entries" and be consistent with the actual entry count in the database by order of magnitude.

4. This skill is a symlink,skill_manage cannot be modified (practical lesson from 2026-09-11)

skill_manage will report not found in active profile, because the real source is in the ldm-skill repository. To modify this skill, directly use patch Tool changes the true source path:

/Users/likai/Documents/Hermes_Workspace/ldm-skill/skills/ldm-session-handoff/SKILL.md

After the change, read back from the symlink path (/Users/likai/.hermes/skills/ldm-session-handoff/SKILL.md) to verify.