Session Reflection

Session reflection is everything the session lived, contrasted against what belongs to each project, until no loop is left dangling. It recovers the whole arc, reconciles it against the durable corpus in both directions, and leaves every item — settled or open — with an owner a later session can find.

Upstream are the transcript, the specialist contracts, and the injected digest. Downstream is memory curation: reflection ends when the corpus is correct. Compaction is a separate act: it is safe at any time and needs no reflection first, because the PreCompact hook rebuilds the session's in-flight state from the database (see "Compacting").

Process

1. Recover the whole arc. Scan from the session opening for accepted and rejected proposals, deferrals, closures, user corrections, and specialist reactions — recency is not weight, an early settled choice still stands. Include cross_layer_impacts, open_gaps, and failure_report findings even where the user never reacted: they are observations about Gaia, not conversational agreements. reference.md holds the full recovery pass.
2. Reconcile in both directions. For each initiative the session touched, read its live corpus — gaia memory get-relevant --initiative=<key> returns that whole pending set uncapped, with bodies — and ask: what did this session produce with no home yet, and what already-open pending did it close, advance, or invalidate? A topic search only answers whether your own phrasing has a row; the closure you owe is usually phrased in terms that predate the session that solved it. Read briefs, plans, tasks, and approvals the same way — a conversation cannot close an object the substrate still shows open. A session that produced any Gaia improvement touched gaia_system by definition, whatever project it was nominally working on — sweep it too. reference.md holds the reverse-sweep mechanics and the objective-state checks that verify a SKIP.
3. Classify disjointly. Separate settled decisions and learnings, genuinely open work, and Gaia improvements. A user correction any user would want is a Gaia improvement, not a settled preference of his: only his difference becomes his row. When closure is uncertain, classify as open; a lost pending costs more than an extra review. For anything about Gaia itself, memory/SKILL.md's ownership test decides the initiative — gaia_system for an observed failure or friction, project-scoped gaia for a decision to build or change something.
4. Give every item a home, and know what the home does. The pending worklist that returns to the user each session selects class=thread with status carry_forward or open only — an anchor still reaches a dispatched agent as held knowledge, but never comes back as work. Filing live work as an anchor hides it; filing settled knowledge as a thread turns the worklist into noise. SKIP is a home only when you name the canonical object that owns the item — already-canonical work is referenced, never copied.
5. Adjudicate against the exception boundary. The boundary table lives in memory/SKILL.md ("Process" step 5) — this is a pointer to it, not a copy. Most operations are decided and executed directly; only the rows the boundary marks "ask first" or "veto" wait on the user.
6. Run the curation, closures included. Materialize the step 2 closures alongside the new rows; reclassify and append are non-mutative, so nothing but omission keeps a resolved thread open. A closing arc that passes the milestone test in reference.md uses checkpoint, one atomic write; an ordinary close does not.
7. State the resume point. One line naming what the next session picks up — a pointer, not a container: everything it names already has a row.

Working tables

These internal tables force one owner per item before curation; omit empty sections. SAVE, APPEND, TRANSITION, LINK, and SKIP are adjudicated by memory; a closure or graduation is a TRANSITION materialized as reclassify. memory/reference.md owns the exact forms.

What we settled

Accepted decisions, closures, and reusable learnings. Prefer SKIP naming the canonical object; SAVE only knowledge that must constrain a later choice.

Open work

One row per unresolved concern and per pending the sweep found resolved; the latter is a TRANSITION, never a silent omission.

What Gaia should improve

Symptom      observable behavior, not diagnosis
Component    one precise owner
Evidence     observed proof
Reproduction exact repeatable route, or unknown
→ feedback_<component>_<symptom> · type feedback · SAVE or APPEND

Work the evidence through before saving; reference.md owns field definitions and the gaia_system retrieval query.

Output

The user sees a post-curation report, one line per durable effect, not the working tables or raw verbs. Flag a type=user row first for its governed veto.

Resume point

Name what the next session picks up: a pointer, never a copied container.

Compacting

Compaction no longer waits for this reflection. Before every compaction, manual or automatic, the PreCompact hook writes this session's ledger from the database -- its open contracts, its pending signatures, the memory it wrote, the worktrees its agents opened -- and the birth that follows renders it as ## Resume point. Reflection stays a deliberate curation pass the user asks for; it is not a precondition. When the user asks to compact, the session id is the session= line of the ## Environment block:

1. Request the compaction. Call the host's compaction tool once: mcp__gaia__compact_when_idle in Claude Code, gaia_compact_when_idle in OpenCode. It schedules the compaction for when the current turn ends, never mid-turn. The host can still refuse it.
2. Optionally leave a hand note. Only what comes next and no row holds -- the exact next action, the active files: gaia session resume-point set --session-id <id> --text "<text>", at most 2000 characters. It appears as note: only in this session's Resume point; the ledger already carries the contracts, signatures, memory and branches, so do not restate them.
3. End the turn with a line saying the compaction was requested -- not that it will happen.

If the next turn carries a note that the compaction did not start, tell the user so, name the host's reason, and ask them to type /compact.

Compact when the user asks, reflection finished or not: do not offer a reflection first and do not hold the compaction for one. The ledger already carries the durable state, and the hand note is where anything else the next turn needs goes.

Without the tool -- a headless Claude Code session (the desktop app, -p, the SDK), where the host cannot compact from a mod, Claude Code with mods disabled or older than 2.1.287, or any host that does not list it -- nothing the orchestrator runs can start the compaction. Skip step 1, optionally leave the hand note (step 2), and end the turn asking the user to type /compact. Never report a compaction you did not start.

When the user types /compact without asking to compact first, nothing above runs: the PreCompact hook still writes the ledger, and the hand note appears only if one was written for this session.

Ownership and consent

Consent mechanics belong to memory: the orchestrator recovers, reconciles, and adjudicates, while gaia-operator materializes exact instructions. Any operation requiring consent is delegated through its approval flow and never autoexecuted. Independent operations are best-effort; a checkpoint stays atomic, so partial state is never reported as closure. Reflection itself is not a new durable object.

Handoffs

• Load memory for curation and reference.md for detailed recovery mechanics.
• Load examples.md for the integrated flow, compaction included.