Memory Reflexion
Tier 2 episodic write operations: the reflexion write path extracted from the
memory router per ADR-063 (memory-skill decomposition). memory still routes
here; a caller that needs only to record a session outcome loads this sub-skill
instead of the full memory surface.
Reflexion is one operation: extract an episode from a completed session log.
The episode record is the durable artifact. It is committed to the repository
and can be queried through memory-search. No non-memory downstream consumer
reads it today.
[!NOTE] This sub-skill previously carried a second step that folded episodes into a derived causal graph (Tier 3). ADR-089 removed that layer: nothing read it, and its aggregated output was noise. Episodes are unaffected and remain the system of record. See ADR-089 for the evidence.
Triggers
Use this skill when the user says:
extract episode from sessionto capture a completed session as an episoderecord what happened this sessionfor the reflexion write pathre-extract this episodeto refresh a record over an existing episode file
Quick Start
# Extract an episode from a completed session log (Tier 2)
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/memory/scripts/extract_session_episode.py" "<session-log-path>"
# Re-extract over an existing episode, merging rather than clobbering
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/memory/scripts/extract_session_episode.py" "<session-log-path>" --preserve
The script is canonical and shared with the memory router; this sub-skill does
not reimplement it. It lives at
${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/memory/scripts/extract_session_episode.py.
Quick Reference
| Operation | Script | Key Parameters |
|---|---|---|
| Extract episode (Tier 2) | extract_session_episode.py |
session_log_path, --output-path, --force, --preserve |
--force and --preserve are mutually exclusive. --force overwrites an
existing episode file. --preserve merges a fresh extraction over the existing
record without dropping richer data already there.
Who Reads Episodes
memory-search reads episodes today. Outside memory tooling, its own tests,
and documentation examples, no code calls get_episodes, get_episode, or
get_decision_sequence. Verify before you rely on the opposite:
git grep -n "get_episodes\|get_episode(\|get_decision_sequence" -- '*.py' \
| grep -v "memory_core/\|/tests/\|test_"
An earlier version of this section claimed three consumers. That claim was false and the ADR-089 review retracted it. One of the three excludes episode paths from a churn signal, one allowlists the episode path prefix, and one generates and stages episodes. None reads episode content.
Write for a future non-memory consumer. Episodes are the primary record of what happened in a session, and their value is that they can be queried later. That does not make an incomplete record harmless, so the extraction rules below still bind.
Tier 2 survived the ADR-089 removal on derivation distance and cost, not on readership. Episodes are the primary record and are many small files. The removed causal graph was derived from them and was a single rewritten blob. Whether episodes earn their keep is an open question that ADR-089 explicitly declined to settle.
Schema
The episode schema is defined in ADR-038 and documented in detail in references/reflexion-memory.md. That reference travels with this sub-skill: it covers the episode schema and the integration workflow. Read it when you need the exact field shapes.
Ordering
Completed session?
│
└─► extract_session_episode.py "<session-log-path>"
└─► Produces an episode record in the repository episode store (Tier 2)
Only extract from COMPLETED sessions. A partial session produces an incomplete episode, and an incomplete episode is a falsified record of what happened. It is committed, so it outlives the session that produced it.
Graceful Degradation
The reflexion write path is local-only. Serena is the canonical store and travels with the repository (ADR-007). Episode extraction reads a session log and writes an episode record. It requires no network store, so there is no fallback to invoke here.
Verification
| Operation | Verification |
|---|---|
| Episode extracted | Episode record written; CLI reports the episode ID and outcome |
| Episode staged | The new episode file appears in git status |
| Re-extraction | --preserve leaves existing richer fields intact; --force replaces the record |
Anti-Patterns
| Anti-Pattern | Do This Instead |
|---|---|
| Extracting from an in-progress session | Only extract from COMPLETED sessions |
| Re-running without a write mode on an existing episode | Choose --force (replace) or --preserve (merge) deliberately |
| Hand-editing an episode record | Re-extract from the session log |
Process
Phase 1: Extract
Run extract_session_episode.py against a completed session log. Confirm the
CLI reports an episode ID and a recognized outcome.
Phase 2: Verify
Confirm the episode file exists in the episode store and that its outcome
matches how the session actually ended. An episode that records
success for a session that was abandoned is worse than no episode, because it
is committed and a later reader has no way to tell it from a true one.
Related Skills
| Skill | When to Use Instead |
|---|---|
memory |
Router for search, health, or maintenance operations |
memory-search |
Tier 1 semantic lookup; smaller context than the full router |
memory-enhancement |
Add citations, verify code references, track confidence |
curating-memories |
Memory maintenance (obsolete, deduplicate, link) |
Troubleshooting
| Symptom | Cause | Recovery |
|---|---|---|
| Episode not found | Session log path wrong or session incomplete | Verify the session log path; confirm the session reached a terminal outcome |
| Episode file already exists | A prior extraction wrote it | Choose --force to replace or --preserve to merge |
| Outcome reads wrong | Session log terminal state is ambiguous | Fix the session log first; the episode derives from it |
See references/reflexion-memory.md for the full troubleshooting table and the retrospective integration workflow.
Extension Points
| Extension | How to Add |
|---|---|
| New episode field | Extend the ADR-038 episode schema; update extract_session_episode.py and the reference |
| Downstream consumer | Read episode records directly; chain through memory-search for retrieval |
Before adding a derived aggregation over episodes, read ADR-089. The last one was deleted for having no reader and producing noise. A new one needs a named consumer that is not itself memory tooling.
References
- ADR-007: Memory-first architecture (canonical store, local-only posture)
- ADR-037: Memory router architecture (the router this sub-skill delegates from)
- ADR-038: Reflexion memory schema (episode shape)
- ADR-056: Skill output format standardization (the envelope this sub-skill emits)
- ADR-063: Memory skill decomposition (this extraction)
- ADR-089: Removal of the derived causal-memory tier
- references/reflexion-memory.md: full schema and integration workflow