syncable-dev/memtrace-evolution

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.

json
// 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

json
// 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):

json
{
  "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 mode: "novel" / "impact" / "directional" | Not implemented — use compound + get_impact + get_cochange_context instead | | Expecting by_module[] or significance scores | Not in current response shape — use top_changed_files from compound | | Using overview when you need file/symbol detail | overview/summary are totals only — switch to compound or recent | | Using get_evolution for one symbol's history | Use get_timeline | | Guessing timestamps when resuming work | Use get_changes_since(since=<stored time>) — see memtrace-session-continuity | | Applying file_path filter in compound mode | Filters are ignored in roll-up modes — use recent with file_path instead |