memtrace-skills 0.7.10

package/plugins/memtrace-skills/skills/memtrace-api-topology/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: memtrace-api-topology
+description: "Always use for API endpoint, HTTP route, fetch/client call, REST surface, service dependency, cross-repo dependency, or API topology questions in source code. Do not use Grep, Glob, rg, find, or manual file search for routes or HTTP calls; Memtrace maps endpoints and call edges from the indexed AST graph."
+---
+
+## Overview
+
+Map the HTTP API surface of a codebase — exposed endpoints, outbound HTTP calls, and cross-repo service-to-service dependency graphs. Supports auto-detection for Express, Encore, NestJS, Axum, FastAPI, Flask, Gin, Spring Boot, and more.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_api_endpoints` | All exposed HTTP endpoints (GET /users, POST /orders, etc.) |
+| `find_api_calls` | All outbound HTTP calls (fetch, axios, reqwest, etc.) |
+| `get_api_topology` | Cross-repo call graph: which service calls which endpoint |
+| `link_repositories` | Manually link repos for cross-repo edge detection |
+
+> **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. Discover endpoints
+
+Use `find_api_endpoints`:
+- `repo_id` — required
+- Returns: method, path, handler function, framework detected
+
+### 2. Discover outbound calls
+
+Use `find_api_calls`:
+- `repo_id` — required
+- Returns: target URL/path, HTTP method, calling function, library used (fetch, axios, reqwest, etc.)
+
+### 3. Map service topology
+
+Use `get_api_topology` to see the cross-repo HTTP call graph:
+- Which services call which endpoints
+- Confidence scores for each detected link
+- Service-to-service dependency direction
+
+**Prerequisite:** Multiple repos must be indexed. If cross-repo links aren't appearing, use `link_repositories` to explicitly connect them.
+
+### 4. Deep-dive into an endpoint
+
+For any specific endpoint, use `get_symbol_context` with the endpoint's symbol ID to see:
+- Which internal functions handle the request
+- Which processes (execution flows) include this endpoint
+- Which external services call this endpoint
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Expecting cross-repo links with only one repo indexed | Index ALL related services first; cross-repo HTTP edges are linked automatically after indexing |
+| Missing endpoints from custom frameworks | Memtrace auto-detects major frameworks; for custom routers, the endpoints may appear as regular functions |
+| Not using `link_repositories` | If auto-linking missed a connection, use this to manually establish cross-repo edges |

package/plugins/memtrace-skills/skills/memtrace-change-impact-analysis/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: memtrace-change-impact-analysis
+description: "Always use before source-code edits, refactors, API changes, renames, removals, PR reviews, or risk assessments when the user needs to know what will break. Do not manually grep references or browse files for impact; this workflow uses Memtrace graph context, impact, and change detection."
+---
+
+## 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/plugins/memtrace-skills/skills/memtrace-cochange/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: memtrace-cochange
+description: "Always use for historical coupling, co-change, what changes with this, hidden dependency, or what else needs to move questions for source code. Do not use git log, git diff, Grep, or manual file search to correlate changes; Memtrace queries co-change and temporal graph data directly."
+---
+
+## Overview
+
+Find symbols that historically co-change with a target symbol — ranked by co-occurrence frequency across all episodes. This surfaces **behavioral coupling** that the static call graph cannot see.
+
+`get_impact` answers "who calls this?" (structural).
+`get_cochange_context` answers "what always moves when this moves?" (historical).
+
+They are complementary. A symbol with no direct callers can still have strong cochange partners if it's always modified alongside another in every commit.
+
+> **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 target symbol
+
+Use `find_symbol` if you need the exact name. The tool matches by `name` field.
+
+### 2. Call `get_cochange_context`
+
+```
+get_cochange_context(
+  repo_id: "...",
+  symbol: "execute",    // exact symbol name
+  limit: 20             // default 20, increase for broader view
+)
+```
+
+### 3. Interpret results
+
+The response contains `cochanges[]`, each with:
+- `name` — symbol name
+- `kind` — Function / Method / Class / Struct
+- `file_path` — where it lives
+- `cochange_count` — how many episodes it shared with the target
+
+```
+High cochange_count = strong historical coupling
+→ If you modify the target, you will likely need to touch this too
+→ Or it may be the real root cause you should investigate first
+```
+
+### 4. Cross-reference with call graph
+
+For the top cochange partners, optionally run `get_impact` to see if the coupling is also structural:
+
+| Structural coupling | Historical coupling | Interpretation |
+|---|---|---|
+| Yes | Yes | Core architectural dependency — highest risk |
+| No | Yes | Hidden coupling — only visible through history |
+| Yes | No | Called frequently but changed independently — lower risk |
+
+## When to Use
+
+- **Before modifying a symbol** — get blast awareness beyond what `get_impact` shows
+- **Incident investigation** — when `get_impact` doesn't explain the blast radius, check cochange history
+- **Code review** — verify that a PR touched all historically-coupled partners
+- **Refactoring** — discover implicit coupling before extracting a module
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Only using `get_impact` for blast radius | Structural coupling misses behavioral coupling — always pair with cochange |
+| Ignoring low-`in_degree` cochange partners | A rarely-called utility with high cochange_count is a strong coupling signal |
+| Using cochange as a dependency map | It's not a dependency graph — it's a change correlation. Two symbols can cochange without any direct relationship. |

package/plugins/memtrace-skills/skills/memtrace-code-review/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: memtrace-code-review
+description: "Always use when the user asks to review a GitHub pull request, run Memtrace code review, post Memtrace review comments, create a PR with a review step, or publish local graph-backed review findings to GitHub. Prefer the review_github_pr MCP tool over manual diff inspection."
+---
+
+## Overview
+
+Use Memtrace's local-first PR review workflow. The agent should call the `review_github_pr` MCP tool so review runs against the developer's local indexed graph, AST detectors, YAML rule pack, and review policy. GitHub is used for PR context and optional comment publication; source code analysis stays local.
+
+## Default Flow
+
+1. If the user gives a GitHub PR URL and asks to inspect or review it, call `review_github_pr` with `post: false`.
+2. If the user explicitly asks to publish, post comments, or complete the PR review, call `review_github_pr` with `post: true`.
+3. Use `graphMode: "strict"` by default. Use `graphMode: "off"` only when the user asks to benchmark non-graph behavior or the local graph is unavailable.
+4. Default to `minSeverity: "high"` and `maxComments: 5` when posting. For previews, `maxComments: 10` is acceptable.
+5. Pass `repoRoot` when the PR checkout is not the current working directory. Pass `repoId` when the indexed repository id is known.
+
+## Example User Prompts
+
+- "Review this PR with Memtrace: https://github.com/OWNER/REPO/pull/123"
+- "Use Memtrace to review this pull request and post the findings: https://github.com/OWNER/REPO/pull/123"
+- "Create the PR, then run Memtrace code review and publish the review comments."
+
+## Guardrails
+
+- Do not start with generic grep, rg, or manual diff review when `review_github_pr` is available.
+- Do not post comments unless the user explicitly requested publication.
+- Do not create benchmark-specific or PR-specific findings. The review must come from general Memtrace detectors, graph evidence, and policy ranking.
+- If the tool reports missing auth, tell the user to run `memtrace auth login`.
+- If the tool reports missing GitHub App installation, tell the user to install Memtrace Code Reviewer on that repository.
+- If the tool reports missing local graph context, tell the user to run `memtrace index .` at the workspace root.
+
+## Output
+
+For previews, summarize:
+- PR URL and repository
+- Graph state
+- Number of candidate comments
+- File, line, severity, and message for each finding
+
+For posted reviews, report the PR URL and number of comments posted.

package/plugins/memtrace-skills/skills/memtrace-codebase-exploration/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: memtrace-codebase-exploration
+description: "Always use when the user wants to explore, understand, onboard to, map, or get an overview of an indexed source-code repo, architecture, modules, or major flows. Do not use Glob, find, tree, rg, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing."
+---
+
+## 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 `limit: 15`. It ranks symbols by PageRank over the repo's CALLS / REFERENCES edges (default `method: "pagerank"`, 0.85 damping factor).
+
+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/plugins/memtrace-skills/skills/memtrace-continuous-memory/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: memtrace-continuous-memory
+description: "Always use when the user asks to keep Memtrace fresh while editing, watch a repo, enable live or incremental indexing, set up always-on memory, or make just-saved source code queryable immediately. Do not fall back to repeated Grep or manual rescans; configure Memtrace watching."
+---
+
+## Overview
+
+Memtrace keeps the knowledge graph live as you edit. Once you call `watch_directory`, every save runs through the **incremental indexing fast-path** — a notify-based file watcher debounces saves, the indexer re-parses only the touched files, and the engine commits the delta in a single WAL transaction. Steady-state latency is **~80 ms from save to queryable** on a typical project.
+
+This is what makes "session continuity" actually work: by the time you ask `find_symbol` after a save, the new symbol is already in the graph.
+
+## Steps
+
+### 1. Confirm the repo is indexed
+
+```
+mcp__memtrace__list_indexed_repositories
+```
+
+If the repo isn't there, run `index_directory` first. The watcher requires an existing repo_id — it never bootstraps from scratch.
+
+### 2. Start watching
+
+```
+mcp__memtrace__watch_directory(
+  path: "/abs/path/to/repo"
+)
+```
+
+The tool registers a `notify` watcher on the directory tree, debounces save bursts (so a `:wq` that touches a swap file doesn't trigger twice), and routes deltas through the indexer's incremental fast-path. Returns immediately — watching runs in the background.
+
+### 3. Confirm it's live
+
+```
+mcp__memtrace__list_watched_paths
+```
+
+Each entry shows the watched root, the bound repo_id, and the last delta's `persist_ms`.
+
+### 4. Edit normally — Memtrace catches up
+
+After every save the watcher emits a `labels_updated` WebSocket event:
+
+```json
+{
+  "event":           "labels_updated",
+  "repo_id":         "demo",
+  "nodes_changed":   12,
+  "persist_ms":      78,
+  "timestamp":       "2026-04-27T10:42:13Z"
+}
+```
+
+Dashboards and IDE plugins subscribe to this on `/ws` and refresh themselves. As an agent you don't have to listen — your next `find_symbol` / `find_code` / `get_symbol_context` call will see the new state automatically.
+
+### 5. Stop watching
+
+```
+mcp__memtrace__unwatch_directory(path: "/abs/path/to/repo")
+```
+
+Idempotent — unwatching an already-unwatched path is a no-op.
+
+## When to Use
+
+- **Long sessions on the same repo** — keeps `get_symbol_context` accurate without rerunning `index_directory`
+- **Pair programming with an IDE plugin** — the dashboard's WebSocket subscription auto-refreshes panels
+- **Demo / live coding** — every save reflects in the graph within 80–150 ms
+- **Long-running agents** — instead of polling `index_directory`, the watcher pushes deltas
+
+## When NOT to Use
+
+- **One-shot batch edits** — running `index_directory --incremental` at the end is cheaper than spinning up a watcher
+- **Generated / build output trees** — exclude paths under `target/`, `dist/`, `node_modules/` (the watcher honours common ignore patterns but a noisy build can still saturate the debounce queue)
+- **CI / containerised runs** — file events are unreliable across container boundaries; index explicitly instead
+
+## Latency Expectations
+
+| Operation | Typical wall time |
+|---|---|
+| File save → watcher fires | < 5 ms |
+| Debounce window | 50 ms |
+| Incremental parse + delta persist | ~80 ms |
+| `labels_updated` broadcast | < 1 ms after persist |
+| Total: save → queryable | ~80–150 ms |
+
+If you see `persist_ms` consistently above 500 ms, the saved files are larger than expected (e.g., generated bundles) — narrow the watch root or add ignore patterns.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---|---|
+| Calling `watch_directory` on an unindexed repo | Returns an error — run `index_directory` first |
+| Watching `node_modules/` or `target/` | Saturates the watcher with build noise — point at the source root only |
+| Polling `find_symbol` every second to "wait" for indexing | Subscribe to the `labels_updated` WS event, or just call once after the save — the delta is already there |
+| Forgetting to `unwatch_directory` between sessions | Watchers are per-process; restarting `memtrace start` wipes them, but for hosted instances unwatching cleanly avoids leaks |

package/plugins/memtrace-skills/skills/memtrace-episode-replay/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: memtrace-episode-replay
+description: "Always use to replay source-code evolution, understand why code looks this way, inspect implementation attempts, reversions, past reasoning, or abandoned approaches across commits and working-tree episodes. Do not use git log, git diff, Grep, or manual history reconstruction; Memtrace has episodic symbol replay."
+---
+
+## 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 |

package/plugins/memtrace-skills/skills/memtrace-evolution/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: memtrace-evolution
+description: "Always use for source-code change history, recent modifications, what changed since a date, symbol timeline, evolution, unexpected changes, or incident timeline questions. Do not use git log, git diff, Grep, or manual file search to reconstruct history; Memtrace has symbol-level temporal memory."
+---
+
+## Overview
+
+Multi-mode temporal analysis engine that answers "what changed and why should I care?" across arbitrary time windows. Uses Structural Significance Budgeting (SSB) to surface the most important changes without overwhelming you with noise.
+
+This is memtrace's most powerful analytical tool. It implements six distinct scoring algorithms — choose the right one based on what the user needs.
+
+## Query Modes — Choose the Right Algorithm
+
+| Mode | Algorithm | Best For |
+|------|-----------|----------|
+| `compound` | Rank-fusion: 0.50×impact + 0.35×novel + 0.15×recent | **Default.** General-purpose "what changed?" — use when unsure |
+| `impact` | Structural Significance: `sig(n) = in_degree^0.7 × (1 + out_degree)^0.3` | "What broke?" — finds changes with the largest blast radius |
+| `novel` | Change Surprise Index: `surprise(n) = (1 + in_degree) / (1 + change_freq_90d)` | "What's unexpected?" — anomaly detection for rarely-changing code |
+| `recent` | Temporal Proximity: `impact × exp(−0.5 × Δhours)` | "What changed near the incident?" — time-weighted for root cause |
+| `directional` | Asymmetric scoring (added→out_degree, removed→in_degree, modified→impact) | "What was added vs removed?" — structural change direction |
+| `overview` | Fast module-level rollup only | Quick summary — no per-symbol scoring, just module counts |
+
+> **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. Determine the time window
+
+Ask the user or infer:
+- `from` — ISO-8601 start timestamp (required)
+- `to` — ISO-8601 end timestamp (defaults to now)
+- `repo_id` — scope to a repo (call `list_indexed_repositories` if unknown)
+
+### 2. Choose the mode
+
+**Decision tree:**
+
+```
+User wants to know...
+├── "what changed?"           → compound (default)
+├── "what could have broken?" → impact
+├── "anything unexpected?"    → novel
+├── "what changed near X?"    → recent (set to to incident time)
+├── "what was added/removed?" → directional
+└── "quick summary?"          → overview
+```
+
+### 3. Execute the query
+
+Use the `get_evolution` MCP tool with:
+- `repo_id` — required
+- `from` / `to` — the time window
+- `mode` — one of: compound, impact, novel, recent, directional, overview
+
+### 4. Interpret results
+
+The response contains:
+
+- **`added[]`** — new symbols that appeared in the time window
+- **`removed[]`** — symbols that were deleted
+- **`modified[]`** — symbols that changed
+- **`by_module[]`** — module-level rollup (NEVER truncated — always shows all modules)
+- **`significance_coverage`** — fraction of total significance captured (target: ≥0.80)
+- **`budget_exhausted`** — if true, there were more significant changes than the budget allowed
+
+Each symbol includes: `name`, `kind`, `file_path`, `scope_path`, `in_degree`, `out_degree`, and all four scores (`impact`, `novel`, `recent`, `compound`).
+
+### 5. Drill deeper
+
+- **For a single symbol's full history:** Use `get_timeline` with the symbol name
+- **For diff-based change scope:** Use `detect_changes` when you have a specific diff/patch
+- **For blast radius of a specific change:** Use `get_impact` on high-scoring symbols
+
+## Scoring Algorithms — Detailed Reference
+
+### Impact Score (Structural Significance Budgeting)
+```
+sig(n) = in_degree^0.7 × (1 + out_degree)^0.3
+```
+- Heavily weights callers (in_degree) — symbols called by many others have high blast radius
+- Mild boost for outbound complexity (out_degree) — complex functions that changed are notable
+- SSB selects the minimum set covering ≥80% of total significance mass
+
+### Novelty Score (Change Surprise Index)
+```
+surprise(n) = (1 + in_degree) / (1 + change_freq_90d)
+```
+- High in_degree + low change frequency = **maximum surprise**
+- A core utility that hasn't changed in 90 days suddenly changing → likely worth investigating
+- Low in_degree + high frequency = routine churn, deprioritized
+
+### Recent Score (Temporal Proximity Weighting)
+```
+recent(n) = impact(n) × exp(−0.5 × |Δhours to reference|)
+```
+- Exponential decay from the reference timestamp (the `to` parameter)
+- Changes close to an incident get amplified; older changes fade
+- Best for incident timelines: set `to` to the incident timestamp
+
+### Compound Score (Rank Fusion)
+```
+compound = 0.50×rank(impact) + 0.35×rank(novel) + 0.15×rank(recent)
+```
+- Rank-based fusion avoids scale sensitivity between different score types
+- Impact-dominant but boosted by novelty and recency
+- Best default when you don't have a specific hypothesis
+
+## Auto-overview Safety
+
+If a time window produces more than 500 candidates and mode is not `overview`, the query **automatically downgrades to overview mode** and returns `auto_overview: true`. This prevents timeouts on wide windows. When you see `auto_overview: true`:
+- Narrow the window, OR
+- Switch to `get_changes_since` (which handles this automatically), OR
+- Use the `by_module` rollup to identify the specific area and query a tighter window
+
+## Session-Aware Alternative
+
+If you're resuming work after a break and don't know the right `from` timestamp, use `get_changes_since` instead — it accepts a `last_episode_id` anchor and never requires timestamp guessing.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Using `overview` when user needs details | Overview only gives module-level counts — use `compound` for symbol-level |
+| Ignoring `budget_exhausted` flag | If true, there are more significant changes beyond what was returned — narrow the time window or use module rollup |
+| Not checking `by_module` first | Module rollup is never truncated — scan it to identify which areas changed before diving into symbol-level |
+| Using `recent` without setting `to` | The `to` timestamp is the reference point for proximity weighting — set it to the incident/event time |
+| Guessing timestamps when resuming work | Use `get_changes_since` with a stored `session_anchor` instead — exact episode boundary, no guessing |