session-distill

---
name: session-distill
description: This skill should be used when the user asks to "distill this session", "save session learnings", "capture learnings from this session", "what's worth remembering from this session", "session distill", or "extract memories from this session". Reflects over the current conversation, extracts 1–3 atomic, non-obvious learnings the code and commits won't capture, and drafts them as fleeting memories into the review-memories queue — no source snapshot.
---

# Session Distill

Mine the current session for durable knowledge and draft it as fleeting memories. A session is a good *mine* but a bad *artifact*: most of it is ephemeral, and the parts worth keeping that already live in code, commit messages, or diffs do not need a memory. This skill extracts only the small residue a future reader could not recover by reading the repo — decisions made in conversation, gotchas found by trial-and-error, and rejected approaches with their rationale.

Unlike `engy:ingest`, this skill never writes a source snapshot and never commits a transcript. It produces lightweight, atomic fleeting memories that join the standard `engy:review-memories` promotion lifecycle, human-gated at every step.

## MCP Tools

- `listWorkspaces` — resolve `workspaceId` when not known from context
- `createFleetingMemory` — draft each approved distillation (DB row, `promoted: false`)

## Core Principle: Distill, Don't Snapshot

The signal-to-noise ratio of a raw session is brutal. A dense hour typically yields **one** memory worth keeping. Resist the urge to summarize the whole conversation. Capture the few claims that are both *non-obvious* and *not already recorded elsewhere*, then stop.

## Selection Filter

Apply this filter to every candidate before drafting it. When in doubt, drop it — a missed learning costs little; a noisy memory degrades retrieval for every future query.

**Keep** (not recoverable from the repo):
- **Decisions made in conversation** — "chose X over Y because Z", where Z lives only in the discussion.
- **Gotchas found the hard way** — surprising tool/library/environment behavior that cost real trial-and-error.
- **Rejected approaches** — what was tried, why it failed, what replaced it.
- **Conventions discovered** — an implicit rule not enforced by linters/types and not written in CLAUDE.md.

**Skip** (already recorded, or ephemeral):
- Anything captured by the **code comment, commit message, or diff** of work done this session.
- Step-by-step narration of what happened, exact command sequences, or tool output.
- Transient state (merge in progress, which file was open, a flaky run that resolved).
- Restatements of existing memories or CLAUDE.md content.

See `references/selection-criteria.md` for worked keep-vs-skip examples drawn from real sessions.

**Boundary — Engy knowledge layer vs. harness memory.** This skill writes to the Engy workspace knowledge layer. A learning that is purely about *how Claude should operate* (tool quirks, testing technique, workflow preference) often belongs in the harness per-project memory at `~/.claude/projects/<slug>/memory/` instead. If a candidate is operational-for-Claude rather than domain/product knowledge, flag it during confirmation (Step 4) and let the user decide where it lands — do not force it into the knowledge layer.

## Process

### Step 1: Identify Workspace

Resolve `workspaceId` from the current session/route context. If ambiguous, call `listWorkspaces` and ask which workspace to capture into.

### Step 2: Scan the Session

The current conversation is already in context — no tool fetches it. Re-read the session and list every candidate learning, then immediately run each through the Selection Filter. Produce a shortlist of **at most 3** survivors. If nothing survives, print "No durable learnings to capture — everything from this session is already in the code, commits, or existing memory." and stop. Reporting nothing is a valid, common outcome.

### Step 3: Draft Atomic Distillations

For each survivor, draft a four-part body (matching `engy:ingest` distillations for consistency). **Atomicity rule (load-bearing for retrieval):** one central claim per memory. Do not fold a second claim in with "and"/"also" — split it into a separate candidate or drop it. Do not restate a sibling fact that belongs in its own memory; point to it in "Connects to" instead.

```
**Core claim:** <the single most important assertion>

**What surprised:** <what was non-obvious or cost trial-and-error>

**Connects to:** <related topics, decisions, or existing notes — name them>

**Contradicts:** <any prior position or note this conflicts with, or "nothing identified">

Session: <session id if known from context, else "session YYYY-MM-DD">
```

Derive tags: always include `'session-distill'`; add a repo short-name tag when the learning is repo-scoped, and a doc-class tag (`'convention'`, `'decision'`, etc.) where unambiguous. Do not invent rich per-memory tags — `engy:review-memories` proposes those at promotion.

### Step 4: Confirm With the User (Human Gate)

Present the shortlist before creating anything. For each candidate show: the proposed core claim, its tags, and whether it reads as **domain knowledge** (→ Engy knowledge layer) or **operational-for-Claude** (→ may belong in harness memory). Let the user approve, edit, reclassify, or drop each one. Only approved, domain-bound candidates proceed to Step 5.

### Step 5: Create Fleeting Memories

For each approved candidate, call:

```
createFleetingMemory({
  workspaceId: <id>,
  type: 'capture',
  source: 'agent',
  tags: ['session-distill', ...<derived tags>],
  content: <four-part body from Step 3>
})
```

Note: `source` has no `'session'` value (enum is `agent | user | system`) and there is no session-id parameter — that is why provenance rides in the `tags` and the `Session:` line of the body. Record each returned memory `id` for the summary.

### Step 6: Hand Off

Do **not** reindex and do **not** commit anything — fleeting memories are surfaced by `engy:review-memories` via `listMemories`, not search, so no index update is needed, and promotion (not this skill) writes the durable markdown file.

## Output Format

```
Session distill complete.

  Scanned:    <N> candidates, <M> survived the filter
  Created:    fleeting #<id> — <core claim, truncated>   [tags]
              fleeting #<id> — <core claim, truncated>   [tags]
  Deferred:   <K> flagged as operational → suggested for harness memory (not created here)

Next: run /engy:review-memories to promote these when ready.
```

## Key Principles

- **One memory is a good session.** Three is a lot. Zero is common and fine.
- **The session is a mine, not an artifact** — never snapshot or commit the transcript.
- **No auto-promotion** — drafts join `engy:review-memories`; this skill never promotes.
- **Human-gated** — propose before creating; the user is the arbiter of what is worth keeping.
- **Respect the memory boundary** — operational-for-Claude learnings may belong in harness memory, not the knowledge layer.

## Flow Position

**Typical trigger:** the user wraps up a working session and wants its durable learnings captured.

**Next step:** `/engy:review-memories` — promotes the drafted distillations when the user is ready.

• SKILL.md 7 KB
• references/selection-criteria.md 4 KB