memtrace 0.1.2-2.5

package/README.md

@@ -0,0 +1,242 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/syncable-dev/memtrace-public/main/assets/logo.svg" alt="Memtrace" width="120" height="120" />
+</p>
+
+<h1 align="center">Memtrace</h1>
+
+<p align="center">
+  <strong>Code intelligence graph for AI agents</strong><br/>
+  Structural search · Relationship analysis · Temporal evolution · Architectural understanding
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/memtrace"><img src="https://img.shields.io/npm/v/memtrace?style=flat-square&color=00D4B8&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/memtrace"><img src="https://img.shields.io/npm/dm/memtrace?style=flat-square&color=0A1628&label=downloads" alt="npm downloads" /></a>
+  <a href="https://github.com/syncable-dev/memtrace-public/stargazers"><img src="https://img.shields.io/github/stars/syncable-dev/memtrace-public?style=flat-square&color=00D4B8" alt="GitHub stars" /></a>
+  <a href="https://github.com/syncable-dev/memtrace-public/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Proprietary%20EULA-0A1628?style=flat-square" alt="license" /></a>
+  <a href="https://memtrace.dev"><img src="https://img.shields.io/badge/docs-memtrace.dev-00D4B8?style=flat-square" alt="docs" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#skills">Skills</a> ·
+  <a href="#mcp-tools">MCP Tools</a> ·
+  <a href="#evolution-engine">Evolution Engine</a> ·
+  <a href="#claude-code-setup">Claude Code</a> ·
+  <a href="#claude-desktop-setup">Claude Desktop</a>
+</p>
+
+---
+
+Memtrace is an MCP server that builds a **persistent knowledge graph** from your codebase. It parses source files, resolves cross-file relationships, detects API endpoints, runs community detection, and embeds all symbols for semantic search — then exposes 25+ tools via the [Model Context Protocol](https://modelcontextprotocol.io) so AI agents can explore, analyze, and reason about your code structurally.
+
+## Quick Start
+
+```bash
+# Install (binary + skills + MCP server — all in one)
+npm install -g memtrace
+
+# Start the graph database
+memtrace start
+
+# Index your project
+memtrace index /path/to/your/project
+```
+
+That's it. The installer handles everything:
+
+| Step | What happens |
+|------|-------------|
+| **Binary** | Platform-specific native binary installed via npm |
+| **Skills** | 12 AI agent skills written to `~/.claude/skills/` and plugin cache |
+| **Plugin** | `memtrace-skills@memtrace` enabled in `~/.claude/settings.json` |
+| **Marketplace** | GitHub marketplace registered for auto-updates |
+| **MCP Server** | `memtrace mcp` registered in `mcpServers` |
+
+> **Zero configuration required** — just install and start exploring your codebase with Claude.
+
+## Skills
+
+Memtrace ships with **12 skills** that teach Claude _how_ to use the knowledge graph. Skills fire automatically based on what you ask.
+
+### Command Skills
+
+| Skill | Triggers when you say... |
+|:------|:------------------------|
+| `memtrace-index` | _"index this project"_, _"set up code intelligence"_, _"parse this codebase"_ |
+| `memtrace-search` | _"find this function"_, _"where is X defined"_, _"search for authentication logic"_ |
+| `memtrace-relationships` | _"who calls this"_, _"what does this function call"_, _"show class hierarchy"_ |
+| `memtrace-evolution` | _"what changed this week"_, _"how did this evolve"_, _"what's different since Monday"_ |
+| `memtrace-impact` | _"what will break if I change this"_, _"blast radius"_, _"risk assessment"_ |
+| `memtrace-quality` | _"find dead code"_, _"complexity hotspots"_, _"code smells"_ |
+| `memtrace-graph` | _"show me the architecture"_, _"find bottlenecks"_, _"most important functions"_ |
+| `memtrace-api-topology` | _"list API endpoints"_, _"service dependencies"_, _"who calls this API"_ |
+
+### Workflow Skills
+
+Multi-step orchestrations that chain tools together with decision logic:
+
+| Skill | Triggers when you say... |
+|:------|:------------------------|
+| `memtrace-codebase-exploration` | _"explore this codebase"_, _"I'm new to this project"_, _"give me an overview"_ |
+| `memtrace-change-impact-analysis` | _"what will break if I refactor this"_, _"pre-change risk assessment"_ |
+| `memtrace-incident-investigation` | _"something broke"_, _"root cause analysis"_, _"what went wrong"_ |
+| `memtrace-refactoring-guide` | _"help me refactor"_, _"reduce complexity"_, _"clean up tech debt"_ |
+
+## MCP Tools
+
+25+ tools exposed via the Model Context Protocol:
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**Search & Discovery**
+- `find_code` — hybrid BM25 + semantic search with RRF
+- `find_symbol` — exact/fuzzy name match with Levenshtein
+
+**Relationships**
+- `analyze_relationships` — callers, callees, hierarchy, imports
+- `get_symbol_context` — 360° view in one call
+
+**Impact Analysis**
+- `get_impact` — blast radius with risk rating
+- `detect_changes` — diff-to-symbols scope mapping
+
+**Code Quality**
+- `find_dead_code` — zero-caller detection
+- `find_most_complex_functions` — complexity hotspots
+- `calculate_cyclomatic_complexity` — per-symbol scoring
+- `get_repository_stats` — repo-wide metrics
+
+</td>
+<td width="50%" valign="top">
+
+**Temporal Analysis**
+- `get_evolution` — 6 scoring modes (see below)
+- `get_timeline` — full symbol version history
+- `detect_changes` — diff-based impact scope
+
+**Graph Algorithms**
+- `find_bridge_symbols` — betweenness centrality
+- `find_central_symbols` — PageRank / degree
+- `list_communities` — Louvain module detection
+- `list_processes` / `get_process_flow` — execution tracing
+
+**API Topology**
+- `get_api_topology` — cross-repo HTTP call graph
+- `find_api_endpoints` — all exposed routes
+- `find_api_calls` — all outbound HTTP calls
+
+**Indexing & Watch**
+- `index_directory` — parse, resolve, embed
+- `watch_directory` — live incremental re-indexing
+- `execute_cypher` — direct graph queries
+
+</td>
+</tr>
+</table>
+
+## Evolution Engine
+
+The temporal analysis engine implements **six distinct scoring algorithms** — choose the right one for the question you're asking:
+
+| Mode | Formula | Best for |
+|:-----|:--------|:---------|
+| **`compound`** | `0.50 × rank(impact) + 0.35 × rank(novel) + 0.15 × rank(recent)` | General-purpose _"what changed?"_ |
+| **`impact`** | `sig(n) = in_degree^0.7 × (1 + out_degree)^0.3` | _"What broke?"_ — largest blast radius |
+| **`novel`** | `surprise(n) = (1 + in_degree) / (1 + change_freq_90d)` | _"What's unexpected?"_ — anomaly detection |
+| **`recent`** | `impact × exp(−0.5 × Δhours)` | _"What changed near the incident?"_ |
+| **`directional`** | Asymmetric: added → out_degree, removed → in_degree | _"What was added vs removed?"_ |
+| **`overview`** | Module-level rollup only | Quick summary, no per-symbol scoring |
+
+Uses **Structural Significance Budgeting (SSB)** to select the minimum set of changes covering ≥80% of total significance — surfaces what matters without drowning you in noise.
+
+## Claude Code Setup
+
+`npm install -g memtrace` handles everything. For manual setup:
+
+```bash
+# 1. Register the marketplace
+claude plugin marketplace add syncable-dev/memtrace
+
+# 2. Install the skills plugin
+claude plugin install memtrace-skills@memtrace --scope user
+
+# 3. Register the MCP server
+claude mcp add memtrace -- memtrace mcp -e MEMGRAPH_URL=bolt://localhost:7687
+```
+
+<details>
+<summary><strong>What this writes to <code>~/.claude/settings.json</code></strong></summary>
+
+```json
+{
+  "mcpServers": {
+    "memtrace": {
+      "command": "memtrace",
+      "args": ["mcp"],
+      "env": { "MEMGRAPH_URL": "bolt://localhost:7687" }
+    }
+  },
+  "enabledPlugins": {
+    "memtrace-skills@memtrace": true
+  },
+  "extraKnownMarketplaces": {
+    "memtrace": {
+      "source": { "source": "github", "repo": "syncable-dev/memtrace" }
+    }
+  }
+}
+```
+
+</details>
+
+### Installing skills separately
+
+```bash
+npx memtrace-skills install     # install skills + register MCP
+npx memtrace-skills uninstall   # remove everything
+```
+
+## Claude Desktop Setup
+
+Skills are installed to `~/.claude/skills/` which is shared between Claude Code and Claude Desktop — both pick up skills automatically after `npm install -g memtrace`.
+
+Add the MCP server to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memtrace": {
+      "command": "memtrace",
+      "args": ["mcp"],
+      "env": { "MEMGRAPH_URL": "bolt://localhost:7687" }
+    }
+  }
+}
+```
+
+## Supported Languages
+
+Rust · Go · TypeScript · JavaScript · Python · Java · C · C++ · C# · Swift · Kotlin · Ruby · PHP · Dart · Scala · Perl — and more via Tree-sitter.
+
+## Requirements
+
+| Dependency | Purpose |
+|:-----------|:--------|
+| **Memgraph** | Knowledge graph backend — auto-managed via `memtrace start` |
+| **Node.js ≥ 18** | npm installation |
+| **Git** | Temporal analysis (commit history) |
+
+## Links
+
+- [Documentation](https://memtrace.dev)
+- [npm Package](https://www.npmjs.com/package/memtrace)
+- [Report an Issue](https://github.com/syncable-dev/memtrace-public/issues)
+
+---
+
+<p align="center">
+  <sub>Built by <a href="https://syncable.dev">Syncable</a> · <a href="LICENSE">Proprietary EULA</a> · Free to use</sub>
+</p>

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,236 @@
+#!/usr/bin/env node
+"use strict";
+
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+const { execSync } = require("child_process");
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const PLUGIN_NAME = "memtrace-skills";
+const MARKETPLACE_NAME = "memtrace";
+const MARKETPLACE_REPO = "syncable-dev/memtrace-public";
+
+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",
+};
+
+// ── Binary helpers ────────────────────────────────────────────────────────────
+
+function getPlatformKey() {
+  return `${os.platform()}-${os.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`
+    );
+  }
+}
+
+// ── Skill installation ───────────────────────────────────────────────────────
+
+function installSkills() {
+  const skillsSrc = path.join(__dirname, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    console.warn("memtrace: skills directory not found, skipping skill installation");
+    return;
+  }
+
+  const claudeSkillsDir = path.join(os.homedir(), ".claude", "skills");
+
+  // Collect all .md skill files from commands/ and workflows/
+  const skillDirs = ["commands", "workflows"];
+  let installed = 0;
+
+  for (const dir of skillDirs) {
+    const srcDir = path.join(skillsSrc, dir);
+    if (!fs.existsSync(srcDir)) continue;
+
+    const files = fs.readdirSync(srcDir).filter(f => f.endsWith(".md"));
+    for (const file of files) {
+      const skillName = file.replace(/\.md$/, "");
+      const destDir = path.join(claudeSkillsDir, skillName);
+      const srcFile = path.join(srcDir, file);
+
+      try {
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.copyFileSync(srcFile, path.join(destDir, "SKILL.md"));
+        installed++;
+      } catch (e) {
+        console.warn(`memtrace: failed to install skill ${skillName}: ${e.message}`);
+      }
+    }
+  }
+
+  if (installed > 0) {
+    console.log(`memtrace: installed ${installed} skills to ${claudeSkillsDir}`);
+  }
+}
+
+// ── Settings.json helpers ────────────────────────────────────────────────────
+
+function readSettings() {
+  const settingsFile = path.join(os.homedir(), ".claude", "settings.json");
+  if (fs.existsSync(settingsFile)) {
+    try {
+      return JSON.parse(fs.readFileSync(settingsFile, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+function writeSettings(settings) {
+  const settingsFile = path.join(os.homedir(), ".claude", "settings.json");
+  fs.mkdirSync(path.dirname(settingsFile), { recursive: true });
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + "\n");
+}
+
+// ── MCP server registration ─────────────────────────────────────────────────
+
+function registerMcpServer(binaryPath) {
+  const settings = readSettings();
+
+  if (!settings.mcpServers || typeof settings.mcpServers !== "object") {
+    settings.mcpServers = {};
+  }
+
+  settings.mcpServers.memtrace = {
+    command: binaryPath,
+    args: ["mcp"],
+    env: {
+      MEMGRAPH_URL: "bolt://localhost:7687",
+    },
+  };
+
+  writeSettings(settings);
+  console.log("memtrace: registered MCP server in ~/.claude/settings.json");
+}
+
+// ── Plugin + marketplace registration ────────────────────────────────────────
+
+function enablePlugin() {
+  const settings = readSettings();
+
+  // Enable plugin
+  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== "object") {
+    settings.enabledPlugins = {};
+  }
+  const pluginKey = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+  settings.enabledPlugins[pluginKey] = true;
+
+  // Register marketplace
+  if (!settings.extraKnownMarketplaces || typeof settings.extraKnownMarketplaces !== "object") {
+    settings.extraKnownMarketplaces = {};
+  }
+  settings.extraKnownMarketplaces[MARKETPLACE_NAME] = {
+    source: {
+      source: "github",
+      repo: MARKETPLACE_REPO,
+    },
+  };
+
+  writeSettings(settings);
+  console.log(`memtrace: enabled plugin ${pluginKey}`);
+  console.log(`memtrace: registered marketplace ${MARKETPLACE_NAME}`);
+}
+
+// ── Try Claude CLI install first ─────────────────────────────────────────────
+
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tryClaudeCliInstall() {
+  if (!commandExists("claude")) return false;
+
+  try {
+    execSync(`claude plugin marketplace add ${MARKETPLACE_REPO}`, {
+      stdio: "ignore",
+      timeout: 15000,
+    });
+    execSync(`claude plugin install ${PLUGIN_NAME}@${MARKETPLACE_NAME} --scope user`, {
+      stdio: "ignore",
+      timeout: 15000,
+    });
+    console.log("memtrace: installed skills via Claude CLI");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Main postinstall ─────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  // 1. Verify binary
+  let binaryPath = null;
+  try {
+    binaryPath = getBinaryPath();
+    if (!fs.existsSync(binaryPath)) {
+      throw new Error(`Binary not found at: ${binaryPath}`);
+    }
+    if (os.platform() !== "win32") {
+      fs.chmodSync(binaryPath, 0o755);
+    }
+    console.log(`memtrace: binary installed at ${binaryPath}`);
+  } catch (e) {
+    console.warn(`memtrace: ${e.message}`);
+  }
+
+  // 2. Install skills to ~/.claude/skills/
+  try {
+    installSkills();
+  } catch (e) {
+    console.warn(`memtrace: skill installation failed: ${e.message}`);
+  }
+
+  // 3. Try Claude CLI first, fall back to manual settings
+  try {
+    if (!tryClaudeCliInstall()) {
+      enablePlugin();
+    }
+  } catch (e) {
+    console.warn(`memtrace: plugin registration failed: ${e.message}`);
+  }
+
+  // 4. Register MCP server
+  if (binaryPath) {
+    try {
+      registerMcpServer(binaryPath);
+    } catch (e) {
+      console.warn(`memtrace: MCP server registration failed: ${e.message}`);
+    }
+  }
+}
+
+module.exports = { getBinaryPath };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "memtrace",
+  "version": "0.1.22.5",
+  "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-public"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "memtrace": "bin/memtrace.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "install.js"
+  ],
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "optionalDependencies": {
+    "@memtrace/darwin-arm64": "0.1.22.5",
+    "@memtrace/linux-x64": "0.1.22.5",
+    "@memtrace/win32-x64": "0.1.22.5"
+  },
+  "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 |