/memtrace-episode-replay

name: memtrace-episode-replay
description: "Replay the graph diff of one episode — a single git commit or working-tree save — to inspect what it changed: added/modified/removed symbols and edges. Use when the user asks what one commit or save changed in the graph, why code looks this way, or wants to inspect implementation attempts, reversions, past reasoning, or abandoned approaches across commits and working-tree episodes. Do not use git log or Grep for graph-level episode diffs; Memtrace replays indexed episode records. Do NOT use for module-level summaries or date-range change history — use memtrace-evolution."

Overview

Replay the graph diff for **one episode** (a single git commit or working-tree save). Shows which nodes/edges were added, modified, or removed in that episode — not a multi-episode time-range narrative.

Use `get_evolution(mode: "recent")` to **find** episode IDs and timestamps, then drill into a specific episode with this tool.

Episode selector — pick one

| Approach | Parameters | |---|---| | Known episode UUID | `episode_id` | | Newest episode in repo | `repo_id` + `episode_index: 0` | | Nth newest | `repo_id` + `episode_index: N` |

**There is no `from` / `to` / `include_working_tree` on this tool.**

Optional filters (large commits)

| Param | Purpose | |---|---| | `symbol` | Scope to one symbol name | | `file_path` | Substring filter on record paths | | `kind` | e.g. `"Function"`, `"CALLS"` | | `mode` | `"graph_summary"` for digest on huge commits | | `compress` | default `true` — collapse identical-hash modifications | | `limit` / `cursor` | Pagination per bucket (default limit 200) |

Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).

Steps

1. Find the episode to inspect

From `get_evolution`:

{ "repo_id": "memdb", "from": "7d ago", "mode": "recent", "limit": 20 }

Each entry has `episode` metadata including `id` (use as `episode_id`) and `reference_time`.

Or use `episode_index: 0` for the newest episode without knowing the UUID.

2. Call `get_episode_replay`

By episode UUID:

{
  "episode_id": "550e8400-e29b-41d4-a716-446655440000",
  "symbol": "execute",
  "file_path": "src/order/service.rs",
  "kind": "Function",
  "compress": true,
  "limit": 200
}

Newest episode, summary first on large commits:

{
  "repo_id": "memdb",
  "episode_index": 0,
  "mode": "graph_summary"
}

3. Interpret the response

| Field | Meaning | |---|---| | `found` | `false` if episode missing — check `_note` | | `totals` | Counts: `nodes_added/modified/removed`, `edges_*` | | `nodes_added[]` etc. | Per-record diffs (paginated) | | `page.next_cursor` | More records remain — pass as `cursor` |

For symbol history **across many episodes**, use `get_timeline` instead:

{
  "repo_id": "memdb",
  "scope_path": "OrderService.execute",
  "file_path": "src/order/service.rs"
}

Output

`get_episode_replay` returns the buckets interpreted in step 3:

{
  "found": true,
  "totals": { "nodes_added": 3, "nodes_modified": 12, "nodes_removed": 1, "edges_added": 7, "edges_removed": 2 },
  "nodes_added": [ /* per-record diffs, paginated per bucket */ ],
  "nodes_modified": [ /* … */ ],
  "edges_removed": [ /* … */ ],
  "page": { "next_cursor": 200 }
}

Common Mistakes

| Mistake | Reality | |---------|---------| | Passing `from` / `to` time window | Not supported — one episode per call | | Expecting `narrative_hint` / `attempted_and_reverted` | Not in API — inspect added/modified/removed buckets | | Unfiltered replay on 10k-symbol commits | Use `kind`, `file_path`, `symbol`, or `mode: "graph_summary"` first | | Using this for "what changed last week?" or module summaries | Use memtrace-evolution — `get_evolution(from=..., mode: recent)` — to list episodes |