memtrace 0.7.25 → 0.8.1

package/installer/skills/workflows/memtrace-fleet-coordination.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-fleet-coordination
-description: "Use when you need to understand or act on fleet conflict resolution: what conflict class A/B/C means, how a Class C destructive overlap gets decided (by an agent judge or a human), how to be the judge (fleet_submit_verdict), how to read your directive after a decision, and how branch-scoping isolates fleets. Triggered by: 'two agents are changing the same thing', 'resolve this conflict', 'who should proceed', 'a decision is waiting', acting as a mediator between agents."
+description: "Resolve fleet conflicts between coordinated agents: what conflict class A/B/C means, how a Class C destructive overlap gets decided (by an agent judge or a human), how to be the judge (fleet_submit_verdict), how to read your directive after a decision, and how branch-scoping isolates fleets. Use when the user says 'two agents are changing the same thing', 'resolve this conflict', 'who should proceed', 'a decision is waiting', or asks you to act as a mediator between agents. This skill explains the conflict model and decision loop; for just the verdict/directive/resolution tool calls on a specific escalation, use memtrace-fleet-resolve."
 allowed-tools:
   - mcp__memtrace__fleet_record_episode
   - mcp__memtrace__fleet_submit_verdict
@@ -8,6 +8,10 @@ allowed-tools:
   - mcp__memtrace__fleet_list_escalations
   - mcp__memtrace__fleet_resolve_escalation
   - mcp__memtrace__fleet_get_node_state
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 ---
 
 # Fleet Coordination
@@ -52,6 +56,8 @@ fleet_submit_verdict({
 Verdict kinds: `reconcile {merge_plan}` · `recommend {winner, rationale, confidence}`
 · `defer_to_human {question}`.
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 The referee then decides the outcome:
 - **Auto-apply** only when safe: the clear machine case, or ≥2 independent agents
   agree — and **never** for a destructive *removal* (delete/move), which always
@@ -85,3 +91,17 @@ one session branch and conflicts stay real and resolvable.
 `fleet_get_node_state({repo_id, node})` — recent episodes, active intents, dominant
 intent, and conflict density for one symbol. Use it to understand pressure on a
 hot symbol before you pile on.
+
+## Output
+
+`fleet_record_episode` on a destructive overlap, then `fleet_get_escalation` once decided:
+
+```jsonc
+// fleet_record_episode
+{ "conflict_class": "C", "escalation_id": "01J…",
+  "mediation_request": { /* every agent's assignment + the contested symbols */ } }
+
+// fleet_get_escalation — poll until your_directive ≠ "wait"
+{ "your_directive": "defer",
+  "resolution": "recommend: agent-b — rebase the fix onto the signature change" }
+```

package/installer/skills/workflows/memtrace-fleet-first.md

@@ -1,13 +1,19 @@
 ---
 name: memtrace-fleet-first
-description: "Always use FIRST when more than one coding agent works the same repo+branch at once (a 'fleet'), before reading code, planning a refactor, or making an edit. Triggered by: 'I'm about to edit X', 'rename Y across the codebase', joining a running fleet/session branch, coordinating with other agents, prose hand-offs. Do not grep for 'who else is touching this' and do not skip fleet_publish_intent because 'it's a small change'. Fleet coordination is branch-scoped: pass your session branch so your fleet coordinates and stays isolated from agents on other branches. Skip ONLY for genuinely solo sessions or pure docs-only edits where coordination has zero value."
+description: "Coordinate fleets of coding agents sharing one repo+branch: declare typed intents, classify edit episodes, and resolve conflicts before they collide. Use FIRST when more than one coding agent works the same repo+branch at once (a 'fleet'), before reading code, planning a refactor, or making an edit — triggered by 'I'm about to edit X', 'rename Y across the codebase', joining a running fleet/session branch, coordinating with other agents, or prose hand-offs. Do not grep for 'who else is touching this' and do not skip fleet_publish_intent because 'it's a small change'. Fleet coordination is branch-scoped: pass your session branch so your fleet coordinates and stays isolated from agents on other branches. Skip ONLY for genuinely solo sessions or pure docs-only edits where coordination has zero value."
 allowed-tools:
   - mcp__memtrace__fleet_status
+  - mcp__memtrace__fleet_branch_context
   - mcp__memtrace__fleet_preflight
   - mcp__memtrace__fleet_publish_intent
   - mcp__memtrace__fleet_record_episode
   - mcp__memtrace__fleet_get_escalation
   - mcp__memtrace__fleet_submit_verdict
+  - mcp__memtrace__fleet_get_node_state
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 ---
 
 # Fleet First
@@ -52,15 +58,24 @@ branch* is how a group of agents opts into one coordinating fleet.
 Always include **`assignment`** — your natural-language task. When a conflict
 happens, that's what the judge (another agent) or a human reads to reconcile.
 
-## Check the fleet first (once per session)
+## Check the fleet first (once per session and after idle)
 
+Set a stable identity before any fleet call:
+
+```
+MEMTRACE_AGENT_ID=<your-agent-id>   # required in fleet / hosted environments
 ```
+
+```
+fleet_branch_context({repo_id, branch, agent_id})
+  → you, peers[], pending_escalations, recent_peer_episodes, graph_revision
 fleet_status()        → live_intents, active_agents, pending_escalations, mediator_mode
 ```
 
-If it responds, fleet coordination is active — follow this skill for every edit.
-An empty fleet is **not** permission to skip: it just means you're the first agent
-in this window.
+Call **`fleet_branch_context`** at session start and after idle periods so you do not
+confuse peer WIP with settled graph truth. If fleet tools respond, coordination is
+active — follow this skill for every edit. An empty peer list is **not** permission
+to skip: it just means you're the first agent in this window.
 
 ## The protocol, step by step
 
@@ -125,8 +140,23 @@ degrades to "a human reviews a suggestion," never a silent bad merge.
 - `touched` is a list of qualified symbol identities (e.g. `"module::Symbol"`).
 - Always include `branch` (your session branch) and `assignment` (your task).
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 ## When to skip
 
 Skip the protocol only for a genuinely **solo** session (you're the only agent and
 no one else shares your branch) or **pure docs-only** edits where coordination has
 zero value. Everything else in a fleet goes through the protocol.
+
+## Output
+
+Key return shapes (fields documented above):
+
+```jsonc
+// fleet_record_episode →
+{ "conflict_class": "C", "escalation_id": "…", "mediation_request": { /* every agent's assignment */ } }
+// fleet_get_escalation →
+{ "your_directive": "wait | proceed | defer | review", "resolution": "free text (read on review)" }
+// fleet_status →
+{ "live_intents": [ /* … */ ], "active_agents": [ /* … */ ], "pending_escalations": [ /* … */ ], "mediator_mode": "…" }
+```

package/installer/skills/workflows/memtrace-incident-investigation.md

@@ -1,24 +1,25 @@
 ---
 name: memtrace-incident-investigation
-description: "Always use for source-code bugs, incidents, regressions, production issues, failures, root cause analysis, what broke, or what changed when debugging. Do not start with Grep, Glob, rg, find, or manual file search for code causes; Memtrace combines symbol search, impact, call graph, and temporal history."
+description: "Investigate source-code bugs, incidents, regressions, production issues, and failures to root cause with Memtrace symbol search, impact, call graph, and temporal history. Use when the user asks about root cause analysis, what broke, or what changed when debugging a failure. Do not start with Grep, Glob, rg, find, or manual file search for code causes. For plain what-changed questions without a failure, use memtrace-evolution."
 allowed-tools:
   - mcp__memtrace__get_evolution
-  - mcp__memtrace__get_timeline
-  - mcp__memtrace__detect_changes
   - mcp__memtrace__get_impact
   - mcp__memtrace__get_symbol_context
-  - mcp__memtrace__find_code
-  - mcp__memtrace__find_symbol
-  - mcp__memtrace__analyze_relationships
-  - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__get_timeline
   - mcp__memtrace__get_episode_replay
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__list_indexed_repositories
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
 ## Overview
 
-Root cause investigation workflow for incidents, regressions, and production issues. Uses temporal analysis with the `recent` scoring mode to surface changes closest to the incident time, then traces blast radius and execution flows to identify the likely cause.
+Root cause investigation workflow for incidents, regressions, and production issues. Uses `get_evolution` to list changes near the incident time, then traces blast radius and execution flows to identify the likely cause.
 
 ## Steps
 
@@ -29,97 +30,154 @@ Determine:
 - **Lookback window** — how far back to search? Start with 24 hours, expand if needed.
 - **Repo(s)** — which services are affected? Call `list_indexed_repositories` to get repo_ids.
 
-### 2. Surface recent changes near the incident
+### 2. List changes near the incident
+
+Call `get_evolution`:
+
+```json
+{
+  "repo_id": "<affected-repo>",
+  "from": "<incident_time minus lookback, e.g. 24h before>",
+  "to": "<incident_time ISO-8601>",
+  "mode": "recent",
+  "limit": 100
+}
+```
+
+**Why `recent` mode?** Returns a chronological per-episode changelog. Focus on episodes whose `reference_time` is closest to the incident — especially those with high `nodes_added` + `nodes_removed` or that touch files in the failure area.
+
+Paginate with `cursor` if `next_cursor` is present in the response.
+
+**Success criteria:** A list of episodes in the window, with touched files and change counts for each.
+
+### 3. Identify hotspot files and symbols
 
-Call `get_evolution` with:
-- `mode: "recent"` — temporal proximity weighting: `impact × exp(−0.5 × Δhours)`
-- `from` — lookback start (e.g., 24 hours before incident)
-- `to` — the incident timestamp
-- `repo_id` — the affected repo
+Call `get_evolution` again on the same window with `mode: "compound"`:
 
-**Why `recent` mode?** It exponentially amplifies changes close to the incident time while still weighting by structural impact. A high-impact change made 1 hour before the incident scores much higher than the same change made 20 hours before.
+```json
+{
+  "repo_id": "<affected-repo>",
+  "from": "<same as step 2>",
+  "to": "<same as step 2>",
+  "mode": "compound"
+}
+```
 
-**Success criteria:** A ranked list of changes, with the most likely culprits at the top.
+Review `top_changed_files` and `top_touched_symbols`. Cross-reference with the failure area (endpoint, module, error stack).
 
-### 3. Check for unexpected changes
+**Decision:** Prioritize symbols/files that appear in both the recent episode list (step 2) and the compound hotspots (step 3).
 
-Call `get_evolution` again with `mode: "novel"` on the same time window:
-- Flags changes to rarely-modified code (high in_degree, low change frequency)
-- A core utility that hasn't changed in 90 days suddenly changing near an incident is a strong signal
+### 4. Check for unexpected changes to stable code
 
-**Decision:** If `novel` mode surfaces different symbols than `recent` mode, investigate both — the root cause may be an unexpected change to stable infrastructure.
+For hotspot symbols from step 3, resolve each with `find_symbol`:
 
-### 4. Trace the blast radius of top suspects
+```json
+{ "repo_id": "<affected-repo>", "name": "<symbol>", "limit": 10 }
+```
 
-For the top 3–5 symbols from steps 2–3, call `get_impact` with `direction: upstream`:
+Then call `get_timeline` — stable code that suddenly changed is suspect:
+
+```json
+{ "repo_id": "<affected-repo>", "scope_path": "<from find_symbol>", "file_path": "<from find_symbol>" }
+```
+
+### 5. Assess the blast radius
+
+For the top 3–5 symbols, call `get_impact`:
+
+```json
+{ "repo_id": "<affected-repo>", "target": "<symbol>", "direction": "upstream" }
+```
 - How many downstream consumers were affected?
 - What execution flows pass through this symbol?
 
 **Decision:** Prioritize symbols where the blast radius overlaps with the reported failure area.
 
-### 5. Trace execution flows
+### 6. Trace execution flows
 
 Use `get_symbol_context` on the top suspects to see which processes (HTTP handlers, background jobs, etc.) they participate in.
 
 **Decision:** If the incident is in a specific endpoint/flow, focus on suspects that are members of that process.
 
-### 6. Build the full timeline for the suspect
+### 7. Build the full timeline for the suspect
 
-Once you have a primary suspect, call `get_timeline` with the symbol name to see its full version history:
-- What changed in each commit?
+Once you have a primary suspect, call `get_timeline` with `repo_id`, `scope_path`, and `file_path`:
+- What changed in each episode?
 - When was the last "stable" version?
 - Was the change a modification, or was it newly added?
 
-### 7. Correlate with surrounding changes
+### 8. Correlate adds vs removes per episode
 
-Call `get_evolution` with mode `directional` to separate:
-- **Added symbols** — new code introduced (potential new bugs)
-- **Removed symbols** — deleted code (potential missing functionality)
-- **Modified symbols** — changed behaviour (potential regressions)
+From the step 2 `recent` response, inspect each episode's `nodes_added` and `nodes_removed`:
+- High `nodes_added` — new code introduced (potential new bugs)
+- High `nodes_removed` — deleted code (potential missing functionality)
+- Both moderate — changed behaviour (potential regressions)
 
-### 8. Check historical coupling (cochange)
+### 9. Check historical coupling (cochange)
 
 For the primary suspect, call `get_cochange_context`:
+
+```json
+{ "repo_id": "<affected-repo>", "target": "<symbol>", "limit": 10 }
+```
 - Which symbols historically co-change with this one?
 - If the blast radius from `get_impact` doesn't explain the failure area, check cochange partners — the coupling may be behavioral, not structural.
 
 **Decision:** If a cochange partner is in the failure area but has no direct call relationship to the suspect, it's a hidden dependency — investigate both.
 
-### 9. Replay the sub-commit implementation history (if needed)
+### 10. Replay the sub-commit implementation history (if needed)
+
+If the suspect's episode isn't clear, call `get_episode_replay`:
 
-If the suspect's commit history doesn't explain the intent, call `get_episode_replay`:
-- What was tried before the final committed state?
-- Was any approach attempted and reverted in the same session?
-- The `attempted_and_reverted` hint often explains why seemingly-correct code was changed to something subtler.
+```json
+{
+  "repo_id": "<affected-repo>",
+  "episode_index": 0,
+  "symbol": "<suspect>",
+  "mode": "graph_summary"
+}
+```
+
+- Look for `attempted_and_reverted` hints — approaches tried and rolled back within the episode often explain why the committed state looks the way it does.
 
 ## Report: Root Cause Analysis
 
 1. **Incident Timeline** — when it started, what was observed
-2. **Most Likely Cause** — the top-ranked change(s) by `recent` mode with blast radius confirmation
-3. **Supporting Evidence** — novelty signal (was this an unexpected change?), blast radius overlap with failure area, process membership overlap
+2. **Most Likely Cause** — episodes and symbols closest to the incident with blast radius confirmation
+3. **Supporting Evidence** — timeline sparsity (stable code suddenly changed?), blast radius overlap, process membership overlap
 4. **Change History** — full timeline of the suspect symbol
 5. **Affected Scope** — all processes and downstream consumers impacted
 6. **Remediation** — revert the change, fix forward, or mitigate
 
-## Algorithm Selection Guide for Incidents
+## Tool selection guide for incidents
+
+| Phase | Tool / mode | Why |
+|---|---|---|
+| Initial triage | `get_evolution` `recent` | Per-episode changelog near the incident |
+| Hotspot identification | `get_evolution` `compound` | Top changed files and symbols in the window |
+| Scope assessment | `get_impact` | Blast radius of suspect symbols |
+| Hidden coupling | `get_cochange_context` | Behavioral coupling not in the call graph |
+| Symbol history | `get_timeline` | Full version history of a suspect |
+| Sub-commit intent | `get_episode_replay` | What was tried before the committed state |
+| Quick window check | `get_evolution` `overview` | Totals only — use before narrowing the window |
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Output
+
+The deliverable is the RCA report above. Abridged example (3 of 6 sections filled):
 
-| Phase | Tool / Mode | Why |
-|-------|-------------|-----|
-| Initial triage | `get_evolution` `recent` | Time-weighted ranking surfaces changes near the incident |
-| Anomaly detection | `get_evolution` `novel` | Catches unexpected changes to stable code |
-| Scope assessment | `get_impact` | Ranks by structural significance (blast radius) |
-| Hidden coupling | `get_cochange_context` | Surfaces behavioral coupling not in the call graph |
-| Direction analysis | `get_evolution` `directional` | Separates added/removed/modified |
-| Sub-commit intent | `get_episode_replay` | Reveals what was tried before the committed state |
-| Quick summary | `get_evolution` `overview` | Fast module-level scan before deep-diving |
+- **Most Likely Cause** — episode `2026-07-01T14:22Z` modified `AuthService::validateToken`; upstream blast radius reaches the failing `/api/login` process
+- **Supporting Evidence** — symbol was stable for 90 days before this episode; cochange partner `token_cache.rs` changed in the same window despite no call edge
+- **Remediation** — revert the episode, or fix forward with an expiry guard
 
-## Common Mistakes
+## Common mistakes
 
 | Mistake | Reality |
-|---------|---------|
-| Starting with `impact` mode | Use `recent` first — time proximity is the strongest signal for incidents |
-| Only looking at the most recent commit | The root cause may be from an earlier change whose effects were delayed |
-| Ignoring `novel` mode | Unexpected changes to stable code are often the root cause |
+|---|---|
+| Omitting `from` or passing `days` | Always pass `from` (e.g. `"24 hours ago"`) — never `days` |
+| Using `mode: "novel"` or `"directional"` | Not implemented — use `compound` + `get_timeline` + `get_cochange_context` |
+| Only looking at the most recent commit | The root cause may be from an earlier episode whose effects were delayed |
 | Not checking blast radius overlap | A change is only a suspect if its blast radius reaches the failure area |
 | Stopping at call graph analysis | `get_cochange_context` finds hidden coupling — symbols that move together without calling each other |
 | Reading only committed code | `get_episode_replay` reveals tried-and-reverted approaches that explain the current implementation |

package/installer/skills/workflows/memtrace-refactoring-guide.md

@@ -1,18 +1,19 @@
 ---
 name: memtrace-refactoring-guide
-description: "Always use when the user wants to refactor source code, reduce complexity, clean technical debt, split large functions, extract modules, reorganize code, or choose refactoring priorities. Do not use Grep or manual reference search to plan refactors; Memtrace provides complexity, dead-code, relationships, and impact context."
+description: "Build a phased, risk-scored refactoring plan from Memtrace complexity, dead-code, bridge, and impact analysis. Use when the user wants to refactor source code, reduce complexity, clean technical debt, split large functions, extract modules, reorganize code, or choose refactoring priorities. Do not use Grep or manual reference search to plan refactors; Memtrace provides complexity, dead-code, relationships, and impact context."
 allowed-tools:
   - mcp__memtrace__find_most_complex_functions
   - mcp__memtrace__find_dead_code
   - mcp__memtrace__find_bridge_symbols
-  - mcp__memtrace__find_central_symbols
-  - mcp__memtrace__get_symbol_context
-  - mcp__memtrace__get_impact
   - mcp__memtrace__get_evolution
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__get_symbol_context
   - mcp__memtrace__analyze_relationships
   - mcp__memtrace__list_communities
-  - mcp__memtrace__calculate_cyclomatic_complexity
-  - mcp__memtrace__list_indexed_repositories
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
@@ -27,7 +28,7 @@ Guided refactoring workflow — identifies refactoring candidates using structur
 Run these three tools in parallel to build a candidate list:
 
 **a) Complexity hotspots:**
-Call `find_most_complex_functions` with `limit: 20`
+Call `find_most_complex_functions` with `top_n: 20`
 
 **b) Dead code:**
 Call `find_dead_code` to find unused symbols
@@ -37,7 +38,9 @@ Call `find_bridge_symbols` to find chokepoints with too much responsibility
 
 ### 2. Score candidates by volatility
 
-Call `get_evolution` with mode `compound` over a 90-day window:
+Call `get_evolution` with `from: "90d ago"` and `mode: "compound"`.
+
+Review `top_touched_symbols` and `top_changed_files`:
 - Symbols that are BOTH complex AND frequently changing are the highest priority
 - Complex but stable code can wait — it's not causing active pain
 - Volatile but simple code may be fine — frequent changes to simple code is normal
@@ -63,9 +66,11 @@ Also call `get_symbol_context` to check:
 ### 4. Understand the neighbourhood
 
 For each refactoring target, call `analyze_relationships`:
-- `find_callees` — what does it depend on? (these become candidates for extraction)
-- `find_callers` — what depends on it? (these need updating after refactoring)
-- `class_hierarchy` — is it part of an inheritance chain? (Liskov concerns)
+- `find_callees` — what does it depend on? These become candidates for extraction
+- `find_callers` — what depends on it? These need updating after refactoring
+- `class_hierarchy` — is it part of an inheritance chain? Liskov concerns
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ### 5. Check community boundaries
 
@@ -106,6 +111,21 @@ For each item, include:
 | Bridge symbol with many dependents | Extract interface first, then refactor implementation behind it |
 | Symbol in cross-repo API | Coordinate with consumers; backward-compatible changes only |
 
+## Output
+
+A phased plan (Phases 1–3). One worked entry:
+
+| Field | Example |
+|---|---|
+| Target | `process_payment` — `src/billing/processor.py`, complexity 38 |
+| Why | Complex + volatile (14 changes/90d in `top_touched_symbols`) + 23-symbol blast radius |
+| First move | Extract validation branch to `validate_payment_request`; keep callers untouched |
+| Risk | High — upstream spans 3 processes incl. `checkout_flow`; incremental migration |
+
+Acceptance criteria:
+- Every plan item cites complexity, volatility, and blast radius — no gut-feel picks.
+- High/Critical-risk items include a test plan naming affected callers/processes.
+
 ## Common Mistakes
 
 | Mistake | Reality |

package/installer/skills/workflows/memtrace-session-continuity.md

@@ -1,98 +1,112 @@
 ---
 name: memtrace-session-continuity
-description: "Always use at session start or resume when the user asks to continue, catch up, see what changed while away, recover prior context, or orient without guessing timestamps in an indexed source-code repo. Do not use git log, Grep, or manual file search for catch-up; Memtrace provides session anchors and change memory."
+description: "Catch up on everything that changed in an indexed source-code repo since the last session, using stored session anchors and Memtrace change memory. Use when the user asks to continue, catch up, resume, see what changed while away, recover prior context, or orient at session start without guessing timestamps. Do not use git log, Grep, or manual file search for catch-up; Memtrace provides session anchors and change memory."
 allowed-tools:
   - mcp__memtrace__get_changes_since
   - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__get_evolution
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
 user-invocable: true
 ---
 
 ## Overview
 
-Session continuity for agents. Instead of guessing a time window and blindly running `get_evolution`, pass a `session_anchor` from your last session and get back exactly what changed — nothing more. The response returns a new anchor to persist for next time.
+Session continuity for agents. Store a timestamp from your last session and call `get_changes_since` to see exactly what happened since then — then drill into details with `get_evolution` if needed.
 
-**Core principle:** Agents track a cursor, not a clock. Never guess timestamps.
+**Core principle:** Persist a `since` timestamp (or the `until` from your last catch-up call). Never invent a `days` parameter.
 
 ## Steps
 
 ### 1. Find or bootstrap the session anchor
 
-Look for a stored `session_anchor` from your last session:
+Look for a stored anchor from your last session:
 
 ```json
 {
-  "last_episode_id": "ep_abc123",
-  "last_reference_time": "2026-04-13T10:43:00Z"
+  "repo_id": "memdb",
+  "since": "2026-04-13T10:43:00Z"
 }
 ```
 
-If you have no anchor yet (first run), call `list_indexed_repositories`. Each repo now includes `last_episode_id`, `last_episode_time`, and `last_episode_type` — use `last_episode_id` as your bootstrap anchor.
+If you have no anchor yet (first run), call `list_indexed_repositories`. Use `last_episode_time` from the repo entry as a bootstrap `since` value, or ask the user how far back to look.
 
 ### 2. Call `get_changes_since`
 
+```json
+{
+  "repo_id": "memdb",
+  "since": "2026-04-13T10:43:00Z"
+}
 ```
-get_changes_since(
-  repo_id: "...",
-  last_episode_id: "ep_abc123"      // preferred — exact episode boundary
-  // OR
-  last_reference_time: "2026-04-13T10:43:00Z"   // fallback
-)
-```
+
+Optional: pass `until` to cap the upper bound (defaults to now).
+
+**Required param is `since`** — not `last_episode_id`, not `days`. Same time formats as `get_evolution.from` (`"7d ago"`, ISO-8601, etc.).
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ### 3. Interpret the response
 
-| `status` | Meaning | Action |
-|---|---|---|
-| `no_changes` | Nothing changed since your anchor | Safe to proceed; store new anchor |
-| `changes_detected` | Full symbol-level delta returned | Review `modified[]`, `added[]`, `removed[]` |
-| `changes_detected_overview` | >500 candidates — module rollup only | Check `by_module` for affected areas |
-| `error` | Bad anchor or unknown episode | Fall back to `last_reference_time` or re-index |
+Response shape: see [Output](#output) below. Act on `totals.episode_count`:
+
+| `totals.episode_count` | Action |
+|---|---|
+| `0` | Nothing changed — safe to proceed |
+| `1–20` | Review each episode's `touched_files` and change counts |
+| Many episodes | Scan `touched_files` for overlap with your task; drill down with `get_evolution` |
 
 ### 4. Decide whether changes are relevant
 
 ```
-changes_detected
-├── Check modified[]/added[]/removed[] — do any overlap with your current task?
-│   ├── YES → understand what changed before proceeding
-│   └── NO  → safe to continue, update anchor
-
-changes_detected_overview (large window)
-├── Check by_module — does any changed module overlap with your task area?
-│   ├── YES → get_evolution(mode: compound) scoped to that window for detail
-│   └── NO  → ignore, update anchor
+episodes returned
+├── Any touched_files overlap your current task area?
+│   ├── YES → call get_evolution(from: since, mode: compound) for hotspots
+│   └── NO  → safe to continue
+└── Need per-commit detail?
+    └── get_evolution(from: since, mode: recent, limit: 100)
 ```
 
-### 5. Always persist the returned anchor
+### 5. Always persist the new anchor
 
-Every response includes a new `session_anchor`. Store it for next session:
+Store the `until` value from the response (or the latest episode's `reference_time`) for next session:
 
 ```json
 {
-  "session_anchor": {
-    "last_episode_id": "ep_xyz789",
-    "last_reference_time": "2026-04-13T14:22:00Z"
-  }
+  "repo_id": "memdb",
+  "since": "2026-04-13T14:22:00Z"
 }
 ```
 
-## Auto-mode Selection
+## Output
 
-`get_changes_since` automatically picks the right mode so it never crashes:
+`get_changes_since` returns:
 
-| Candidate count | Mode selected | What you get |
-|---|---|---|
-| 0 | — | `no_changes` immediately |
-| 1–499 | `compound` | Full symbol scoring |
-| 500+ | `overview` | Module rollup only |
+| Field | Meaning |
+|---|---|
+| `episodes[]` | Each episode since `since`, with `touched_files`, `nodes_added/removed`, `reference_time` |
+| `totals.episode_count` | How many episodes in the window — `0` means nothing changed |
+| `since` / `until` | The resolved window boundaries |
 
-`candidate_count` in the response tells you what was found before selection.
+```json
+{
+  "since": "2026-04-13T10:43:00Z",
+  "until": "2026-04-13T14:22:00Z",
+  "episodes": [
+    { "reference_time": "2026-04-13T12:05:00Z", "touched_files": ["src/engine/page_cache.rs"], "nodes_added": 4, "nodes_removed": 1 }
+  ],
+  "totals": { "episode_count": 1 }
+}
+```
 
-## Common Mistakes
+## Common mistakes
 
 | Mistake | Reality |
-|---------|---------|
-| Using `get_evolution` with a guessed timestamp | `get_changes_since` uses an exact episode boundary — no guessing, no over-fetching |
-| Discarding the returned `session_anchor` | Without it, next session reverts to timestamp guessing |
-| Treating `changes_detected_overview` as too large to act on | `by_module` is complete — it tells you exactly which areas changed even in large windows |
-| Calling this tool repeatedly within one session | Call once at session start; use the returned evolution result for the rest of the session |
+|---|---|
+| Passing `last_episode_id` or `days` | `get_changes_since` requires `since` — a timestamp string |
+| Using `get_evolution` without `from` | Always pass `from` (e.g. `"7d ago"`) — never omit it or use `days` |
+| Expecting `status`, `by_module`, or `session_anchor` in the response | Not in the current shape — use `episodes[]` and `totals` |
+| Discarding the stored `since` timestamp | Without it, next session reverts to guessing |
+| Calling this repeatedly within one session | Call once at session start; reuse the result for the rest of the session |