| name | distill |
| description | Memory consolidation — distills session learnings and transcripts into persistent memory files |
| version | 0.1.0 |
| level | 2 |
| triggers | ["/distill","distill memory","consolidate memory","update memory files"] |
| context_files | ["context/learnings.md"] |
| steps | [{"name":"Orient","description":"Survey the current memory landscape before writing anything"},{"name":"Gather","description":"Collect signal from learnings.md and recent session state"},{"name":"Consolidate","description":"Write and update memory files with new signal"},{"name":"Prune","description":"Keep MEMORY.md index under 200 lines, remove stale entries"}] |
Distill Skill
Consolidates session learnings and accumulated context into the persistent memory system
(~/.claude/memory/). Run when the ember gate fires (heartbeat will notify you) or manually
at any time to refresh memory with recent work.
What Claude Gets Wrong Without This Skill
Without distillation, session learnings accumulate in context/learnings.md but never get
promoted to the global memory system that persists across projects. The memory index grows
stale. Future sessions start with outdated context.
When to Run
- When heartbeat surfaces an
ember-due flag (automatic — run /distill to clear it)
- After a major task is complete and the learnings are worth preserving globally
- Before switching to a different project context
- When
context/learnings.md has grown significantly since the last distillation
The 4-Phase Process
Phase 1 — Orient
Before writing anything, survey the current memory landscape:
ls ~/.claude/memory/
cat ~/.claude/memory/MEMORY.md
Read the MEMORY.md index. Skim 2-3 of the most relevant topic files to understand what's
already there. Avoid duplicating entries that already exist.
Phase 2 — Gather
Collect signal from three sources, in priority order:
- context/learnings.md — most recent entries (scan from bottom up, newest first)
- context/session-memory.md — current session state and key results
- context/decisions.md — any PROPOSED or recently decided entries
For each entry, ask: is this general enough to be useful outside this project, or is it
project-specific? General → global memory. Project-specific → project memory file.
Phase 3 — Consolidate
Write or update memory files:
- New insight: create or append to the relevant topic file
- Existing entry that changed: update in place, note what changed
- Contradicted fact: delete the old entry, write the corrected one
- Relative dates: convert to absolute (e.g. "last week" → "2026-03-24")
Use the standard memory frontmatter format:
---
name: [descriptive name]
description: [one-line description for relevance matching]
type: user | feedback | project | reference
---
[memory content]
Bash access is read-only during distillation. Use only:
ls, find, grep, cat, stat, wc, head, tail
All writes go through the Write/Edit tools only.
Phase 4 — Prune and Index
After writing:
- Update
~/.claude/memory/MEMORY.md index — one line per file, under 150 chars
- Keep the index under 200 lines total
- Remove pointers to files that no longer exist
- Demote verbose index entries (>150 chars) — move detail to the topic file, keep pointer short
- Resolve any contradictions between topic files
Scope Decision
| Content type | Where it goes |
|---|
| How I prefer to work, style preferences | ~/.claude/memory/ (user scope) |
| Project architecture, active constraints | ~/.claude/memory/ with project tag |
| Lessons that apply across projects | ~/.claude/memory/ (global) |
| One-off task detail | Leave in learnings.md, do not promote |
After Distillation
Update the ember lock to mark consolidation complete:
touch ~/.claude/memory/.ember.lock 2>/dev/null || true
This resets the ember gate's time counter. The session counter resets automatically when
the gate fires.
Anti-Patterns
Do not copy-paste entire learnings.md entries into memory. Summarize — memory files should
be denser than raw session notes.
Do not distill one-off task details. The quality gate: would this entry help a future session
that has never seen this project before? If no, leave it in learnings.md.
Do not let MEMORY.md exceed 200 lines. When it approaches the limit, merge related entries
into topic files and keep only the pointer in the index.
Mandatory Checklist
- Verify MEMORY.md index was read before writing any new files
- Verify each new entry was checked against existing entries for duplication
- Verify bash commands used were read-only only
- Verify MEMORY.md index is under 200 lines after pruning
- Verify ember.lock was touched to reset the gate timer
