session-handoff

Table of Contents

• [What It Is](#what-it-is)
• [The Unit Schema](#the-unit-schema)
• [Two-Phase Extraction](#two-phase-extraction)
• [Splitting and Superseding](#splitting-and-superseding)
• [Capture Workflow](#capture-workflow)
• [Recall Workflow](#recall-workflow)
• [When NOT To Use](#when-not-to-use)
• [Detailed Resources](#detailed-resources)
• [Exit Criteria](#exit-criteria)

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.

1. 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.

1. 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