memtrace 0.1.37 → 0.1.45

package/installer/skills/commands/memtrace-impact.md

@@ -0,0 +1,64 @@
+---
+name: memtrace-impact
+description: "Use when the user asks about blast radius, what will break if I change this, risk of modifying a symbol, upstream or downstream dependencies, impact analysis before refactoring, or wants to understand the consequences of a code change"
+allowed-tools:
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+user-invocable: true
+---
+
+## Overview
+
+Compute the blast radius of changing a specific symbol. Traces upstream (what depends on this) and downstream (what this depends on) through the knowledge graph to quantify risk before making modifications.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `get_impact` | Blast radius from a specific symbol (by ID) |
+| `detect_changes` | Scope symbols affected by a diff/patch |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Identify the symbol
+
+If you have a symbol name but not its ID:
+- Use `find_symbol` for exact names
+- Use `find_code` for natural-language queries
+
+### 2. Run impact analysis
+
+Use the `get_impact` MCP tool:
+- `symbol_id` — the symbol you plan to change (required)
+- `direction` — `upstream` (what depends on me), `downstream` (what I depend on), or `both` (default)
+- `depth` — traversal hops (default 3)
+
+### 3. Interpret the risk rating
+
+| Risk | Meaning | Action |
+|------|---------|--------|
+| **Low** | Few dependents, leaf node | Safe to modify; minimal testing needed |
+| **Medium** | Moderate dependents | Test direct callers; review interface contracts |
+| **High** | Many dependents across modules | Coordinate changes; comprehensive test coverage |
+| **Critical** | Core infrastructure, many transitive dependents | Plan migration strategy; consider backward-compatible changes |
+
+### 4. For diff-based analysis
+
+When you have an actual code diff (not just a symbol), use `detect_changes`:
+- Scopes all symbols affected by the diff
+- Returns blast radius AND affected processes (execution flows)
+- Useful for PR reviews or pre-commit checks
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Changing a single function | `get_impact` with `direction: both` |
+| Reviewing a PR or diff | `detect_changes` with the diff content |
+| Renaming/removing a public API | `get_impact` with `direction: upstream`, high depth |
+| Refactoring internals | `get_impact` with `direction: downstream` to check what you depend on |

package/installer/skills/commands/memtrace-index.md

@@ -0,0 +1,66 @@
+---
+name: memtrace-index
+description: "Use when the user asks to index a project, set up code intelligence, parse a codebase, build a knowledge graph, prepare a repo for analysis, or as the very first step before any code exploration, search, or relationship analysis"
+allowed-tools:
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__check_job_status
+  - mcp__memtrace__list_jobs
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Index a local codebase into the persistent code knowledge graph. This is always the first step — it parses every source file, resolves cross-file relationships, detects API endpoints/calls, runs community detection and process tracing, and embeds all symbols for semantic search.
+
+## Quick Reference
+
+| Parameter | Purpose |
+|-----------|---------|
+| `path` | Absolute path to the directory to index |
+| `incremental` | Only re-parse changed files (use for subsequent runs) |
+| `clear_existing` | Wipe and rebuild from scratch |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Check if already indexed
+
+Use the `list_indexed_repositories` MCP tool first. If the repo is already indexed and recent, skip to step 4.
+
+**Success criteria:** You have a list of repo_ids and their last-indexed timestamps.
+
+### 2. Index the directory
+
+Use the `index_directory` MCP tool:
+
+- Set `path` to the project root (absolute path)
+- Set `incremental: true` if re-indexing after changes
+- Set `clear_existing: true` only if a full rebuild is needed
+
+**Success criteria:** You receive a `job_id` immediately.
+
+### 3. Poll for completion
+
+Use `check_job_status` with the `job_id` every 2–3 seconds.
+
+Pipeline stages in order: **scan → parse → resolve → communities → processes → persist → embeddings → api_detect → done**
+
+Wait until `status = "completed"`. If `status = "failed"`, report the error message to the user.
+
+### 4. Report to user
+
+After indexing completes, call `list_indexed_repositories` to confirm the repo appears with correct node/edge counts. Report: repo_id, languages detected, total symbols, total relationships.
+
+**Save the `repo_id`** — most other memtrace tools require it.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Path does not exist | Ask user to verify the absolute path |
+| Job status "failed" | Report the error message; suggest `clear_existing: true` for a fresh rebuild |
+| Timeout (job running > 5 min) | Large repos are normal; keep polling. For monorepos, index subdirectories separately |
+| Already indexed | Use `incremental: true` to update, or skip indexing entirely |

package/installer/skills/commands/memtrace-quality.md

@@ -0,0 +1,69 @@
+---
+name: memtrace-quality
+description: "Use when the user asks about dead code, unused functions, code complexity, cyclomatic complexity, refactoring candidates, code smells, code quality metrics, functions that are too complex, or wants to find code that should be cleaned up"
+allowed-tools:
+  - mcp__memtrace__find_dead_code
+  - mcp__memtrace__calculate_cyclomatic_complexity
+  - mcp__memtrace__find_most_complex_functions
+  - mcp__memtrace__get_repository_stats
+user-invocable: true
+---
+
+## Overview
+
+Identify code quality issues using structural graph analysis — dead code (zero callers), complexity hotspots (high out-degree), and repository-wide statistics.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_dead_code` | Symbols with zero callers (potentially unused) |
+| `calculate_cyclomatic_complexity` | Complexity score for a specific symbol |
+| `find_most_complex_functions` | Top-N functions by complexity across the repo |
+| `get_repository_stats` | Repo-wide counts: nodes, edges, communities, processes |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Get repository overview
+
+Use `get_repository_stats` to understand the codebase scale:
+- Node counts by kind (functions, classes, methods, interfaces)
+- Edge counts (calls, imports, extends, type references)
+- Community and process counts
+
+### 2. Find dead code
+
+Use `find_dead_code`:
+- `repo_id` — required
+- `include_tests` — set true to also flag unused test helpers (default false)
+
+**Note:** Exported symbols and entry points are excluded by default — the tool won't flag public APIs as "dead" just because they're called externally.
+
+### 3. Find complexity hotspots
+
+Use `find_most_complex_functions`:
+- `repo_id` — required
+- `limit` — how many to return (default 10)
+
+Complexity scoring (based on out-degree — number of callees):
+| Score | Rating | Action |
+|-------|--------|--------|
+| < 5 | Low | No action needed |
+| 5–10 | Medium | Monitor; consider splitting if growing |
+| 10–20 | High | Refactoring candidate; extract helper functions |
+| > 20 | Critical | Immediate attention; this function does too much |
+
+### 4. Drill into specific functions
+
+Use `calculate_cyclomatic_complexity` on specific symbols flagged by the user or found in step 3.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Treating all dead code as deletable | Some "dead" code is called via reflection, dynamic dispatch, or external consumers |
+| Ignoring exported symbols in dead code results | If `include_tests: false`, exported symbols are already excluded |
+| Only looking at the highest complexity | Medium-complexity functions that are growing (check `get_evolution`) are often more urgent |

package/installer/skills/commands/memtrace-relationships.md

@@ -0,0 +1,73 @@
+---
+name: memtrace-relationships
+description: "Use when the user asks who calls a function, what a function calls, class hierarchy, inheritance, imports, exports, type usages, dependencies between symbols, or wants to understand how code connects before making changes"
+allowed-tools:
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+user-invocable: true
+---
+
+## Overview
+
+Traverse the code knowledge graph to map relationships between symbols — callers, callees, class hierarchies, imports, exports, and type usages. Essential for understanding a symbol's neighbourhood before modifying it.
+
+## Quick Reference
+
+| query_type | What it finds |
+|------------|---------------|
+| `find_callers` | What calls this function/method? |
+| `find_callees` | What does this function call? |
+| `class_hierarchy` | Parent classes, interfaces, mixins |
+| `overrides` | Which child classes override this method? |
+| `imports` | What modules does this file import? |
+| `exporters` | Which files import this module? |
+| `type_usages` | Where is this type/interface referenced? |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Get the symbol ID
+
+If you don't have a symbol `id`, find it first:
+- Use `find_symbol` for exact names
+- Use `find_code` for natural-language queries
+
+### 2. Choose your approach
+
+**Quick 360° view** → Use `get_symbol_context`
+Returns in one call: direct callers, callees, type references, community membership, process membership, and cross-repo API callers.
+
+**ALWAYS prefer `get_symbol_context` first** — it answers "what does this touch and what touches it?" faster than multiple `analyze_relationships` calls.
+
+**Targeted traversal** → Use `analyze_relationships`
+When you need a specific relationship type at a specific depth:
+- `symbol_id` — the symbol to start from (required)
+- `query_type` — one of the types above (required)
+- `depth` — traversal hops, default 2 (higher = slower but reveals indirect deps)
+
+### 3. Interpret results
+
+- **High in_degree** (many callers) → widely-used symbol; changes have large blast radius
+- **High out_degree** (many callees) → complex function; candidate for refactoring
+- **Deep class hierarchy** → check for Liskov violations or fragile base class issues
+- **Cross-repo API callers** → changes require coordination with other teams/services
+
+### 4. Follow up
+
+After understanding relationships, consider:
+- `get_impact` to quantify the blast radius of a change
+- `get_evolution` to see how this symbol has changed over time
+- `find_dead_code` if you found unreferenced symbols
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Need broad context fast | Use `get_symbol_context` (one call, full picture) |
+| Need specific relationship at depth >2 | Use `analyze_relationships` with custom depth |
+| Symbol has many callers | Follow up with `get_impact` before modifying |
+| Found cross-repo API callers | This is a service boundary — coordinate changes |

package/installer/skills/commands/memtrace-search.md

@@ -0,0 +1,67 @@
+---
+name: memtrace-search
+description: "Use when the user asks to find code, search for a function, locate a symbol, look up where something is defined, search across repos, find implementations, or needs to discover where a piece of logic lives before making changes"
+allowed-tools:
+  - mcp__memtrace__find_code
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Find code using hybrid BM25 full-text + semantic vector search with Reciprocal Rank Fusion. Works for both natural-language queries and exact symbol names. This is the primary discovery tool — use it before calling relationship or impact analysis tools.
+
+## Quick Reference
+
+| Tool | Best For |
+|------|----------|
+| `find_code` | Natural-language queries ("authentication middleware", "retry logic"), broad searches |
+| `find_symbol` | Exact identifier names ("getUserById", "PaymentService"), when you know the name |
+
+## Steps
+
+### 1. Choose the right search tool
+
+- **Know the exact name?** → Use `find_symbol` with `fuzzy: true` for typo tolerance
+- **Describing behaviour?** → Use `find_code` with a natural-language query
+- **Searching all repos?** → Omit `repo_id` from either tool
+
+### 2. Execute the search
+
+> **Parameter types:** numbers must be JSON numbers, not strings. `limit: 20` is correct; `limit: "20"` returns `MCP error -32602: expected usize`.
+
+**`find_code` parameters:**
+- `query` — string, required. Natural-language or exact text.
+- `repo_id` — string, optional. Scope to a single repo (omit to search all).
+- `kind` — string, optional. Filter by symbol type: `"Function"`, `"Class"`, `"Method"`, `"Interface"`, `"APIEndpoint"`, `"APICall"`.
+- `limit` — **integer**, optional. Max results. Default `20`, capped at `100`.
+- `as_of` — string, optional. ISO-8601 timestamp for time-travel search (e.g. `"2026-04-01T00:00:00Z"`).
+- `file_path` — string, optional. File path or directory substring to constrain results (e.g. `"cli/commands"` or `"auth.py"`).
+
+**`find_symbol` parameters:**
+- `name` — string, required. Exact or partial symbol name (e.g. `"ValidateToken"`).
+- `fuzzy` — boolean, optional. Enable Levenshtein correction. Default `false`.
+- `edit_distance` — **integer**, optional. Maximum Levenshtein edit distance for fuzzy search. Default `2`, capped at `2`.
+- `repo_id` — string, optional. Scope to a single repo.
+- `kind` — string, optional. Filter by symbol type (e.g. `"Function"`, `"Class"`, `"Variable"`).
+- `file_path` — string, optional. Filter by file path substring.
+- `limit` — **integer**, optional. Max results. Default `10`, capped at `50`.
+
+**Success criteria:** Results include `file_path`, `start_line`, `kind`, and relevance `score`.
+
+### 3. Use results for next steps
+
+Save the symbol `id` from results — pass it to:
+- `analyze_relationships` to map callers/callees
+- `get_symbol_context` for a 360-degree view
+- `get_impact` to assess blast radius before changes
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Searching without indexing first | Call `list_indexed_repositories` to verify the repo is indexed |
+| Using find_symbol for vague queries | Use `find_code` for natural-language; `find_symbol` is for exact names |
+| Ignoring the `kind` filter | Narrow results with kind=Function, kind=Class etc. to reduce noise |
+| Re-searching to get more context | Use the symbol `id` with `get_symbol_context` instead of re-searching |

package/installer/skills/workflows/memtrace-change-impact-analysis.md

@@ -0,0 +1,85 @@
+---
+name: memtrace-change-impact-analysis
+description: "Use when the user is about to modify code, planning a refactoring, wants to know what will break, needs a pre-change risk assessment, is reviewing a PR, or wants to understand the full consequences of a code change before making it"
+allowed-tools:
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, and produces a risk-rated change plan.
+
+## Steps
+
+### 1. Identify what's being changed
+
+Find the target symbol(s):
+- Use `find_symbol` if the user named specific functions/classes
+- Use `find_code` if the user described behaviour ("the authentication middleware")
+
+Collect symbol IDs for all targets.
+
+### 2. Get 360° context for each target
+
+For each symbol, call `get_symbol_context`:
+- Direct callers and callees
+- Community membership (which module is this in?)
+- Process membership (which execution flows does this participate in?)
+- Cross-repo API callers (is this an endpoint called by other services?)
+
+**Decision:** If cross-repo API callers exist, this change requires coordination with other teams. Flag this immediately.
+
+### 3. Compute blast radius
+
+For each target, call `get_impact` with `direction: both`:
+- Upstream impact: what depends on this symbol
+- Downstream impact: what this symbol depends on
+- Risk rating: Low / Medium / High / Critical
+
+**Decision:**
+| Risk | Action |
+|------|--------|
+| Low | Proceed with standard testing |
+| Medium | Review all direct callers; test affected processes |
+| High | Plan incremental migration; consider feature flags |
+| Critical | Full migration strategy; backward-compatible changes required |
+
+### 4. Check temporal stability
+
+Call `get_evolution` with mode `novel` for a 30-day window on the repo:
+- Are any of the target symbols flagged as "rarely changing"? If so, this change is structurally surprising and deserves extra scrutiny.
+- Have the target symbols been changing frequently? High churn + high impact = volatile hotspot.
+
+### 5. Map affected execution flows
+
+From step 2, you already know which processes are affected. For critical changes, use `analyze_relationships` with `query_type: find_callers` at `depth: 3` to trace the full transitive caller chain.
+
+### 6. Produce the risk assessment
+
+Synthesize into a change plan:
+
+1. **Target(s)** — what's being changed and where
+2. **Blast Radius** — number of direct/transitive dependents, risk rating
+3. **Affected Processes** — which execution flows will be impacted
+4. **Cross-Service Impact** — any external callers or consumers
+5. **Stability Signal** — is this code stable (novel) or volatile (frequent changes)?
+6. **Recommended Approach** — based on risk: direct change, incremental migration, or backward-compatible evolution
+7. **Test Coverage** — which callers/processes to verify after the change
+
+## Decision Points
+
+| Condition | Action |
+|-----------|--------|
+| Risk = Critical | Recommend backward-compatible change + deprecation path |
+| Cross-repo callers exist | Flag as requiring multi-service coordination |
+| Symbol has high novelty score | Extra review — this rarely changes; make sure the change is intentional |
+| Multiple processes affected | List each affected flow; recommend testing each one |
+| Symbol is a bridge point | Change may disconnect parts of the architecture — verify alternative paths exist |

package/installer/skills/workflows/memtrace-codebase-exploration.md

@@ -0,0 +1,108 @@
+---
+name: memtrace-codebase-exploration
+description: "Use when the user asks to explore a codebase, understand a project, onboard to a new repo, get an overview of how code is structured, map the architecture, or wants a comprehensive understanding of a codebase they're new to"
+allowed-tools:
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__check_job_status
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_repository_stats
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__list_processes
+  - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__find_bridge_symbols
+  - mcp__memtrace__find_api_endpoints
+  - mcp__memtrace__get_api_topology
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__find_most_complex_functions
+user-invocable: true
+---
+
+## Overview
+
+Full codebase exploration workflow — from indexing through architectural understanding. Chains indexing, graph algorithms, community detection, and temporal analysis into a structured onboarding experience. Use this when someone is new to a codebase and needs to build a mental model.
+
+## Steps
+
+### 1. Index the codebase
+
+Call `list_indexed_repositories` first. If the repo is already indexed, skip to step 2.
+
+Otherwise, call `index_directory` with the project path, then poll `check_job_status` until completion.
+
+**Success criteria:** Repo appears in `list_indexed_repositories` with non-zero node/edge counts.
+
+### 2. Get the lay of the land
+
+Call `get_repository_stats` to understand scale:
+- How many functions, classes, methods, interfaces?
+- How many relationships (calls, imports, extends)?
+- How many communities and processes were detected?
+
+Report these numbers to the user — they set expectations for the codebase's size and complexity.
+
+### 3. Map the architecture (communities)
+
+Call `list_communities` to see how the codebase naturally clusters into logical modules.
+
+**Decision:** If >10 communities, summarize the top 5–7 by size and let the user ask about specific ones.
+
+Each community represents a cohesive module — these are the "areas" of the codebase.
+
+### 4. Find the most important symbols
+
+Call `find_central_symbols` with `method: "pagerank"` and `limit: 15`.
+
+These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.
+
+### 5. Find architectural bottlenecks
+
+Call `find_bridge_symbols` to identify chokepoints — symbols that connect otherwise-separate parts of the codebase.
+
+**Decision:** If bridge symbols overlap heavily with central symbols, flag them as critical infrastructure — high importance AND single point of failure.
+
+### 6. Map execution flows
+
+Call `list_processes` to discover entry points:
+- HTTP handlers (API endpoints)
+- Background jobs
+- CLI commands
+- Event handlers
+
+This shows HOW the code is actually used at runtime, not just how it's structured.
+
+### 7. Map the API surface (if applicable)
+
+Call `find_api_endpoints` to list all HTTP routes.
+
+**Decision:** If multiple repos are indexed, also call `get_api_topology` to map service-to-service dependencies.
+
+### 8. Recent activity
+
+Call `get_evolution` with mode `overview` and a 30-day window to see which modules have been most active recently.
+
+**Decision:** If the user asks about specific recent changes, switch to mode `compound` for symbol-level detail.
+
+### 9. Complexity hotspots
+
+Call `find_most_complex_functions` with `limit: 10` to identify potential technical debt.
+
+## Report Synthesis
+
+Synthesize findings into a structured overview:
+
+1. **Scale** — languages, total symbols, total relationships
+2. **Architecture** — main communities/modules and what they do
+3. **Critical Infrastructure** — central symbols and bridge points
+4. **Execution Flows** — how the code is entered and used
+5. **API Surface** — endpoints and service dependencies
+6. **Recent Activity** — what's been changing in the last 30 days
+7. **Technical Debt** — complexity hotspots and potential dead code
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Skipping indexing and using file-based grep | The knowledge graph provides structural understanding that grep cannot — callers, callees, communities, processes |
+| Reporting raw numbers without interpretation | "450 functions across 12 communities" means nothing; describe what each community does |
+| Only looking at code structure | Execution flows (processes) show how the code is actually used — always include them |
+| Ignoring temporal context | Recent evolution shows where active development is happening — this is where the user will likely need to work |

package/installer/skills/workflows/memtrace-episode-replay.md

@@ -0,0 +1,100 @@
+---
+name: memtrace-episode-replay
+description: "Use when an agent needs to understand why code looks the way it does, replay implementation steps between commits, find what was tried and reverted, understand a colleague's (or your past self's) reasoning, or avoid repeating a previously-abandoned approach"
+allowed-tools:
+  - mcp__memtrace__get_episode_replay
+  - mcp__memtrace__get_timeline
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Replay the sub-commit implementation narrative for any symbol. Between any two commits, Memtrace recorded every file save as a `working_tree` episode. This tool surfaces that sequence — the attempts, the reversions, the iterative refinements — not just the final committed state.
+
+**Git shows A→B. Episode replay shows every step in between.**
+
+This is the only tool that can answer: "why does this code look like this?" without relying on commit messages or comments.
+
+## Steps
+
+### 1. Identify the symbol and time window
+
+Use `find_symbol` to get the exact symbol name if needed. Determine the window:
+- `from` — when to start (e.g. a few days before a confusing commit)
+- `to` — when to end (usually the commit timestamp or now)
+
+If you don't know the window, call `get_timeline` first to find when the symbol changed.
+
+### 2. Call `get_episode_replay`
+
+```
+get_episode_replay(
+  repo_id: "...",
+  symbol: "execute",
+  from: "2026-04-10T00:00:00Z",
+  to:   "2026-04-13T00:00:00Z",
+  include_working_tree: true,   // false = commits only
+  compress: true                // collapse identical-hash runs
+)
+```
+
+### 3. Read the narrative_hint sequence
+
+Each episode has a `narrative_hint` — derived automatically from AST hash patterns:
+
+| Hint | What it means |
+|---|---|
+| `committed` | A real git commit — the "public record" checkpoint |
+| `pre_commit_finalization` | Last working_tree save before a commit — the final draft |
+| `iterative_refinement` | 3+ consecutive working_tree saves — active development in progress |
+| `attempted_and_reverted` | Hash returned to a prior state — something was tried and backed out |
+| `no_change` | File was saved but this symbol didn't change |
+| `working_tree_save` | A single file save with structural changes |
+
+### 4. Reconstruct the implementation story
+
+Read the sequence like a narrative:
+
+```
+committed              ← "here's where we started"
+working_tree_save      ← "first attempt"
+iterative_refinement   ← "refining the approach"
+attempted_and_reverted ← "tried X, it was wrong, backed out"
+pre_commit_finalization← "final version before commit"
+committed              ← "here's what shipped"
+```
+
+The gap between `committed` entries is the implementation story.
+
+### 5. Identify what to act on
+
+| Pattern | Implication |
+|---|---|
+| `attempted_and_reverted` appears | There was a tried-and-abandoned approach — understand why before trying similar |
+| Multiple `iterative_refinement` clusters | The author was unsure — this area may need extra care |
+| No working_tree episodes (commits only) | Code was written elsewhere or pasted in — less implementation history available |
+| Very short episode sequence | Straightforward change — low implementation complexity |
+
+## When to Use
+
+- **Before modifying unfamiliar code** — understand the intent, not just the current state
+- **Post-session debugging** — replay what was tried during a broken session
+- **Code review** — understand the reasoning behind non-obvious implementations
+- **Avoiding dead ends** — check if the approach you're about to try was already attempted and reverted
+
+## Compression
+
+With `compress: true` (default), consecutive episodes with identical `ast_hash` are collapsed to first+last of the run. Cosmetic saves and whitespace-only edits are filtered out. Only structurally significant transitions are shown.
+
+With `compress: false`, every single save is shown — useful when you want to see exact timing between saves.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Only reading the final committed code | The commit shows *what*, the episode replay shows *why* — always check both for unfamiliar code |
+| Ignoring `attempted_and_reverted` hints | These are the most valuable entries — they represent knowledge about what doesn't work |
+| Using `include_working_tree: false` by default | Commits-only loses all the sub-commit narrative — only use this if you explicitly want commit-level granularity |
+| Large windows with compress off | Very long histories produce noise; use `compress: true` unless you need exact save-by-save granularity |