memtrace-skills 0.7.10

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

@@ -0,0 +1,58 @@
+---
+name: memtrace-impact
+description: "Always use before or during source-code changes when the user asks about blast radius, impact, what breaks, risk, upstream callers, downstream dependencies, or consequences of modifying a symbol. Do not use Grep or manual reference search; Memtrace computes transitive graph impact."
+---
+
+## Overview
+
+Compute the blast radius of changing a specific symbol. Traces upstream (what depends on this) and downstream (what this depends on) through the knowledge graph to quantify risk before making modifications.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `get_impact` | Blast radius from a specific symbol (by ID) |
+| `detect_changes` | Scope symbols affected by a diff/patch |
+
+> **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 symbol
+
+If you have a symbol name but not its ID:
+- Use `find_symbol` for exact names
+- Use `find_code` for natural-language queries
+
+### 2. Run impact analysis
+
+Use the `get_impact` MCP tool:
+- `symbol_id` — the symbol you plan to change (required)
+- `direction` — `upstream` (what depends on me), `downstream` (what I depend on), or `both` (default)
+- `depth` — traversal hops (default 3)
+
+### 3. Interpret the risk rating
+
+| Risk | Meaning | Action |
+|------|---------|--------|
+| **Low** | Few dependents, leaf node | Safe to modify; minimal testing needed |
+| **Medium** | Moderate dependents | Test direct callers; review interface contracts |
+| **High** | Many dependents across modules | Coordinate changes; comprehensive test coverage |
+| **Critical** | Core infrastructure, many transitive dependents | Plan migration strategy; consider backward-compatible changes |
+
+### 4. For diff-based analysis
+
+When you have an actual code diff (not just a symbol), use `detect_changes`:
+- Scopes all symbols affected by the diff
+- Returns blast radius AND affected processes (execution flows)
+- Useful for PR reviews or pre-commit checks
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Changing a single function | `get_impact` with `direction: both` |
+| Reviewing a PR or diff | `detect_changes` with the diff content |
+| Renaming/removing a public API | `get_impact` with `direction: upstream`, high depth |
+| Refactoring internals | `get_impact` with `direction: downstream` to check what you depend on |

package/plugins/memtrace-skills/skills/memtrace-incident-investigation/SKILL.md

@@ -0,0 +1,112 @@
+---
+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."
+---
+
+## 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.
+
+## Steps
+
+### 1. Establish the timeline
+
+Determine:
+- **Incident time** — when did the problem start? (This becomes the `to` parameter)
+- **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
+
+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
+
+**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.
+
+**Success criteria:** A ranked list of changes, with the most likely culprits at the top.
+
+### 3. Check for unexpected changes
+
+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
+
+**Decision:** If `novel` mode surfaces different symbols than `recent` mode, investigate both — the root cause may be an unexpected change to stable infrastructure.
+
+### 4. Trace the blast radius of top suspects
+
+For the top 3–5 symbols from steps 2–3, call `get_impact` with `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
+
+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
+
+Once you have a primary suspect, call `get_timeline` with the symbol name to see its full version history:
+- What changed in each commit?
+- When was the last "stable" version?
+- Was the change a modification, or was it newly added?
+
+### 7. Correlate with surrounding changes
+
+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)
+
+### 8. Check historical coupling (cochange)
+
+For the primary suspect, call `get_cochange_context`:
+- 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)
+
+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.
+
+## 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
+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
+
+| 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 |
+
+## 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 |
+| 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/plugins/memtrace-skills/skills/memtrace-index/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: memtrace-index
+description: "Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, when code exploration needs an index, or when searches return 0/partial results for source paths under an indexed root. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed."
+---
+
+## Overview
+
+Index a local codebase into the persistent code knowledge graph. This is always the first step — it parses every source file, resolves cross-file relationships, detects API endpoints/calls, runs community detection and process tracing, and embeds all symbols for semantic search.
+
+## Quick Reference
+
+| Parameter | Purpose |
+|-----------|---------|
+| `path` | Absolute path to the directory to index |
+| `incremental` | Only re-parse changed files (use for subsequent runs) |
+| `clear_existing` | Wipe and rebuild from scratch |
+
+> **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. Check if already indexed
+
+Use the `list_indexed_repositories` MCP tool first. If the repo is already indexed and recent, skip to step 4.
+
+**Success criteria:** You have a list of repo_ids and their last-indexed timestamps.
+
+If a repo is present but searches miss a source subdirectory under that repo
+root (for example `ui/`, `memtrace-ui/`, `web/`, `frontend/`, or `src/`), treat
+that as a stale/partial index. Do not use grep as a workaround. Run incremental
+indexing on the repo root, then retry the Memtrace query.
+
+### 2. Index the directory
+
+Use the `index_directory` MCP tool:
+
+- Set `path` to the project root (absolute path)
+- Set `incremental: true` if re-indexing after changes
+- Set `clear_existing: true` only if a full rebuild is needed
+
+**Success criteria:** You receive a `job_id` immediately.
+
+### 3. Poll for completion
+
+Use `check_job_status` with the `job_id` every 2–3 seconds.
+
+Pipeline stages in order: **scan → parse → resolve → communities → processes → persist → embeddings → api_detect → done**
+
+Wait until `status = "completed"`. If `status = "failed"`, report the error message to the user.
+
+### 4. Report to user
+
+After indexing completes, call `list_indexed_repositories` to confirm the repo appears with correct node/edge counts. Report: repo_id, languages detected, total symbols, total relationships.
+
+**Save the `repo_id`** — most other memtrace tools require it.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Path does not exist | Ask user to verify the absolute path |
+| Job status "failed" | Report the error message; suggest `clear_existing: true` for a fresh rebuild |
+| Timeout (job running > 5 min) | Large repos are normal; keep polling. For monorepos, index subdirectories separately |
+| Already indexed | Use `incremental: true` to update, or skip indexing entirely |

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

@@ -0,0 +1,63 @@
+---
+name: memtrace-quality
+description: "Always use for source-code quality, dead code, unused functions, zero callers, complexity, cyclomatic complexity, hotspots, refactoring candidates, or code smell questions. Do not use Grep, Glob, rg, or manual reference search for unused code; Memtrace uses graph reachability and complexity metrics."
+---
+
+## Overview
+
+Identify code quality issues using structural graph analysis — dead code (zero callers), complexity hotspots (high out-degree), and repository-wide statistics.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_dead_code` | Symbols with zero callers (potentially unused) |
+| `calculate_cyclomatic_complexity` | Complexity score for a specific symbol |
+| `find_most_complex_functions` | Top-N functions by complexity across the repo |
+| `get_repository_stats` | Repo-wide counts: nodes, edges, communities, processes |
+
+> **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. Get repository overview
+
+Use `get_repository_stats` to understand the codebase scale:
+- Node counts by kind (functions, classes, methods, interfaces)
+- Edge counts (calls, imports, extends, type references)
+- Community and process counts
+
+### 2. Find dead code
+
+Use `find_dead_code`:
+- `repo_id` — required
+- `include_tests` — set true to also flag unused test helpers (default false)
+
+**Note:** Exported symbols and entry points are excluded by default — the tool won't flag public APIs as "dead" just because they're called externally.
+
+### 3. Find complexity hotspots
+
+Use `find_most_complex_functions`:
+- `repo_id` — required
+- `limit` — how many to return (default 10)
+
+Complexity scoring (based on out-degree — number of callees):
+| Score | Rating | Action |
+|-------|--------|--------|
+| < 5 | Low | No action needed |
+| 5–10 | Medium | Monitor; consider splitting if growing |
+| 10–20 | High | Refactoring candidate; extract helper functions |
+| > 20 | Critical | Immediate attention; this function does too much |
+
+### 4. Drill into specific functions
+
+Use `calculate_cyclomatic_complexity` on specific symbols flagged by the user or found in step 3.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Treating all dead code as deletable | Some "dead" code is called via reflection, dynamic dispatch, or external consumers |
+| Ignoring exported symbols in dead code results | If `include_tests: false`, exported symbols are already excluded |
+| Only looking at the highest complexity | Medium-complexity functions that are growing (check `get_evolution`) are often more urgent |

package/plugins/memtrace-skills/skills/memtrace-refactoring-guide/SKILL.md

@@ -0,0 +1,103 @@
+---
+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."
+---
+
+## Overview
+
+Guided refactoring workflow — identifies refactoring candidates using structural analysis, scores them by risk and priority, and produces a phased refactoring plan. Combines complexity metrics, dead code detection, bridge analysis, and temporal evolution to prioritize what to refactor first and how to do it safely.
+
+## Steps
+
+### 1. Identify refactoring candidates
+
+Run these three tools in parallel to build a candidate list:
+
+**a) Complexity hotspots:**
+Call `find_most_complex_functions` with `limit: 20`
+
+**b) Dead code:**
+Call `find_dead_code` to find unused symbols
+
+**c) Architectural bottlenecks:**
+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:
+- 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
+
+**Priority matrix:**
+
+| | Low Complexity | High Complexity |
+|---|---|---|
+| **Stable (low change freq)** | Leave alone | Monitor; refactor if touched |
+| **Volatile (high change freq)** | Normal; leave alone | **TOP PRIORITY** — refactor first |
+
+### 3. Assess risk for top candidates
+
+For each top-priority candidate, call `get_impact` with `direction: both`:
+- **Low risk** → refactor directly
+- **Medium risk** → refactor with comprehensive tests
+- **High/Critical risk** → plan incremental migration with backward compatibility
+
+Also call `get_symbol_context` to check:
+- How many processes does this symbol participate in? (More = more testing needed)
+- Is it part of a cross-repo API? (If yes, coordinate with consumers)
+
+### 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)
+
+### 5. Check community boundaries
+
+Call `list_communities` and check: does the refactoring target sit at a community boundary?
+- If yes, the refactoring may involve splitting responsibilities across modules
+- If it belongs clearly to one community, the refactoring is more contained
+
+### 6. Produce the refactoring plan
+
+Synthesize into a phased plan:
+
+**Phase 1 — Quick Wins:**
+- Dead code removal (zero-risk deletions)
+- Simple functions with high churn (reduce volatility)
+
+**Phase 2 — High-Impact Refactors:**
+- Complex + volatile functions (highest priority by the matrix)
+- Bridge symbols with too many responsibilities (extract interfaces)
+
+**Phase 3 — Structural Improvements:**
+- Splitting oversized communities into smaller, focused modules
+- Extracting shared logic from bridge symbols into dedicated services
+
+For each item, include:
+1. **Target** — function/class name, file, current complexity score
+2. **Why** — complexity + volatility + blast radius rationale
+3. **How** — specific refactoring approach (extract method, split class, introduce interface)
+4. **Risk** — impact analysis rating + affected processes
+5. **Test Plan** — which callers/processes to verify
+
+## Decision Points
+
+| Condition | Action |
+|-----------|--------|
+| Complex + volatile + high blast radius | Highest priority — but plan carefully; incremental approach |
+| Complex + stable + low blast radius | Can wait; refactor when you're already touching nearby code |
+| Dead code with zero callers | Safe to delete — quick win |
+| 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 |
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Refactoring the most complex function first | Complexity alone isn't enough — prioritize by complexity × volatility |
+| Deleting all dead code at once | Some "dead" code is called dynamically; verify before batch deletion |
+| Refactoring without checking blast radius | A "simple" refactor on a bridge symbol can cascade across the codebase |
+| Not checking temporal evolution | A complex function that hasn't changed in a year is lower priority than a simpler one that changes weekly |

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

@@ -0,0 +1,67 @@
+---
+name: memtrace-relationships
+description: "Always use for source-code relationship questions: callers, callees, references, imports, exports, type usages, class hierarchy, inheritance, implementations, overrides, or dependencies between symbols. Do not use Grep, Glob, rg, find, or manual text search for references; Memtrace traverses typed AST graph edges."
+---
+
+## Overview
+
+Traverse the code knowledge graph to map relationships between symbols — callers, callees, class hierarchies, imports, exports, and type usages. Essential for understanding a symbol's neighbourhood before modifying it.
+
+## Quick Reference
+
+| query_type | What it finds |
+|------------|---------------|
+| `find_callers` | What calls this function/method? |
+| `find_callees` | What does this function call? |
+| `class_hierarchy` | Parent classes, interfaces, mixins |
+| `overrides` | Which child classes override this method? |
+| `imports` | What modules does this file import? |
+| `exporters` | Which files import this module? |
+| `type_usages` | Where is this type/interface referenced? |
+
+> **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. Get the symbol ID
+
+If you don't have a symbol `id`, find it first:
+- Use `find_symbol` for exact names
+- Use `find_code` for natural-language queries
+
+### 2. Choose your approach
+
+**Quick 360° view** → Use `get_symbol_context`
+Returns in one call: direct callers, callees, type references, community membership, process membership, and cross-repo API callers.
+
+**ALWAYS prefer `get_symbol_context` first** — it answers "what does this touch and what touches it?" faster than multiple `analyze_relationships` calls.
+
+**Targeted traversal** → Use `analyze_relationships`
+When you need a specific relationship type at a specific depth:
+- `symbol_id` — the symbol to start from (required)
+- `query_type` — one of the types above (required)
+- `depth` — traversal hops, default 2 (higher = slower but reveals indirect deps)
+
+### 3. Interpret results
+
+- **High in_degree** (many callers) → widely-used symbol; changes have large blast radius
+- **High out_degree** (many callees) → complex function; candidate for refactoring
+- **Deep class hierarchy** → check for Liskov violations or fragile base class issues
+- **Cross-repo API callers** → changes require coordination with other teams/services
+
+### 4. Follow up
+
+After understanding relationships, consider:
+- `get_impact` to quantify the blast radius of a change
+- `get_evolution` to see how this symbol has changed over time
+- `find_dead_code` if you found unreferenced symbols
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Need broad context fast | Use `get_symbol_context` (one call, full picture) |
+| Need specific relationship at depth >2 | Use `analyze_relationships` with custom depth |
+| Symbol has many callers | Follow up with `get_impact` before modifying |
+| Found cross-repo API callers | This is a service boundary — coordinate changes |

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

@@ -0,0 +1,93 @@
+---
+name: memtrace-search
+description: "Always use to find, search, locate, or look up source-code symbols, functions, classes, types, constants, definitions, implementations, logic, error strings inside code, or where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
+---
+
+## Overview
+
+Find code using hybrid BM25 full-text + semantic vector search with Reciprocal Rank Fusion. Works for both natural-language queries and exact symbol names. This is the primary discovery tool — use it before calling relationship or impact analysis tools.
+
+## Quick Reference
+
+| Tool | Best For |
+|------|----------|
+| `find_code` | Natural-language queries ("authentication middleware", "retry logic"), broad searches |
+| `find_symbol` | Exact identifier names ("getUserById", "PaymentService"), when you know the name |
+| `get_source_window` | Optional: bounded source read after a Memtrace hit, when your harness lacks `Read(file, offset, limit)`. Otherwise prefer your harness's bounded read with the returned `start_line` / `end_line`. |
+
+## Steps
+
+### 1. Choose the right search tool
+
+- **Know the exact name?** → Use `find_symbol` with `fuzzy: true` for typo tolerance
+- **Describing behaviour?** → Use `find_code` with a natural-language query
+- **Searching all repos?** → Omit `repo_id` from either tool
+
+### 2. Execute the search
+
+> **Parameter types:** numbers must be JSON numbers, not strings. `limit: 20` is correct; `limit: "20"` returns `MCP error -32602: expected usize`.
+
+**`find_code` parameters:**
+- `query` — string, required. Natural-language or exact text.
+- `repo_id` — string, optional. Scope to a single repo (omit to search all).
+- `kind` — string, optional. Filter by symbol type: `"Function"`, `"Class"`, `"Method"`, `"Interface"`, `"APIEndpoint"`, `"APICall"`.
+- `limit` — **integer**, optional. Max results. Default `20`, capped at `100`.
+- `as_of` — string, optional. ISO-8601 timestamp for time-travel search (e.g. `"2026-04-01T00:00:00Z"`).
+- `file_path` — string, optional. File path or directory substring to constrain results (e.g. `"cli/commands"` or `"auth.py"`).
+
+**`find_symbol` parameters:**
+- `name` — string, required. Exact or partial symbol name (e.g. `"ValidateToken"`).
+- `fuzzy` — boolean, optional. Enable Levenshtein correction. Default `false`.
+- `edit_distance` — **integer**, optional. Maximum Levenshtein edit distance for fuzzy search. Default `2`, capped at `2`.
+- `repo_id` — string, optional. Scope to a single repo.
+- `kind` — string, optional. Filter by symbol type (e.g. `"Function"`, `"Class"`, `"Variable"`).
+- `file_path` — string, optional. Filter by file path substring.
+- `limit` — **integer**, optional. Max results. Default `10`, capped at `50`.
+
+**Success criteria:** Results include `file_path`, `start_line`, `kind`, and relevance `score`.
+
+### 3. Use results for next steps
+
+The default next step is a **graph tool** — `get_symbol_context`,
+`analyze_relationships`, or `get_impact`. Those answer "who calls this",
+"what's the blast radius", "what community is it part of" — context no
+file read can give. That's what Memtrace uniquely provides.
+
+Source bytes come last, only when you're about to edit or quote. Use a
+bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`,
+or `get_source_window` if your harness lacks bounded reads. Do not whole-file.
+
+Save the symbol `id` from results — pass it to:
+- `analyze_relationships` to map callers/callees
+- `get_symbol_context` for a 360-degree view
+- `get_impact` to assess blast radius before changes
+
+### Multi-word natural-language queries
+
+When your query is 3+ words and feels descriptive (e.g. "validate auth token", "find HTTP server error"), don't stop at the first `find_code` call:
+
+1. First try the verbatim query.
+2. If results look generic or the right doc isn't at rank 1, fan out **in parallel** with up to 3 identifier-shaped reshapes:
+   - camelCase: "validate auth token" → `validateAuthToken`
+   - snake_case: → `validate_auth_token`
+   - Domain-likely identifiers: → `auth_token`, `tokenValidator`, `verifyToken`
+3. Memtrace's tokenizer splits camelCase / snake / kebab at index time, so reshaped queries hit identifier names directly.
+4. Take the union of top-5 from each call, dedupe by `file_path:start_line`.
+
+**Worked examples** (verbatim → reshapes to try in parallel):
+- "validate auth token" → `validateAuthToken`, `validate_auth_token`, `verifyToken`
+- "find http server error" → `findHttpServerError`, `http_error`, `serverError`
+- "render value panel" → `renderValuePanel`, `ValuePanel`, `value_panel`
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Searching without indexing first | Call `list_indexed_repositories` to verify the repo is indexed |
+| Using find_symbol for vague queries | Use `find_code` for natural-language; `find_symbol` is for exact names |
+| Ignoring the `kind` filter | Narrow results with kind=Function, kind=Class etc. to reduce noise |
+| Re-searching to get more context | Use the symbol `id` with `get_symbol_context` instead of re-searching |
+| Reading the whole file after a hit | First call `get_symbol_context` for callers/callees. If you still need source, do a bounded `Read(file, offset=start_line, limit=N)` — never whole-file. `get_source_window` is fine if your harness has no bounded read. |
+| Going straight from `find_code` to source read | Memtrace's value is the graph. Default next step is `get_symbol_context` or `get_impact`, not source. |
+| Treating 0 results as permission to grep | 0 results means broaden the Memtrace query, check repo_id/path filters, then reindex if coverage is missing |
+| Assuming a UI subdirectory is unindexed because stats show backend files | If `ui/`, `memtrace-ui/`, or another source directory is under the indexed repo root, diagnose/reindex with Memtrace instead of searching files manually |

package/plugins/memtrace-skills/skills/memtrace-session-continuity/SKILL.md

@@ -0,0 +1,93 @@
+---
+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."
+---
+
+## 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.
+
+**Core principle:** Agents track a cursor, not a clock. Never guess timestamps.
+
+## Steps
+
+### 1. Find or bootstrap the session anchor
+
+Look for a stored `session_anchor` from your last session:
+
+```json
+{
+  "last_episode_id": "ep_abc123",
+  "last_reference_time": "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.
+
+### 2. Call `get_changes_since`
+
+```
+get_changes_since(
+  repo_id: "...",
+  last_episode_id: "ep_abc123"      // preferred — exact episode boundary
+  // OR
+  last_reference_time: "2026-04-13T10:43:00Z"   // fallback
+)
+```
+
+### 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 |
+
+### 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
+```
+
+### 5. Always persist the returned anchor
+
+Every response includes a new `session_anchor`. Store it for next session:
+
+```json
+{
+  "session_anchor": {
+    "last_episode_id": "ep_xyz789",
+    "last_reference_time": "2026-04-13T14:22:00Z"
+  }
+}
+```
+
+## Auto-mode Selection
+
+`get_changes_since` automatically picks the right mode so it never crashes:
+
+| Candidate count | Mode selected | What you get |
+|---|---|---|
+| 0 | — | `no_changes` immediately |
+| 1–499 | `compound` | Full symbol scoring |
+| 500+ | `overview` | Module rollup only |
+
+`candidate_count` in the response tells you what was found before selection.
+
+## 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 |