memtrace 0.1.3

package/bin/memtrace.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const { getBinaryPath } = require("../install.js");
+
+let binaryPath;
+try {
+  binaryPath = getBinaryPath();
+} catch (e) {
+  console.error(`Error: ${e.message}`);
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(`Failed to run memtrace: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/install.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+"use strict";
+
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORM_MAP = {
+  "darwin-arm64": "@memtrace/darwin-arm64",
+  "darwin-x64":   "@memtrace/darwin-x64",
+  "linux-x64":    "@memtrace/linux-x64",
+  "linux-arm64":  "@memtrace/linux-arm64",
+  "win32-x64":    "@memtrace/win32-x64",
+};
+
+function getPlatformKey() {
+  const platform = os.platform(); // darwin, linux, win32
+  const arch = os.arch();         // arm64, x64
+  return `${platform}-${arch}`;
+}
+
+function getBinaryPath() {
+  const key = getPlatformKey();
+  const pkg = PLATFORM_MAP[key];
+
+  if (!pkg) {
+    throw new Error(
+      `Memtrace does not support platform: ${key}\n` +
+      `Supported: ${Object.keys(PLATFORM_MAP).join(", ")}`
+    );
+  }
+
+  const ext = os.platform() === "win32" ? ".exe" : "";
+  const binaryName = `memtrace${ext}`;
+
+  try {
+    return require.resolve(`${pkg}/bin/${binaryName}`);
+  } catch {
+    throw new Error(
+      `Could not find memtrace binary for ${key}.\n` +
+      `Try reinstalling: npm install -g memtrace`
+    );
+  }
+}
+
+// postinstall: verify the binary exists and is executable
+if (require.main === module) {
+  try {
+    const bin = getBinaryPath();
+    if (!fs.existsSync(bin)) {
+      throw new Error(`Binary not found at: ${bin}`);
+    }
+    // Ensure executable on Unix
+    if (os.platform() !== "win32") {
+      fs.chmodSync(bin, 0o755);
+    }
+    console.log(`memtrace: installed binary at ${bin}`);
+  } catch (e) {
+    // Non-fatal — optional deps may not be installed in all environments
+    console.warn(`memtrace: ${e.message}`);
+  }
+}
+
+module.exports = { getBinaryPath };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "memtrace",
+  "version": "0.1.3",
+  "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
+  "keywords": [
+    "mcp",
+    "code-intelligence",
+    "ai",
+    "memgraph",
+    "graph",
+    "skills",
+    "claude-code"
+  ],
+  "homepage": "https://memtrace.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncable-dev/memtrace"
+  },
+  "license": "FSL-1.1-MIT",
+  "bin": {
+    "memtrace": "bin/memtrace.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "install.js"
+  ],
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "optionalDependencies": {
+    "@memtrace/darwin-arm64": "0.1.0",
+    "@memtrace/darwin-x64": "0.1.0",
+    "@memtrace/linux-x64": "0.1.0",
+    "@memtrace/linux-arm64": "0.1.0",
+    "@memtrace/win32-x64": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

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

@@ -0,0 +1,62 @@
+---
+name: memtrace-api-topology
+description: "Use when the user asks about API endpoints, HTTP routes, service-to-service calls, microservice dependencies, API topology, which services call which, cross-repo dependencies, or wants to understand the API surface of a codebase"
+allowed-tools:
+  - mcp__memtrace__get_api_topology
+  - mcp__memtrace__find_api_endpoints
+  - mcp__memtrace__find_api_calls
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__link_repositories
+user-invocable: true
+---
+
+## 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 |
+
+## 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/skills/commands/memtrace-evolution.md

@@ -0,0 +1,119 @@
+---
+name: memtrace-evolution
+description: "Use when the user asks what changed in the codebase, how code evolved over time, what was recently modified, what's the diff between versions, what changed since a date, incident investigation timeline, unexpected changes, change history, or temporal analysis of any kind"
+allowed-tools:
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__get_timeline
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## 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 |
+
+## 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
+
+## 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 |

package/skills/commands/memtrace-graph.md

@@ -0,0 +1,67 @@
+---
+name: memtrace-graph
+description: "Use when the user asks about architectural bottlenecks, important symbols, PageRank, centrality, bridge functions, code communities, logical modules, service boundaries, chokepoints, or wants to understand the high-level architecture of a codebase"
+allowed-tools:
+  - mcp__memtrace__find_bridge_symbols
+  - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__list_processes
+  - mcp__memtrace__get_process_flow
+  - mcp__memtrace__execute_cypher
+user-invocable: true
+---
+
+## Overview
+
+Graph algorithms that reveal the structural architecture of a codebase — community detection (Louvain), centrality ranking (PageRank/degree), bridge symbol identification (betweenness), and execution flow tracing.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_bridge_symbols` | Architectural chokepoints — symbols that connect otherwise-separate modules |
+| `find_central_symbols` | Most important symbols by PageRank or degree centrality |
+| `list_communities` | Louvain-detected logical modules/services |
+| `list_processes` | Execution flows: HTTP handlers, background jobs, CLI commands, event handlers |
+| `get_process_flow` | Trace a single process step-by-step |
+| `execute_cypher` | Direct read-only Cypher queries for custom analysis |
+
+## 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.
+
+### 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
+
+### 3. Find architectural chokepoints
+
+Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph. These are:
+- **Single points of failure** — if they break, cascading failures occur
+- **Integration points** — good places for interfaces/contracts
+- **Refactoring targets** — often too much responsibility concentrated in one place
+
+### 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.
+
+### 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.
+
+## Decision Points
+
+| Question | Tool |
+|----------|------|
+| "What are the main modules?" | `list_communities` |
+| "What are the most important functions?" | `find_central_symbols` with method=pagerank |
+| "Where are the bottlenecks?" | `find_bridge_symbols` |
+| "How does a request flow through the system?" | `list_processes` → `get_process_flow` |
+| "What's the entry point for feature X?" | `list_processes`, then filter by name |

package/skills/commands/memtrace-impact.md

@@ -0,0 +1,61 @@
+---
+name: memtrace-impact
+description: "Use when the user asks about blast radius, what will break if I change this, risk of modifying a symbol, upstream or downstream dependencies, impact analysis before refactoring, or wants to understand the consequences of a code change"
+allowed-tools:
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+user-invocable: true
+---
+
+## 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 |
+
+## 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/skills/commands/memtrace-index.md

@@ -0,0 +1,63 @@
+---
+name: memtrace-index
+description: "Use when the user asks to index a project, set up code intelligence, parse a codebase, build a knowledge graph, prepare a repo for analysis, or as the very first step before any code exploration, search, or relationship analysis"
+allowed-tools:
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__check_job_status
+  - mcp__memtrace__list_jobs
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## 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 |
+
+## 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.
+
+### 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/skills/commands/memtrace-quality.md

@@ -0,0 +1,66 @@
+---
+name: memtrace-quality
+description: "Use when the user asks about dead code, unused functions, code complexity, cyclomatic complexity, refactoring candidates, code smells, code quality metrics, functions that are too complex, or wants to find code that should be cleaned up"
+allowed-tools:
+  - mcp__memtrace__find_dead_code
+  - mcp__memtrace__calculate_cyclomatic_complexity
+  - mcp__memtrace__find_most_complex_functions
+  - mcp__memtrace__get_repository_stats
+user-invocable: true
+---
+
+## 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 |
+
+## 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/skills/commands/memtrace-relationships.md

@@ -0,0 +1,70 @@
+---
+name: memtrace-relationships
+description: "Use when the user asks who calls a function, what a function calls, class hierarchy, inheritance, imports, exports, type usages, dependencies between symbols, or wants to understand how code connects before making changes"
+allowed-tools:
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+user-invocable: true
+---
+
+## 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? |
+
+## 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/skills/commands/memtrace-search.md

@@ -0,0 +1,62 @@
+---
+name: memtrace-search
+description: "Use when the user asks to find code, search for a function, locate a symbol, look up where something is defined, search across repos, find implementations, or needs to discover where a piece of logic lives before making changes"
+allowed-tools:
+  - mcp__memtrace__find_code
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## 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 |
+
+## 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
+
+**find_code parameters:**
+- `query` — natural-language or exact text (required)
+- `repo_id` — scope to a single repo (optional; omit to search all)
+- `kind` — filter by symbol type: Function, Class, Method, Interface, APIEndpoint, APICall
+- `limit` — max results (default 10)
+- `as_of` — ISO-8601 timestamp for time-travel search
+
+**find_symbol parameters:**
+- `name` — exact or partial symbol name (required)
+- `fuzzy` — enable Levenshtein correction (default false)
+- `repo_id` — scope to a single repo (optional)
+- `kind` — filter by symbol type
+- `file_path` — filter by file path substring
+
+**Success criteria:** Results include `file_path`, `start_line`, `kind`, and relevance `score`.
+
+### 3. Use results for next steps
+
+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
+
+## 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 |

package/skills/workflows/memtrace-change-impact-analysis.md

@@ -0,0 +1,85 @@
+---
+name: memtrace-change-impact-analysis
+description: "Use when the user is about to modify code, planning a refactoring, wants to know what will break, needs a pre-change risk assessment, is reviewing a PR, or wants to understand the full consequences of a code change before making it"
+allowed-tools:
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## 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/skills/workflows/memtrace-codebase-exploration.md

@@ -0,0 +1,108 @@
+---
+name: memtrace-codebase-exploration
+description: "Use when the user asks to explore a codebase, understand a project, onboard to a new repo, get an overview of how code is structured, map the architecture, or wants a comprehensive understanding of a codebase they're new to"
+allowed-tools:
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__check_job_status
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_repository_stats
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__list_processes
+  - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__find_bridge_symbols
+  - mcp__memtrace__find_api_endpoints
+  - mcp__memtrace__get_api_topology
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__find_most_complex_functions
+user-invocable: true
+---
+
+## 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 `method: "pagerank"` and `limit: 15`.
+
+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/skills/workflows/memtrace-incident-investigation.md

@@ -0,0 +1,104 @@
+---
+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
+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)
+
+## 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 | Mode | Why |
+|-------|------|-----|
+| Initial triage | `recent` | Time-weighted ranking surfaces changes near the incident |
+| Anomaly detection | `novel` | Catches unexpected changes to stable code |
+| Scope assessment | `impact` | Ranks by structural significance (blast radius) |
+| Direction analysis | `directional` | Separates added/removed/modified |
+| Quick summary | `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 |

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