memtrace 0.3.10 → 0.3.12

package/README.md

@@ -297,6 +297,27 @@ Already ran `npm uninstall` first? The cleanup script is persisted at `~/.memtra
 node ~/.memtrace/uninstall.js
 ```
 
+### A note on install
+
+`npm install -g memtrace` ships a small main package + a platform-specific binary (one of `@memtrace/darwin-arm64`, `@memtrace/linux-x64`, or `@memtrace/win32-x64`) that npm picks automatically.
+
+Most setups just work. If `memtrace start` ever says **"Could not find binary for your platform"**, any of these will fix it:
+
+```bash
+# Option 1 — re-run install, asking npm to keep optional deps
+npm install -g memtrace --include=optional
+
+# Option 2 — refresh from latest
+memtrace install                  # built-in self-update
+# or:
+npm install -g memtrace@latest --force
+
+# Option 3 — install the platform binary directly (Apple Silicon shown — swap for your platform)
+npm install -g @memtrace/darwin-arm64
+```
+
+This typically only happens on machines where npm is configured to skip optional dependencies (some corporate npmrc setups, certain CI caches). Postinstall self-heals on most installs; the options above cover the rest.
+
 ## Languages
 
 Rust · Go · TypeScript · JavaScript · Python · Java · C · C++ · C# · Swift · Kotlin · Ruby · PHP · Dart · Scala · Perl — and more via Tree-sitter.

package/bin/memtrace.js

@@ -13,6 +13,64 @@ const { getBinaryPath } = require("../install.js");
 
 const args = process.argv.slice(2);
 
+// ── Handle `memtrace install` — always pull latest, then run remaining args ──
+//
+// `npm install -g memtrace` fetches latest from the registry on a fresh
+// install, but a user who already has memtrace 0.3.4 globally will not
+// receive 0.3.5 unless they explicitly re-run `npm install`. This
+// subcommand runs the upgrade for them and then chains to whatever
+// command they actually wanted: `memtrace install start` upgrades AND
+// boots the daemon; `memtrace install index .` upgrades AND indexes.
+//
+// We use `spawnSync` so output streams in real time. After the npm
+// upgrade completes, we shell out to `memtrace <rest>` via PATH —
+// which now resolves to the freshly-installed shim, not this old one.
+
+if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const memtraceCmd = process.platform === "win32" ? "memtrace.cmd" : "memtrace";
+
+  process.stdout.write("memtrace: fetching latest from npm registry…\n");
+  const installResult = spawnSync(
+    npmCmd,
+    ["install", "-g", "memtrace@latest"],
+    { stdio: "inherit", env: process.env }
+  );
+
+  if (installResult.error) {
+    console.error(
+      `memtrace install: failed to spawn npm — ${installResult.error.message}\n` +
+      `Is npm on your PATH? Try: which npm`
+    );
+    process.exit(1);
+  }
+  if (installResult.status !== 0) {
+    console.error("memtrace install: npm install -g memtrace@latest failed");
+    process.exit(installResult.status ?? 1);
+  }
+
+  const rest = args.slice(1);
+  if (rest.length === 0) {
+    process.stdout.write("memtrace: latest installed.\n");
+    process.exit(0);
+  }
+
+  // Chain into the upgraded binary. PATH now resolves `memtrace` to the
+  // newly-installed shim, so we get the latest behaviour for free.
+  process.stdout.write(
+    `memtrace: upgrade complete — running 'memtrace ${rest.join(" ")}'\n`
+  );
+  const runResult = spawnSync(memtraceCmd, rest, {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (runResult.error) {
+    console.error(`memtrace: failed to chain command — ${runResult.error.message}`);
+    process.exit(1);
+  }
+  process.exit(runResult.status ?? 0);
+}
+
 if (args[0] === "uninstall" || args[0] === "cleanup") {
   const candidates = [
     path.join(__dirname, "..", "uninstall.js"),
@@ -106,22 +164,26 @@ function checkForUpdate(currentVersion) {
   });
 }
 
-// ── MCP mode: async spawn so the event loop stays alive for the update check ─
+// ── Fire the (cached) update check in the background, regardless of mode ────
+// Cache lives in ~/.memtrace/update-check.json with a 24 h TTL, so we hit
+// registry.npmjs.org at most once per day per user. Result is printed to
+// stderr when a newer version exists. The check is non-blocking and never
+// fails the user's command.
+
+const { version: currentVersion } = require("../package.json");
+const updateCheckPromise = checkForUpdate(currentVersion).then((latest) => {
+  if (latest) {
+    process.stderr.write(
+      `\n[memtrace] Update available: ${currentVersion} → ${latest}\n` +
+      `           Run: \x1b[1mmemtrace install\x1b[0m   ` +
+      `(upgrades + can chain commands, e.g. \`memtrace install start\`)\n\n`
+    );
+  }
+});
 
 if (args[0] === "mcp") {
-  const { version: currentVersion } = require("../package.json");
-
-  // Fire the update check in the background — result prints to stderr if newer
-  checkForUpdate(currentVersion).then((latest) => {
-    if (latest) {
-      process.stderr.write(
-        `\n[memtrace] Update available: ${currentVersion} → ${latest}\n` +
-        `           Run: npm install -g memtrace\n\n`
-      );
-    }
-  });
-
-  // Use async spawn (not spawnSync) so Node's event loop keeps running
+  // MCP mode: async spawn so Node's event loop keeps running long enough
+  // for the update check to print its notice to the agent's stderr.
   const child = spawn(binaryPath, args, {
     stdio: "inherit",
     env:   process.env,
@@ -136,8 +198,10 @@ if (args[0] === "mcp") {
   });
 
 } else {
-  // ── All other commands: synchronous pass-through ────────────────────────────
-
+  // All other commands: synchronous pass-through. The update check
+  // already fired above; cache write happens in the background and we
+  // don't block on it (the http GET timeout is 3 s, well under any
+  // reasonable user-visible startup budget).
   const result = spawnSync(binaryPath, args, {
     stdio: "inherit",
     env:   process.env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -36,9 +36,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.3.10",
-    "@memtrace/linux-x64": "0.3.10",
-    "@memtrace/win32-x64": "0.3.10"
+    "@memtrace/darwin-arm64": "0.3.12",
+    "@memtrace/linux-x64": "0.3.12",
+    "@memtrace/win32-x64": "0.3.12"
   },
   "engines": {
     "node": ">=18"

package/skills/commands/memtrace-graph.md

@@ -1,42 +1,32 @@
 ---
 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"
+description: "Use when the user asks about architectural bottlenecks, important symbols, PageRank, centrality, bridge functions, code communities, logical modules, service boundaries, chokepoints, dependency paths between symbols, 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__find_dependency_path
   - 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.
+Graph algorithms that reveal the structural architecture of a codebase — community detection (Louvain), centrality ranking (PageRank), bridge symbol identification (Tarjan articulation points), shortest-path discovery, and execution flow tracing.
+
+All four algorithm tools (`find_central_symbols`, `find_bridge_symbols`, `find_dependency_path`, `list_communities`) run natively against the MemDB-backed knowledge graph — no Cypher required.
 
 ## Quick Reference
 
 | Tool | Purpose |
 |------|---------|
-| `find_bridge_symbols` | Architectural chokepoints — symbols that connect otherwise-separate modules |
-| `find_central_symbols` | Most important symbols (PageRank via ArcadeDB `algo.pagerank`) |
+| `find_bridge_symbols` | Architectural chokepoints — symbols whose removal disconnects the graph (Tarjan articulation points) |
+| `find_central_symbols` | Most important symbols by **PageRank** (default) or degree centrality |
+| `find_dependency_path` | Shortest call/import path between two symbols (BFS over typed edges) |
 | `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
 
@@ -44,77 +34,42 @@ If you see `MCP error -32602: invalid type: string "N", expected usize`, you pas
 
 Start with `list_communities` to see how the codebase is naturally partitioned into logical modules. Each community has a name, member count, and representative symbols.
 
-**`list_communities` parameters:**
-- `repo_id` — string, required. Repository ID (from `list_indexed_repositories`).
-- `branch` — string, optional. Defaults to `"main"`.
-- `min_size` — **integer**, optional. Minimum community size to include. Default `3`.
-- `limit` — **integer**, optional. Max communities to return. Default `50`, capped at `200`.
-
-Example (correct):
-```json
-{ "repo_id": "Memtrace", "limit": 20 }
-```
-Example (WRONG — will fail):
-```json
-{ "repo_id": "Memtrace", "limit": "20" }
-```
-
 ### 2. Find critical infrastructure
 
 Use `find_central_symbols` to identify the most important symbols:
+- `method: "pagerank"` — importance by link structure (default; same algorithm Google uses)
+- `method: "degree"` — importance by direct connection count
+- `limit` — how many to return
 
-**`find_central_symbols` parameters:**
-- `repo_id` — string, required.
-- `branch` — string, optional. Defaults to `"main"`.
-- `limit` — **integer**, optional. How many to return. Default `20`, capped at `100`.
-
-Returns the top-N symbols ranked by **PageRank** (ArcadeDB's native `algo.pagerank` procedure). Filters the global run to Function/Method/Class/Interface/Struct in the requested repo + branch. Falls back to in-degree centrality only if the native procedure isn't registered on the connected ArcadeDB build.
+The PageRank pass walks every CALLS / REFERENCES edge in the repo, distributes rank with the standard 0.85 damping factor, and converges on a stable ordering. The output is sorted by score descending, with each entry carrying `name`, `kind`, `file_path`, `score`, and the `in_degree`/`out_degree` it accumulated during the walk.
 
 ### 3. Find architectural chokepoints
 
-Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph. These are:
+Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph (Tarjan articulation points). 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. Discover the path between two symbols
 
-Ranks symbols by **betweenness centrality** (ArcadeDB's native `algo.betweenness` with `normalized: true`) — how many shortest paths between other symbols pass through each one. Falls back to an in-degree × out-degree heuristic only if the native procedure isn't registered.
+Use `find_dependency_path` to answer "how does symbol A reach symbol B?" — returns the shortest call/import chain via BFS over typed edges. Useful for:
+- "Why does the auth handler depend on the database client?"
+- "How does this CLI command reach the logging subsystem?"
+- "Confirm symbol X actually transitively depends on Y."
 
-### 4. Trace execution flows
+### 5. 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`.
+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, ordered by the indexed `step` property on each STEP_IN_PROCESS edge.
 
 ## Decision Points
 
 | Question | Tool |
 |----------|------|
 | "What are the main modules?" | `list_communities` |
-| "What are the most important functions?" | `find_central_symbols` (PageRank, native) |
+| "What are the most important functions?" | `find_central_symbols` with method=pagerank |
 | "Where are the bottlenecks?" | `find_bridge_symbols` |
+| "How does symbol A reach symbol B?" | `find_dependency_path` |
 | "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/workflows/memtrace-codebase-exploration.md

@@ -50,7 +50,7 @@ Each community represents a cohesive module — these are the "areas" of the cod
 
 ### 4. Find the most important symbols
 
-Call `find_central_symbols` with `limit: 15`. It ranks symbols by PageRank (ArcadeDB's native `algo.pagerank`) — no extra parameter needed.
+Call `find_central_symbols` with `limit: 15`. It ranks symbols by PageRank over the repo's CALLS / REFERENCES edges (default `method: "pagerank"`, 0.85 damping factor).
 
 These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.
 

package/skills/workflows/memtrace-continuous-memory.md

@@ -0,0 +1,104 @@
+---
+name: memtrace-continuous-memory
+description: "Use when the user asks to keep memtrace fresh while editing, watch a directory for live updates, enable incremental indexing, set up always-on memory, or wants their just-saved code to be queryable immediately"
+allowed-tools:
+  - mcp__memtrace__watch_directory
+  - mcp__memtrace__list_watched_paths
+  - mcp__memtrace__unwatch_directory
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__check_job_status
+user-invocable: true
+---
+
+## Overview
+
+Memtrace keeps the knowledge graph live as you edit. Once you call `watch_directory`, every save runs through the **incremental indexing fast-path** — a notify-based file watcher debounces saves, the indexer re-parses only the touched files, and the engine commits the delta in a single WAL transaction. Steady-state latency is **~80 ms from save to queryable** on a typical project.
+
+This is what makes "session continuity" actually work: by the time you ask `find_symbol` after a save, the new symbol is already in the graph.
+
+## Steps
+
+### 1. Confirm the repo is indexed
+
+```
+mcp__memtrace__list_indexed_repositories
+```
+
+If the repo isn't there, run `index_directory` first. The watcher requires an existing repo_id — it never bootstraps from scratch.
+
+### 2. Start watching
+
+```
+mcp__memtrace__watch_directory(
+  path: "/abs/path/to/repo"
+)
+```
+
+The tool registers a `notify` watcher on the directory tree, debounces save bursts (so a `:wq` that touches a swap file doesn't trigger twice), and routes deltas through the indexer's incremental fast-path. Returns immediately — watching runs in the background.
+
+### 3. Confirm it's live
+
+```
+mcp__memtrace__list_watched_paths
+```
+
+Each entry shows the watched root, the bound repo_id, and the last delta's `persist_ms`.
+
+### 4. Edit normally — Memtrace catches up
+
+After every save the watcher emits a `labels_updated` WebSocket event:
+
+```json
+{
+  "event":           "labels_updated",
+  "repo_id":         "demo",
+  "nodes_changed":   12,
+  "persist_ms":      78,
+  "timestamp":       "2026-04-27T10:42:13Z"
+}
+```
+
+Dashboards and IDE plugins subscribe to this on `/ws` and refresh themselves. As an agent you don't have to listen — your next `find_symbol` / `find_code` / `get_symbol_context` call will see the new state automatically.
+
+### 5. Stop watching
+
+```
+mcp__memtrace__unwatch_directory(path: "/abs/path/to/repo")
+```
+
+Idempotent — unwatching an already-unwatched path is a no-op.
+
+## When to Use
+
+- **Long sessions on the same repo** — keeps `get_symbol_context` accurate without rerunning `index_directory`
+- **Pair programming with an IDE plugin** — the dashboard's WebSocket subscription auto-refreshes panels
+- **Demo / live coding** — every save reflects in the graph within 80–150 ms
+- **Long-running agents** — instead of polling `index_directory`, the watcher pushes deltas
+
+## When NOT to Use
+
+- **One-shot batch edits** — running `index_directory --incremental` at the end is cheaper than spinning up a watcher
+- **Generated / build output trees** — exclude paths under `target/`, `dist/`, `node_modules/` (the watcher honours common ignore patterns but a noisy build can still saturate the debounce queue)
+- **CI / containerised runs** — file events are unreliable across container boundaries; index explicitly instead
+
+## Latency Expectations
+
+| Operation | Typical wall time |
+|---|---|
+| File save → watcher fires | < 5 ms |
+| Debounce window | 50 ms |
+| Incremental parse + delta persist | ~80 ms |
+| `labels_updated` broadcast | < 1 ms after persist |
+| Total: save → queryable | ~80–150 ms |
+
+If you see `persist_ms` consistently above 500 ms, the saved files are larger than expected (e.g., generated bundles) — narrow the watch root or add ignore patterns.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---|---|
+| Calling `watch_directory` on an unindexed repo | Returns an error — run `index_directory` first |
+| Watching `node_modules/` or `target/` | Saturates the watcher with build noise — point at the source root only |
+| Polling `find_symbol` every second to "wait" for indexing | Subscribe to the `labels_updated` WS event, or just call once after the save — the delta is already there |
+| Forgetting to `unwatch_directory` between sessions | Watchers are per-process; restarting `memtrace start` wipes them, but for hosted instances unwatching cleanly avoids leaks |

package/skills/workflows/memtrace-first.md

@@ -9,12 +9,46 @@ description: "Use when working on any indexed codebase before searching files, r
 
 ```
 IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
-NEVER reach for Grep/Glob/Read to discover or understand code.
+Memtrace returns exact file_path + start_line + end_line for every result.
+Read the file at THAT location. Do not Grep/Glob/Find to "locate" anything
+already in the graph.
 ```
 
 Memtrace is the memory layer of the codebase. It has the full knowledge graph: every symbol, call, import, community, process, and API — with time dimension. File tools are blind to this structure.
 
-**97% better accuracy. 83% fewer wasted tokens. No exceptions.**
+**97% better accuracy. 83% fewer wasted tokens. No exceptions for what's in the graph.**
+
+## What Memtrace actually indexes
+
+Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_path, kind) **+ semantic vector search over embedded code bodies** (first ~1500 chars of every Function / Method / Class / Struct / Interface body), fused via Reciprocal Rank Fusion.
+
+The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `find_code`**. The body got embedded; the embedding catches it. You do NOT need `Grep` to hunt for `STRIPE_KEY_FOO_BAR` if it lives inside a function in your indexed codebase.
+
+## The narrow exceptions where grep/glob are still right
+
+These are the ONLY cases where file tools beat memtrace:
+
+- **Files outside the indexed repo.** Vendored deps, system headers, dirs `walker::is_excluded_path` skipped (`.git`, `node_modules`, `target`, `dist`). Memtrace literally cannot see them.
+- **Non-source artifacts.** `.env`, `package.json`, build scripts, top-level `README.md`, raw config files. Memtrace indexes parseable code, not configuration text.
+- **Pure file-inventory questions.** "How many `*.test.ts` files exist", "list every Markdown file in `docs/`". You're asking for a file count, not a symbol search.
+- **Reading at a known path.** Once memtrace has handed you `file_path:start_line:end_line`, use `Read` — never substitute `Grep` for `Read`.
+
+For everything else inside the indexed repo, memtrace is the right tool.
+
+## The decision rule
+
+| Question Claude is asking | Right tool |
+|---|---|
+| "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → file:line. Then `Read` that range. |
+| "What calls `foo`?" | `get_symbol_context(name="foo")` → callers with file:line each. |
+| "How does authentication work?" | `find_code(query="authentication")` → ranked symbols with file:line. |
+| "Find the function that uses `STRIPE_KEY_FOO_BAR`" | `find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
+| "Where's that error message `'connection refused for tenant'`?" | `find_code(query="connection refused for tenant")` → semantic catches it. |
+| "What breaks if I change `foo`?" | `get_impact(name="foo")` → blast radius with file:line. |
+| "What changed in `auth.ts` last week?" | `get_evolution(file_path="auth.ts", from="7d ago")`. |
+| "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
+| "Find this string in my `.env`." | `Grep` (non-source artifact). |
+| "Read file I already have the path of." | `Read` (path is known). |
 
 ## Parameter Types — Read This Before Calling Any Tool