Session Handoff

Record where the thinking landed, not that a session happened.

What It Is

A session ends with decisions half-made, questions half-answered, and findings nobody wrote down. The next session starts from zero and re-derives them, which costs tokens and forces the human to reconstruct their own prior reasoning.

This skill decomposes a session into typed units and stages them for later recall. The type is what makes recall trustworthy: a status update stops being true in days, while a fact about how a tool behaves stays true for years, so the two cannot share one shelf life.

The Unit Schema

Every unit carries seven fields:

Thread: short, specific label phrased the way a later session would ask
Type:   finding | decision | open-thread | state
Date:   YYYY-MM-DD, when this thread reached its conclusion
State:  what landed by the end of the session, in 1-2 sentences
Why:    the load-bearing reasoning, including what was rejected
Open:   what remains unresolved, omitted entirely when nothing is
Ref:    the session this came from

The four types and how fast each ages:

Type	What it is	Half-life
finding	A durable fact about the world, platform, or tools	365 days
decision	A project choice that could later be revised	90 days
state	A transient status or state change	7 days
open-thread	A live, unresolved question	does not decay

Those values are the retention classes in memory_palace.corpus.decay_model.UNIT_TYPE_DECAY. The writer picks a type, never a shelf life, so retention is bound once per class rather than guessed per item.

Two-Phase Extraction

Inventory first, judge second. Doing both at once loses threads, because the act of grouping suppresses items that do not fit a group yet.

1. Phase 1 sweeps the transcript and lists every distinct thread it touched, one line each. Over-include on purpose.
2. Phase 2 groups that inventory into threads and renders one unit per thread per type.

Full procedure and the coverage self-check: modules/two-phase-extraction.md.

Splitting and Superseding

A thread that bundles a durable finding with the transient action that produced it becomes two units with different types, so each ages on its own curve.

A later unit with the same Thread and Type supersedes the earlier one. The same thread under a different type stays separate. Supersession is why a revised decision does not surface next to the decision it replaced.

Capture Workflow

1. Run Phase 1, then Phase 2.
2. Optionally gate the rendered units through Skill(memory-palace:memory-clarity-probe). If the composite reads Unclear, expand the units before staging them.
3. Write them to data/state/handoff_units.json in this shape:

{"units": [{"thread": "...", "type": "decision", "date": "2026-08-13",
            "state": "...", "why": "...", "open": "", "ref": "...",
            "files": ["src/thing.py"]}]}

Declare files when the claim would stop being true if those paths changed. The capture path fingerprints them, and recall flags the unit when one moves.

The Stop hook drains that file and merges the units into the session record. The Stop payload carries no transcript content and the hook runs no model, which is why capture is staged by this skill rather than extracted by the hook.

Recall Workflow

Append +recall to a prompt to have matching units injected, or +recall? to also see what was retrieved. Recall is opt-in because fixed-cost injection on every turn spends the context window it was meant to extend.

Before acting on any state unit, state the elapsed time since it was written. See modules/temporal-awareness.md.

When to suggest it mid-session

The token is the user's to type, so the work here is to say when it would pay and leave the choice with them. Offer it in one line at the moment it applies, then answer the question that was actually asked.

plugins/memory-palace/hooks/recall.py ranks units by keyword overlap between the prompt and each unit's thread, state, why, and open fields, scaled by type-aware decay. The rest follows from that: overlap is the retrieval, so a prompt naming its topic retrieves and a prompt gesturing at it does not.

Moment in the session	Offer	What makes it pay
The prompt names work from an earlier session in that work's own vocabulary	+recall	Overlap scoring has terms to match
Work resumes after a clear or a compaction	+recall	The units are still on disk once the live context no longer holds them
The user asks why a past decision went the way it did	+recall	why is one of the ranked fields
The user doubts whether injected state is still current	+recall?	Visible mode shows what was retrieved and which dependencies moved

Stay quiet in the other cases. Say nothing when the answer is already in the live context, when the prompt shares no content words with any prior thread, or when this session already recalled that thread. Retrieval on a zero-overlap prompt returns nothing and costs the user a round trip, and units dedupe by thread and type, so a second +recall on a recalled thread returns what the user is reading now.

Phrase it as an offer beside the answer, never as a precondition for one: "the prior session left notes on this, so add +recall if you want them."

When NOT To Use

• Capturing knowledge from an external article: use Skill(memory-palace:knowledge-intake).
• Building a scratch structure inside one long conversation: use Skill(memory-palace:session-palace-builder).
• Judging whether a summary is clear enough to hand off: that is Skill(memory-palace:memory-clarity-probe).

Detailed Resources

Module	Read it for
modules/unit-schema.md	Field semantics, type selection, worked examples
modules/two-phase-extraction.md	The sweep checklist and render rules
modules/temporal-awareness.md	Session gaps and what survives them

Known Limitation

The staging file is process-global. Two concurrent sessions in one checkout can have one drain the other's units. The window is a single turn, and the skill cannot know its own session id, which is why staging exists rather than direct record writes.

Exit Criteria

• Phase 1 names the thread count before any unit is written
• Every unit carries all seven fields and a Type from the four
• A thread holding a durable result and the transient action that produced it is emitted as two units with different types
• Units land in data/state/handoff_units.json and it parses as JSON with a top-level units array
• On resume, elapsed time since the prior session is stated before any state unit is acted on
• Open threads carry a non-empty Open field
• A +recall offer names the thread it would retrieve, and is made at most once per thread per session