memtrace 0.1.37 → 0.1.45

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

@@ -0,0 +1,120 @@
+---
+name: memtrace-first
+description: "Use when working on any indexed codebase before searching files, reading code, debugging issues, tracing call flows, finding implementations, understanding behavior, or answering 'how does X work' questions. Triggered by: file search, symbol lookup, code navigation, debugging, tracing, understanding architecture, finding where something is defined or called."
+---
+
+# Memtrace First
+
+## The Iron Law
+
+```
+IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
+NEVER reach for Grep/Glob/Read to discover or understand code.
+```
+
+Memtrace is the memory layer of the codebase. It has the full knowledge graph: every symbol, call, import, community, process, and API — with time dimension. File tools are blind to this structure.
+
+**97% better accuracy. 83% fewer wasted tokens. No exceptions.**
+
+## Parameter Types — Read This Before Calling Any Tool
+
+All memtrace MCP tools are **strictly typed**. Pass JSON numbers (not strings) for integer parameters.
+
+| Parameter | Correct | WRONG (fails with MCP error -32602) |
+|---|---|---|
+| `limit`, `min_size`, `depth`, `max_depth`, `last_n` | `limit: 20` | `limit: "20"` |
+| `repo_id`, `branch`, `name`, `symbol_name`, `query` | `repo_id: "my-repo"` | `repo_id: my-repo` (unquoted) |
+| `fuzzy`, `include_tests`, `invalidate` | `fuzzy: true` | `fuzzy: "true"` |
+
+If you see `failed to deserialize parameters: invalid type: string "N", expected usize`, remove the quotes from the number and retry.
+
+## Check Indexing First (Once Per Session)
+
+```
+mcp__memtrace__list_indexed_repositories
+```
+
+If the current repo appears → Memtrace is active. Follow this skill for ALL code tasks.
+If not indexed → offer to index with `mcp__memtrace__index_directory`, then follow this skill.
+
+## Task → Tool Map
+
+| What you need | Use instead of Grep/Glob/Read |
+|---|---|
+| Find a function / class / symbol | `find_symbol` or `find_code` |
+| Understand how something works | `get_symbol_context` |
+| Find all callers of a function | `get_symbol_context` (callers field) |
+| Find all callees / dependencies | `get_symbol_context` (callees field) |
+| Trace a request / execution path | `get_process_flow` |
+| Understand module structure | `list_communities` |
+| Find the most important symbols | `find_central_symbols` |
+| Find API endpoints | `find_api_endpoints` |
+| Find where an API is called | `find_api_calls` |
+| Debug a problem | `get_symbol_context` → `get_impact` → `get_evolution` |
+| What changed recently? | `get_changes_since` or `get_evolution` |
+| What breaks if I change X? | `get_impact` |
+| Cross-service / cross-repo calls | `get_service_diagram` or `get_api_topology` |
+| Dependency between two symbols | `find_dependency_path` |
+| What files change together? | `get_cochange_context` |
+| Architecture overview | `list_communities` + `find_central_symbols` |
+
+## Standard Workflows
+
+### "How does X work?" / "Explain X"
+1. `find_symbol` or `find_code` → locate the symbol
+2. `get_symbol_context` → callers, callees, community, processes
+3. `get_process_flow` (if it's a process/request path)
+4. Read source ONLY for the exact lines you need to quote
+
+### Debugging "X is broken"
+1. `find_symbol` → locate the broken thing
+2. `get_symbol_context` → understand its role
+3. `get_impact` → blast radius (what else breaks)
+4. `get_evolution` → what changed recently (mode: `recent`)
+5. `get_changes_since` → confirm timing vs incident
+
+### "Where is X defined / called?"
+1. `find_symbol` with `fuzzy: true`
+2. `get_symbol_context` for full caller/callee map
+3. Read specific file only after locating exact line
+
+### Before any code modification
+1. `find_symbol` → confirm you have the right target
+2. `get_symbol_context` → understand full context
+3. `get_impact` → know blast radius before touching anything
+
+## Red Flags — STOP, Use Memtrace Instead
+
+You are violating this skill if you think:
+
+| Thought | Reality |
+|---|---|
+| "Let me grep for this" | `find_code` or `find_symbol` is faster and structurally aware |
+| "Let me glob for the file" | `find_symbol` returns exact location with context |
+| "Let me read the whole file" | `get_symbol_context` gives you only what matters |
+| "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
+| "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
+| "The user didn't say to use Memtrace" | User asked about the code. Repo is indexed. Use Memtrace. |
+| "This is a simple question" | Simple questions benefit most — one `find_symbol` vs 20 file reads |
+
+## When File Tools Are Still Correct
+
+Use Grep/Glob/Read ONLY for:
+- Reading the **exact source lines** of a symbol you already located via Memtrace
+- Files that are config, data, or docs (not source code symbols)
+- Repos confirmed NOT indexed in Memtrace
+
+Never use file tools as a **discovery** mechanism when Memtrace is available.
+
+## Skill Priority
+
+This skill is a **process skill** — it runs BEFORE any implementation or search skill.
+
+When this skill applies, it overrides default file-search behavior. Use the specific Memtrace sub-skills for deep detail on each tool:
+
+- Discovery → `memtrace-search`
+- Impact analysis → `memtrace-impact`
+- Temporal / change analysis → `memtrace-evolution`
+- Incident investigation → `memtrace-incident-investigation`
+- Architecture overview → `memtrace-codebase-exploration`
+- Refactoring → `memtrace-refactoring-guide`

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

@@ -0,0 +1,125 @@
+---
+name: memtrace-incident-investigation
+description: "Use when the user is investigating a bug, incident, production issue, regression, something that broke, root cause analysis, debugging a failure, or trying to figure out what went wrong and when"
+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_episode_replay
+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.
+
+## 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/installer/skills/workflows/memtrace-refactoring-guide.md

@@ -0,0 +1,116 @@
+---
+name: memtrace-refactoring-guide
+description: "Use when the user wants to refactor code, reduce complexity, clean up technical debt, split a large function, extract a module, reorganize code, identify refactoring priorities, or improve code structure"
+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__analyze_relationships
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__calculate_cyclomatic_complexity
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## 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/installer/skills/workflows/memtrace-session-continuity.md

@@ -0,0 +1,98 @@
+---
+name: memtrace-session-continuity
+description: "Use at the start of any session to check what changed since last time, when resuming work after a break, when an agent needs to orient itself without guessing timestamps, or when asked 'what changed while I was away'"
+allowed-tools:
+  - mcp__memtrace__get_changes_since
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_evolution
+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.
+
+**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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.1.37",
+  "version": "0.1.45",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -11,7 +11,7 @@
     "skills",
     "claude-code"
   ],
-  "homepage": "https://memtrace.dev",
+  "homepage": "https://memtrace.io",
   "repository": {
     "type": "git",
     "url": "https://github.com/syncable-dev/memtrace-public"
@@ -23,6 +23,7 @@
   "files": [
     "bin/",
     "skills/",
+    "installer/",
     "install.js",
     "uninstall.js"
   ],
@@ -30,10 +31,14 @@
     "postinstall": "node install.js",
     "preuninstall": "node uninstall.js"
   },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "fs-extra": "^11.0.0"
+  },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.1.37",
-    "@memtrace/linux-x64": "0.1.37",
-    "@memtrace/win32-x64": "0.1.37"
+    "@memtrace/darwin-arm64": "0.1.38",
+    "@memtrace/linux-x64": "0.1.38",
+    "@memtrace/win32-x64": "0.1.38"
   },
   "engines": {
     "node": ">=18"

package/skills/commands/memtrace-api-topology.md

@@ -23,6 +23,9 @@ Map the HTTP API surface of a codebase — exposed endpoints, outbound HTTP call
 | `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

package/skills/commands/memtrace-cochange.md

@@ -17,6 +17,9 @@ Find symbols that historically co-change with a target symbol — ranked by co-o
 
 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

package/skills/commands/memtrace-evolution.md

@@ -27,6 +27,9 @@ This is memtrace's most powerful analytical tool. It implements six distinct sco
 | `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

package/skills/commands/memtrace-graph.md

@@ -26,18 +26,48 @@ Graph algorithms that reveal the structural architecture of a codebase — commu
 | `get_process_flow` | Trace a single process step-by-step |
 | `execute_cypher` | Direct read-only Cypher queries for custom analysis |
 
+## Parameter Types — Read This First
+
+All memtrace MCP tools are **strictly typed**. Numbers must be JSON numbers, not strings.
+
+| Parameter shape | Correct | Wrong (will fail deserialization) |
+|-----------------|---------|-----------------------------------|
+| Integer/count (`limit`, `min_size`, `depth`) | `limit: 20` | `limit: "20"` |
+| String identifier (`repo_id`, `branch`, `name`) | `repo_id: "my-repo"` | `repo_id: my-repo` |
+| Boolean (`fuzzy`, `include_tests`) | `fuzzy: true` | `fuzzy: "true"` |
+
+If you see `MCP error -32602: invalid type: string "N", expected usize`, you passed a string where a number was required. Remove the quotes.
+
 ## Steps
 
 ### 1. Understand the architecture
 
 Start with `list_communities` to see how the codebase is naturally partitioned into logical modules. Each community has a name, member count, and representative symbols.
 
+**`list_communities` parameters:**
+- `repo_id` — string, required. Repository ID (from `list_indexed_repositories`).
+- `branch` — string, optional. Defaults to `"main"`.
+- `min_size` — **integer**, optional. Minimum community size to include. Default `3`.
+- `limit` — **integer**, optional. Max communities to return. Default `50`, capped at `200`.
+
+Example (correct):
+```json
+{ "repo_id": "Memtrace", "limit": 20 }
+```
+Example (WRONG — will fail):
+```json
+{ "repo_id": "Memtrace", "limit": "20" }
+```
+
 ### 2. Find critical infrastructure
 
 Use `find_central_symbols` to identify the most important symbols:
-- `method: "pagerank"` — importance by link structure (like Google's PageRank)
-- `method: "degree"` — importance by direct connection count
-- `limit` — how many to return
+
+**`find_central_symbols` parameters:**
+- `repo_id` — string, required.
+- `branch` — string, optional. Defaults to `"main"`.
+- `limit` — **integer**, optional. How many to return. Default `20`, capped at `100`.
+- `algorithm` — string, optional. `"pagerank"` (default, via MAGE — falls back to degree if unavailable) or `"degree"` (simple in-degree count, no MAGE required).
 
 ### 3. Find architectural chokepoints
 
@@ -46,16 +76,36 @@ Use `find_bridge_symbols` to find symbols that, if removed, would disconnect par
 - **Integration points** — good places for interfaces/contracts
 - **Refactoring targets** — often too much responsibility concentrated in one place
 
+**`find_bridge_symbols` parameters:**
+- `repo_id` — string, required.
+- `branch` — string, optional. Defaults to `"main"`.
+- `limit` — **integer**, optional. Default `15`, capped at `50`.
+
 ### 4. Trace execution flows
 
 Use `list_processes` to see all entry points (HTTP handlers, background jobs, CLI commands, event handlers).
 
-Use `get_process_flow` with a process ID to trace a specific flow step-by-step — shows the full call chain from entry point through business logic to data access.
+**`list_processes` parameters:**
+- `repo_id` — string, required.
+- `branch` — string, optional. Defaults to `"main"`.
+- `limit` — **integer**, optional. Default `50`.
+
+Use `get_process_flow` with a process name to trace a specific flow step-by-step — shows the full call chain from entry point through business logic to data access.
+
+**`get_process_flow` parameters:**
+- `process` — string, required. Process name or entry-point symbol name (from `list_processes`).
+- `repo_id` — string, required.
+- `branch` — string, optional. Defaults to `"main"`.
 
 ### 5. Custom queries
 
 Use `execute_cypher` for advanced graph queries not covered by built-in tools. This is read-only and runs directly against the knowledge graph.
 
+**`execute_cypher` parameters:**
+- `query` — string, required. A read-only Cypher query. Write keywords (CREATE, MERGE, DELETE, SET, etc.) are forbidden. Use `$repo_id` to scope to a repository.
+- `params` — object, optional. JSON object of parameter bindings.
+- `repo_id` — string, optional. If provided, injected as `$repo_id` into `params`.
+
 ## Decision Points
 
 | Question | Tool |

package/skills/commands/memtrace-impact.md

@@ -20,6 +20,9 @@ Compute the blast radius of changing a specific symbol. Traces upstream (what de
 | `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

package/skills/commands/memtrace-index.md

@@ -21,6 +21,9 @@ Index a local codebase into the persistent code knowledge graph. This is always
 | `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

package/skills/commands/memtrace-quality.md

@@ -22,6 +22,9 @@ Identify code quality issues using structural graph analysis — dead code (zero
 | `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

package/skills/commands/memtrace-relationships.md

@@ -25,6 +25,9 @@ Traverse the code knowledge graph to map relationships between symbols — calle
 | `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