Session Gist

A session gist is a record that captures what happened in a session, produced when the session ends. It is one of the most common record types in a healthy Cortex store, and it is the connective tissue between the session-as-a-runtime-event and the session-as-a-thing-to-remember.

The pattern

When a session ends, two paths are possible:

• Clean stop. The Stop hook fires. It receives a transcript or summary of the session and writes a stop-typed event to the inbox.
• Pre-compact. The PreCompact hook fires before the client compacts away the original turns. It writes a pre_compact-typed event with the current conversation snapshot.

Either way, an event lands in inbox/pending/. The next normalize pass turns it into a record — the session gist.

What goes in a gist

A gist is not a full transcript. It is a structured summary, typically including:

• A short title summarising what the session was about.
• The opening request or intent.
• Key decisions or discoveries that came out of the session.
• Any unresolved threads or follow-ups.
• Any artefacts produced (files written, branches created, PRs opened).

The exact section structure depends on the event type and the normalizer’s template for that type. A stop event with a long transcript may yield a multi-section gist; a pre_compact event with just a snapshot may yield a short one.

Why session gists matter

The session is the unit of work for the AI client. The gist is the unit of memory for Cortex. Without the gist, the session’s value evaporates the moment it ends.

Three concrete uses for gists:

Session-start injection

When the next session begins in the same project, the SessionStart hook queries Cortex for relevant gists. Recent gists for the active project land in the model’s context, giving the new session continuity with the last one.

Cross-session search

Gists are recallable like any other record. Asking Cortex “what did I work on in this project last week” returns the relevant gists. The session itself is gone; the gist remains.

Reflection inputs

When reflect is called, gists for the same scope feed into the input set. They are pre-summarised (one summary per session) so the reflection operates at the right level of granularity.

Gist hygiene

Gists accumulate. A project active for months might have hundreds of session gists, some useful, many redundant.

Three mechanisms keep this manageable:

• Distillation. The distillation loop rolls up many gists into a smaller number of higher-level summaries. Originals are kept; the summaries surface in default recalls.
• Activation. Gists that have not been accessed in a long time fall in rank. They are still recallable; they just stop dominating.
• Supersession. A gist that is genuinely superseded — the issue it described was resolved, the question it raised was answered — can be marked superseded by the resolution record. It still exists; it no longer surfaces.

None of these are destructive. The gists do not go away. They just gradually move from “active memory” to “deeper history” as time passes.

What a gist is not

• It is not a transcript. The original session content is captured at the event level (in inbox/processed/), not the record level. The gist is the distillation of the session, not its archive.
• It is not authoritative. A gist is the model’s summary of what happened. If the user wants a guaranteed-faithful record of a specific decision or fact, they should capture it explicitly — either via an MCP capture call or by writing the record by hand.
• It is not free. Each session ending produces one gist; high-volume use produces a steady stream of records. The distillation loop exists precisely to keep that volume tractable.

The gist is the cheapest way to preserve a session’s value. It is not the only way, and it is not always the right way.