/memtrace-evolution

name: memtrace-evolution
description: "Trace source-code change history from Memtrace's symbol-level temporal memory. Use when the user asks about change history, recent modifications, what changed since a date, symbol timeline, evolution, unexpected changes, or incident timelines. Do not use git log, git diff, Grep, or manual file search to reconstruct history. Do NOT use for current-state architecture overviews (use memtrace-codebase-exploration) or for replaying one commit/save's graph diff (use memtrace-episode-replay)."

Overview

Temporal analysis for "what changed in this repo between two points in time?" Works on both git commits and uncommitted working-tree saves.

Required parameters — read before calling

`get_evolution` **always** requires `repo_id` and `from`. There is no `days` parameter.

| Parameter | Required | Type | Example | |---|---|---|---| | `repo_id` | yes | string | `"memdb"` | | `from` | yes | string | `"90d ago"`, `"2026-04-01T00:00:00Z"`, `"yesterday"` | | `to` | no | string | defaults to now; set to incident time when investigating | | `mode` | no | string | `"recent"` (default), `"compound"`, `"summary"`, `"overview"` | | `target` | no | string | symbol name or file path substring to scope results | | `branch` | no | string | branch filter |

> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `cursor`, etc.) must be JSON numbers — not strings. Use `limit: 100`, never `limit: "100"`.

Time-window parameters — do not confuse these tools

| Tool | Time param | Example | Notes | |---|---|---|---| | `get_evolution` | **`from`** (required) | `"90d ago"` | optional `to`; **never** pass `days` | | `get_changes_since` | **`since`** (required) | `"2026-04-13T10:43:00Z"` | optional `until` | | `replay_history` | **`days`** (optional) | `90` | re-walks git history — different tool entirely |

Common failure: `MCP error -32602: missing field 'from'` — you omitted `from` or passed `days` instead.

// CORRECT — 90-day overview
{ "repo_id": "memdb", "from": "90d ago", "mode": "overview" }

// WRONG — days is not a get_evolution parameter
{ "repo_id": "memdb", "days": 90, "mode": "overview" }

Query modes — only these four exist

| Mode | What you get | Best for | |---|---|---| | `recent` | Per-episode list with nodes/edges added/removed; paginate with `limit` + `cursor` | Incident timelines, walking commit-by-commit | | `compound` | Totals plus `top_changed_files` and `top_touched_symbols` | "What changed?" when you need hotspots | | `summary` | Totals plus `first_episode` / `last_episode` metadata | Cheapest window check | | `overview` | Alias for `summary` | Same as `summary` |

Modes **`impact`**, **`novel`**, and **`directional`** are **not implemented** — calling them returns `unknown mode`.

`recent` mode filters (ignored by `compound` / `summary`)

| Param | Purpose | |---|---| | `file_path` | substring match against episode `touched_files` | | `kind` | `"git_commit"` or `"working_tree"` | | `limit` | page size (default 100 episodes) | | `cursor` | pagination offset; follow `next_cursor` in response |

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

Steps

1. Get `repo_id`

list_indexed_repositories()

2. Choose the time window

• `from` — start (required). Relative strings work: `"7d ago"`, `"24 hours ago"`.
• `to` — end (optional, defaults to now). Set to the incident timestamp when investigating regressions.

If resuming a session and you have a stored timestamp from last time, prefer `get_changes_since(since=...)` — see `memtrace-session-continuity`.

3. Choose the mode

User wants...
├── per-commit / per-save changelog     → recent
├── top changed files + symbols         → compound
├── quick totals only                   → summary or overview
└── one symbol's full history           → get_timeline (not get_evolution)

4. Execute

// General "what changed lately?"
{ "repo_id": "memdb", "from": "30d ago", "mode": "compound" }

// Changes in one file last week
{ "repo_id": "memdb", "from": "7d ago", "mode": "recent", "file_path": "auth.ts", "limit": 50 }

// Incident: 24h before failure until failure time
{ "repo_id": "memdb", "from": "2026-04-16T13:00:00Z", "to": "2026-04-17T13:00:00Z", "mode": "recent" }

5. Interpret results

**`recent` mode** — each entry in `episodes[]`:

• `episode` — metadata (`source_type`, `reference_time`, `touched_files`, …)
• `nodes_added`, `nodes_removed`, `edges_added`, `edges_removed`

**`compound` mode:**

• `totals` — aggregate counts
• `top_changed_files` — files with most activity
• `top_touched_symbols` — symbols with most activity

**`summary` / `overview` mode:**

• `totals` — episode and node/edge counts
• `first_episode`, `last_episode` — window boundaries

6. Drill deeper

| Need | Tool | |---|---| | Full history of one symbol | `get_timeline(repo_id, scope_path, file_path)` | | Blast radius of a suspect symbol | `get_impact(repo_id, target)` | | What a diff would affect | `detect_changes(repo_id, diff=...)` | | Behavioral coupling | `get_cochange_context(repo_id, target=<symbol>)` | | Sub-commit tried-and-reverted history | `get_episode_replay` |

Output

Sample `compound` payload (per-mode field lists: step 5 above):

{
  "totals": { "episodes": 42, "nodes_added": 310, "nodes_removed": 95,
              "edges_added": 541, "edges_removed": 120 },
  "top_changed_files":   [ /* files ranked by activity */ ],
  "top_touched_symbols": [ /* symbols ranked by activity */ ]
}

`recent` returns `episodes[]` + `totals` + `page.next_cursor`; `summary`/`overview` return `totals` + `first_episode`/`last_episode`.

Common mistakes

| Mistake | Reality | |---|---| | Passing `days: 90` | Use `from: "90d ago"` — `days` is only on `replay_history` | | Omitting `from` | Required — call fails with `-32602` before any query runs | | Using