S = Session (conversation history as .jsonl) M = Memory { auto: MEMORY.md, user, project, domain } Ctx = Context detection: S → { sessionId, memoryMode, paths } ∥E = Parallel extraction: S × M → Δ -- coproduct of 3 subagents Δ = Extracted artifacts { summary, insights[], related[] } Sel = Selection: Δ → (Iₛ, Lₛ) -- user-guided via AskUserQuestion Iₛ = Selected insights (subset) Lₛ = Storage tier per insight: { tier ∈ {A: MEMORY.md, B: .insights/}, path } Int = Integration: (Iₛ, Lₛ, M) → M' -- write to memory M' = Updated memory state

── PHASE MAPPING ── Phase 1: S → Ctx(S) -- context detection Phase 2: Ctx(S), M → ∥E(S, M) → Δ -- parallel extraction Phase 3: Δ → Sel(Δ) → (Iₛ, Lₛ) -- guided selection Phase 4: (Iₛ, Lₛ, M) → Int → M' -- integration Phase 5: M' → Verify → Cleanup -- verification


For full categorical notation, see `references/formal-semantics.md`.

## Core Principle

**Crystallization over Accumulation**: Distill structured insights; do not merely archive raw experience.

**Recognition over Recall**: Present options, minimize memory burden.

## Initialization (MANDATORY)

Upon invocation, call TodoWrite to track phases:

TodoWrite([ {content: "Detect session context", activeForm: "Detecting session context", status: "in_progress"}, {content: "Extract insights (parallel)", activeForm: "Extracting insights", status: "pending"}, {content: "Guide insight selection", activeForm: "Guiding insight selection", status: "pending"}, {content: "Integrate selected insights", activeForm: "Integrating insights", status: "pending"}, {content: "Verify and cleanup", activeForm: "Verifying completion", status: "pending"} ])


Update status at each phase transition. This externalizes working memory and prevents phase skipping.

## Protocol Integration

**When Prothesis is active**: Invoke `/frame` before Phase 2 extraction for perspective selection. The selected perspective guides insight extraction focus.

**When Syneidesis is active**: Gap detection applies at Phase 3 decision points (Q2-Q5). Syneidesis may surface additional considerations before each AskUserQuestion.

**Cross-session enrichment pathway** (Tertiary hermeneutic circle): Knowledge stored by Reflexion feeds into subsequent sessions' protocol Phase 0/1 detection as heuristic context. Each protocol defines its own consumption pattern — Reflexion provides the storage half; consumption is inscribed in each protocol's SKILL.md. This completes the cross-session knowledge circulation: experience → Reflexion storage → Phase 0/1 enrichment → deeper experience → spiral deepening. Prior patterns loaded per-session may bias detection toward previously observed patterns — each consuming protocol's gate ensures user judgment prevails over prior-pattern bias.

## Workflow

### Phase 1: Context Detection (Main Agent)

1. **Identify current session path**:
   ```bash
   # Session files location pattern:
   ~/.claude/projects/-{encoded-project-path}/sessions/{session-id}.jsonl
   # or for user-level mode:
   ~/.claude/sessions/{session-id}.jsonl

Use Glob to find recent session: ~/.claude/**/sessions/*.jsonl
Sort by modification time, take most recent
Or use /tasks command to see active session ID

Determine Memory Mode:
- Session path contains /projects/- → project-level mode
- Session path is ~/.claude/sessions/ → user-level mode
Create handoff state directory: /tmp/.reflexion/{session-id}/

Write session-context.json:

{
  "sessionId": "<session-id>",
  "sessionPath": "<detected-session-path>",
  "projectPath": "<project-root>",
  "memoryMode": "project-level | user-level",
  "userLevelPath": "~/.claude",
  "projectLevelPath": "<project-root>/.claude"
}

Phase Completion: Update TodoWrite (Phase 1: completed, Phase 2: in_progress)

Phase 2: Parallel Extraction (Plugin Agents)

Call 3 plugin agents in parallel with run_in_background: true:

Task(subagent_type: "reflexion:session-summarizer",
     prompt: "session_path={session_path}, session_id={session_id}",
     run_in_background: true)

Task(subagent_type: "reflexion:insight-extractor",
     prompt: "session_path={session_path}, session_id={session_id}",
     run_in_background: true)

Task(subagent_type: "reflexion:knowledge-finder",
     prompt: "session_id={session_id}",
     run_in_background: true)

Outputs (written by agents):

/tmp/.reflexion/{session-id}/session-summary.md
/tmp/.reflexion/{session-id}/extracted-insights.md
/tmp/.reflexion/{session-id}/related-knowledge.md

Wait for completion:

TaskOutput(task_id=summarizer_id, block=true)
TaskOutput(task_id=extractor_id, block=true)
TaskOutput(task_id=finder_id, block=true)

For detailed agent specifications, see agents/*.md.

Phase Completion: Update TodoWrite (Phase 2: completed, Phase 3: in_progress)

Phase 3: Guided Selection (Main Agent - AskUserQuestion Loop)

Read handoff files and conduct guided dialogue:

Q1: Summary Validation

"Does this summary look correct?"
├── "Yes, correct"
├── "Needs modification" → call AskUserQuestion with inferred options
└── "Skip summary"

Recognition over Recall: When user requests modification, infer likely
missing/incorrect items from session context and present as options.
Never ask open-ended "what should be added?" questions.

Q2: Insight Selection (multiSelect: true)

"Which insights should be saved?"
├── [Insight 1]
├── [Insight 2]
├── ...
└── "None (skip saving)"

Q3: Additional Memory (optional)

"Any missed perspectives?"
├── "Yes" → call AskUserQuestion with inferred options
└── "No, sufficient"

Recognition over Recall: Infer potential insights from session context
NOT already in extracted list. Present as options, not open-ended questions.

Q4: Merge Decision (if related knowledge found)

"Merge with existing knowledge?"
├── "Merge (modify existing file)"
├── "Create new"
└── "Skip"

Q5: Storage Tier (per selected insight)

Project-level mode:

├── "Tier A — MEMORY.md (always loaded, concise entry)"
└── "Tier B — .insights/ (reference-on-demand, detailed archive)"

User-level mode (sessions under ~/.claude/sessions/):

└── "Tier B — .insights/ only (no project MEMORY.md in user-level mode)"

Tier A guidance: suitable for recurring patterns, architecture decisions, project conventions — content read every session. Tier B guidance: suitable for archival knowledge, domain references, project-independent notes — loaded only when relevant.

If Tier B selected → Q5b: .insights/ Scope:

Project-level mode:
├── "Project .insights/ (project-specific archival)"
├── "User .insights/ ~/.claude/.insights/ (cross-project reference)"
└── "Domain .insights/ (tech-stack specific)"

User-level mode:
├── "User .insights/ ~/.claude/.insights/ (cross-project reference)"
└── "Domain .insights/ (tech-stack specific)"

Phase Completion: Update TodoWrite (Phase 3: completed, Phase 4: in_progress)

Phase 4: Integration (Main Agent or Subagent)

Based on user selections:

Tier A (MEMORY.md): Append compact entry to project auto-memory MEMORY.md
- Project-level mode only: path derived from session path by replacing sessions/{session-id}.jsonl → memory/MEMORY.md
- Path: ~/.claude/projects/{encoded}/memory/MEMORY.md
- User-level mode: Tier A unavailable — ~/.claude/memory/ does not exist; Q5 must show Tier B only
- Format: concise markdown under existing topic header or new ## {Topic} section
- Language: English (Korean blocked by hook); no YAML frontmatter
- Constraint: keep MEMORY.md ≤200 lines (only first 200 lines loaded); consolidate or move to .insights/ if near limit
Tier B — New file: Create in selected .insights/ location with proper frontmatter
Tier B — Merge: Edit existing .insights/ file, append or modify section
Tier B — Domain: Create in .insights/domain/{tech-stack}/

Frontmatter Update Rules (Tier B only):

Field	New File	Merge
`date`	Current date	Update to current date
`session`	`[<session-id>]`	Append current session ID
`tags`	From insight	Union (add new, keep existing)
`keywords`	From insight	Union (add new, keep existing)
`summary`	From insight	Revise to reflect merged content
`sections`	From insight	Append new section entries

# Before merge
---
date: 2026-01-15
session: [s1]
tags: [A, B]
keywords: [x, y]
---

# After merge (current session: s2, new insight has tag C, keyword z)
---
date: 2026-02-04       # → Updated
session: [s1, s2]      # → Appended
tags: [A, B, C]        # → Union
keywords: [x, y, z]    # → Union
---

If multiple files to edit, delegate to Task subagent.

Phase Completion: Update TodoWrite (Phase 4: completed, Phase 5: in_progress)

Phase 5: Verification (Main Agent)

"Complete. Any additional actions needed?"
├── "Analyze another session" → Restart from Phase 1
├── "Review related rules" → Suggest relevant rules
└── "Done"

Clean up handoff state: rm -rf /tmp/.reflexion/{session-id}/

Phase Completion: Update TodoWrite (All phases completed), clean up todo list

Additional Resources

agents/ — Plugin agents for Phase 2 parallel extraction
references/formal-semantics.md — Categorical and type-theoretic formalization
references/memory-hierarchy.md — Memory layer documentation
references/subagent-prompts.md — Operational reference (chunking, error handling, invocation)
references/error-handling.md — Error recovery procedures
examples/worked-example.md — Complete walkthrough

reflexion

Reflexion v3

Definition