memtrace 0.1.38 → 0.1.45

package/installer/dist/transformers/cursor.js

@@ -0,0 +1,84 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+function skillsRoot(ctx) {
+    const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
+    return path.join(base, '.cursor', 'skills');
+}
+function mcpPath(ctx) {
+    const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
+    return path.join(base, '.cursor', 'mcp.json');
+}
+function writeSkill(skill, rootDir) {
+    const name = skill.filename.replace(/\.md$/, '');
+    const outDir = path.join(rootDir, name);
+    fs.mkdirSync(outDir, { recursive: true });
+    const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+    // Cursor requires frontmatter `name` matching the folder name.
+    const content = `---\nname: ${name}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
+    fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
+}
+export function registerCursorMcpAt(mcpFile, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(mcpFile);
+    if (corrupted) {
+        console.warn(`memtrace: ${mcpFile} is malformed; backed up to ${backupPath}. Skipped Cursor MCP registration.`);
+        return { registered: false, backupPath };
+    }
+    const cfg = (value ?? {});
+    cfg.mcpServers = cfg.mcpServers ?? {};
+    cfg.mcpServers['memtrace'] = {
+        command: binary,
+        args: ['mcp'],
+        env: { MEMGRAPH_URL: 'bolt://localhost:7687' },
+    };
+    writeJsonAtomic(mcpFile, cfg);
+    return { registered: true };
+}
+export const cursorTransformer = {
+    name: 'cursor',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        for (const s of skills)
+            writeSkill(s, rootDir);
+        let mcpRegistered = false;
+        if (!ctx.skipMcp) {
+            const result = registerCursorMcpAt(mcpPath(ctx), ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+        }
+        return {
+            agent: 'cursor',
+            skillsWritten: skills.length,
+            skillsDir: rootDir,
+            mcpConfigPath: mcpPath(ctx),
+            mcpRegistered,
+            warnings: [],
+        };
+    },
+    async uninstall(ctx) {
+        // 1. Remove memtrace-* skill dirs
+        const rootDir = skillsRoot(ctx);
+        if (fs.existsSync(rootDir)) {
+            for (const entry of fs.readdirSync(rootDir)) {
+                if (entry.startsWith('memtrace-')) {
+                    fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
+                }
+            }
+        }
+        // 2. Remove memtrace entry from mcp.json; delete file if empty
+        const mcpFile = mcpPath(ctx);
+        const { value, corrupted } = safeReadJson(mcpFile);
+        if (!corrupted && value?.mcpServers?.['memtrace']) {
+            delete value.mcpServers['memtrace'];
+            if (Object.keys(value.mcpServers).length === 0) {
+                delete value.mcpServers;
+            }
+            if (Object.keys(value).length === 0) {
+                fs.unlinkSync(mcpFile);
+            }
+            else {
+                writeJsonAtomic(mcpFile, value);
+            }
+        }
+    },
+};

package/installer/dist/transformers/index.d.ts

@@ -0,0 +1,7 @@
+import { Transformer } from './types.js';
+import { claudeTransformer } from './claude.js';
+import { cursorTransformer } from './cursor.js';
+export declare const ALL_TRANSFORMERS: Transformer[];
+export declare function findTransformer(name: string): Transformer | undefined;
+export { claudeTransformer, cursorTransformer };
+export type { Transformer, InstallContext, InstallResult, TransformResult } from './types.js';

package/installer/dist/transformers/index.js

@@ -0,0 +1,7 @@
+import { claudeTransformer } from './claude.js';
+import { cursorTransformer } from './cursor.js';
+export const ALL_TRANSFORMERS = [claudeTransformer, cursorTransformer];
+export function findTransformer(name) {
+    return ALL_TRANSFORMERS.find(t => t.name === name);
+}
+export { claudeTransformer, cursorTransformer };

package/installer/dist/transformers/types.d.ts

@@ -0,0 +1,39 @@
+import { Skill } from '../skills.js';
+/**
+ * A single file to write for a given agent.
+ */
+export interface TransformResult {
+    /** Relative path from the agent's root skill directory. */
+    relativePath: string;
+    /** File content (UTF-8 text). */
+    content: string;
+}
+/**
+ * Runtime context passed to every transformer during install/uninstall.
+ */
+export interface InstallContext {
+    /** 'global' = write to ~/.<agent>/; 'local' = write to cwd's .<agent>/ */
+    scope: 'global' | 'local';
+    /** Used for local scope. Absolute path. */
+    cwd: string;
+    /** Command or absolute path used as the MCP server command. */
+    memtraceBinary: string;
+    /** When true, write skills but skip MCP registration. */
+    skipMcp?: boolean;
+}
+export interface InstallResult {
+    agent: string;
+    skillsWritten: number;
+    skillsDir: string;
+    mcpConfigPath?: string;
+    mcpRegistered: boolean;
+    warnings: string[];
+}
+/**
+ * One transformer per supported AI coding agent.
+ */
+export interface Transformer {
+    name: 'claude' | 'cursor';
+    install(skills: Skill[], ctx: InstallContext): Promise<InstallResult>;
+    uninstall(ctx: InstallContext): Promise<void>;
+}

package/installer/dist/transformers/types.js

@@ -0,0 +1 @@
+export {};

package/installer/dist/utils.d.ts

@@ -0,0 +1,5 @@
+export interface ExecOptions {
+    timeoutMs?: number;
+}
+export declare function execCommand(command: string, opts?: ExecOptions): Promise<string>;
+export declare function commandExists(cmd: string): Promise<boolean>;

package/installer/dist/utils.js

@@ -0,0 +1,22 @@
+import { exec } from 'child_process';
+export function execCommand(command, opts = {}) {
+    const timeout = opts.timeoutMs ?? 30_000;
+    return new Promise((resolve, reject) => {
+        exec(command, { timeout }, (error, stdout, stderr) => {
+            if (error)
+                reject(new Error(`Command failed: ${command}\n${stderr || error.message}`));
+            else
+                resolve(stdout.trim());
+        });
+    });
+}
+export async function commandExists(cmd) {
+    try {
+        const which = process.platform === 'win32' ? 'where' : 'which';
+        await execCommand(`${which} ${cmd}`, { timeoutMs: 5_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/installer/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "memtrace-skills",
+  "version": "0.1.0",
+  "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
+  "type": "module",
+  "bin": {
+    "memtrace-skills": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "plugins/",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "node scripts/copy-skills.js",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "fs-extra": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.0",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncable-dev/memtrace"
+  },
+  "keywords": [
+    "memtrace",
+    "code-intelligence",
+    "mcp",
+    "skills",
+    "claude-code",
+    "ai-agent"
+  ]
+}

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

@@ -0,0 +1,65 @@
+---
+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 |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Discover endpoints
+
+Use `find_api_endpoints`:
+- `repo_id` — required
+- Returns: method, path, handler function, framework detected
+
+### 2. Discover outbound calls
+
+Use `find_api_calls`:
+- `repo_id` — required
+- Returns: target URL/path, HTTP method, calling function, library used (fetch, axios, reqwest, etc.)
+
+### 3. Map service topology
+
+Use `get_api_topology` to see the cross-repo HTTP call graph:
+- Which services call which endpoints
+- Confidence scores for each detected link
+- Service-to-service dependency direction
+
+**Prerequisite:** Multiple repos must be indexed. If cross-repo links aren't appearing, use `link_repositories` to explicitly connect them.
+
+### 4. Deep-dive into an endpoint
+
+For any specific endpoint, use `get_symbol_context` with the endpoint's symbol ID to see:
+- Which internal functions handle the request
+- Which processes (execution flows) include this endpoint
+- Which external services call this endpoint
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Expecting cross-repo links with only one repo indexed | Index ALL related services first; cross-repo HTTP edges are linked automatically after indexing |
+| Missing endpoints from custom frameworks | Memtrace auto-detects major frameworks; for custom routers, the endpoints may appear as regular functions |
+| Not using `link_repositories` | If auto-linking missed a connection, use this to manually establish cross-repo edges |

package/installer/skills/commands/memtrace-cochange.md

@@ -0,0 +1,76 @@
+---
+name: memtrace-cochange
+description: "Use when the user asks what tends to change together with a symbol, what other code moves when this moves, historical coupling, blast awareness before modifying a symbol, or wants to find hidden dependencies not visible in the call graph"
+allowed-tools:
+  - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__get_impact
+user-invocable: true
+---
+
+## Overview
+
+Find symbols that historically co-change with a target symbol — ranked by co-occurrence frequency across all episodes. This surfaces **behavioral coupling** that the static call graph cannot see.
+
+`get_impact` answers "who calls this?" (structural).
+`get_cochange_context` answers "what always moves when this moves?" (historical).
+
+They are complementary. A symbol with no direct callers can still have strong cochange partners if it's always modified alongside another in every commit.
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Identify the target symbol
+
+Use `find_symbol` if you need the exact name. The tool matches by `name` field.
+
+### 2. Call `get_cochange_context`
+
+```
+get_cochange_context(
+  repo_id: "...",
+  symbol: "execute",    // exact symbol name
+  limit: 20             // default 20, increase for broader view
+)
+```
+
+### 3. Interpret results
+
+The response contains `cochanges[]`, each with:
+- `name` — symbol name
+- `kind` — Function / Method / Class / Struct
+- `file_path` — where it lives
+- `cochange_count` — how many episodes it shared with the target
+
+```
+High cochange_count = strong historical coupling
+→ If you modify the target, you will likely need to touch this too
+→ Or it may be the real root cause you should investigate first
+```
+
+### 4. Cross-reference with call graph
+
+For the top cochange partners, optionally run `get_impact` to see if the coupling is also structural:
+
+| Structural coupling | Historical coupling | Interpretation |
+|---|---|---|
+| Yes | Yes | Core architectural dependency — highest risk |
+| No | Yes | Hidden coupling — only visible through history |
+| Yes | No | Called frequently but changed independently — lower risk |
+
+## When to Use
+
+- **Before modifying a symbol** — get blast awareness beyond what `get_impact` shows
+- **Incident investigation** — when `get_impact` doesn't explain the blast radius, check cochange history
+- **Code review** — verify that a PR touched all historically-coupled partners
+- **Refactoring** — discover implicit coupling before extracting a module
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Only using `get_impact` for blast radius | Structural coupling misses behavioral coupling — always pair with cochange |
+| Ignoring low-`in_degree` cochange partners | A rarely-called utility with high cochange_count is a strong coupling signal |
+| Using cochange as a dependency map | It's not a dependency graph — it's a change correlation. Two symbols can cochange without any direct relationship. |

package/installer/skills/commands/memtrace-evolution.md

@@ -0,0 +1,135 @@
+---
+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
+  - mcp__memtrace__get_changes_since
+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 |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Determine the time window
+
+Ask the user or infer:
+- `from` — ISO-8601 start timestamp (required)
+- `to` — ISO-8601 end timestamp (defaults to now)
+- `repo_id` — scope to a repo (call `list_indexed_repositories` if unknown)
+
+### 2. Choose the mode
+
+**Decision tree:**
+
+```
+User wants to know...
+├── "what changed?"           → compound (default)
+├── "what could have broken?" → impact
+├── "anything unexpected?"    → novel
+├── "what changed near X?"    → recent (set to to incident time)
+├── "what was added/removed?" → directional
+└── "quick summary?"          → overview
+```
+
+### 3. Execute the query
+
+Use the `get_evolution` MCP tool with:
+- `repo_id` — required
+- `from` / `to` — the time window
+- `mode` — one of: compound, impact, novel, recent, directional, overview
+
+### 4. Interpret results
+
+The response contains:
+
+- **`added[]`** — new symbols that appeared in the time window
+- **`removed[]`** — symbols that were deleted
+- **`modified[]`** — symbols that changed
+- **`by_module[]`** — module-level rollup (NEVER truncated — always shows all modules)
+- **`significance_coverage`** — fraction of total significance captured (target: ≥0.80)
+- **`budget_exhausted`** — if true, there were more significant changes than the budget allowed
+
+Each symbol includes: `name`, `kind`, `file_path`, `scope_path`, `in_degree`, `out_degree`, and all four scores (`impact`, `novel`, `recent`, `compound`).
+
+### 5. Drill deeper
+
+- **For a single symbol's full history:** Use `get_timeline` with the symbol name
+- **For diff-based change scope:** Use `detect_changes` when you have a specific diff/patch
+- **For blast radius of a specific change:** Use `get_impact` on high-scoring symbols
+
+## Scoring Algorithms — Detailed Reference
+
+### Impact Score (Structural Significance Budgeting)
+```
+sig(n) = in_degree^0.7 × (1 + out_degree)^0.3
+```
+- Heavily weights callers (in_degree) — symbols called by many others have high blast radius
+- Mild boost for outbound complexity (out_degree) — complex functions that changed are notable
+- SSB selects the minimum set covering ≥80% of total significance mass
+
+### Novelty Score (Change Surprise Index)
+```
+surprise(n) = (1 + in_degree) / (1 + change_freq_90d)
+```
+- High in_degree + low change frequency = **maximum surprise**
+- A core utility that hasn't changed in 90 days suddenly changing → likely worth investigating
+- Low in_degree + high frequency = routine churn, deprioritized
+
+### Recent Score (Temporal Proximity Weighting)
+```
+recent(n) = impact(n) × exp(−0.5 × |Δhours to reference|)
+```
+- Exponential decay from the reference timestamp (the `to` parameter)
+- Changes close to an incident get amplified; older changes fade
+- Best for incident timelines: set `to` to the incident timestamp
+
+### Compound Score (Rank Fusion)
+```
+compound = 0.50×rank(impact) + 0.35×rank(novel) + 0.15×rank(recent)
+```
+- Rank-based fusion avoids scale sensitivity between different score types
+- Impact-dominant but boosted by novelty and recency
+- Best default when you don't have a specific hypothesis
+
+## Auto-overview Safety
+
+If a time window produces more than 500 candidates and mode is not `overview`, the query **automatically downgrades to overview mode** and returns `auto_overview: true`. This prevents timeouts on wide windows. When you see `auto_overview: true`:
+- Narrow the window, OR
+- Switch to `get_changes_since` (which handles this automatically), OR
+- Use the `by_module` rollup to identify the specific area and query a tighter window
+
+## Session-Aware Alternative
+
+If you're resuming work after a break and don't know the right `from` timestamp, use `get_changes_since` instead — it accepts a `last_episode_id` anchor and never requires timestamp guessing.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Using `overview` when user needs details | Overview only gives module-level counts — use `compound` for symbol-level |
+| Ignoring `budget_exhausted` flag | If true, there are more significant changes beyond what was returned — narrow the time window or use module rollup |
+| Not checking `by_module` first | Module rollup is never truncated — scan it to identify which areas changed before diving into symbol-level |
+| Using `recent` without setting `to` | The `to` timestamp is the reference point for proximity weighting — set it to the incident/event time |
+| Guessing timestamps when resuming work | Use `get_changes_since` with a stored `session_anchor` instead — exact episode boundary, no guessing |

package/installer/skills/commands/memtrace-graph.md

@@ -0,0 +1,117 @@
+---
+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 |
+
+## 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:
+
+**`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
+
+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
+
+**`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).
+
+**`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 |
+|----------|------|
+| "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 |