@velvetmonkey/flywheel-memory 2.0.120 → 2.0.122

package/dist/index.js

@@ -7571,19 +7571,68 @@ function createVaultWatcher(options) {
 }
 
 // src/core/shared/hubExport.ts
+var EIGEN_ITERATIONS = 50;
 function computeHubScores(index) {
-  const hubScores = /* @__PURE__ */ new Map();
+  const nodes = [];
+  const nodeIdx = /* @__PURE__ */ new Map();
+  const adj = [];
   for (const note of index.notes.values()) {
-    const backlinks = getBacklinksForNote(index, note.path);
-    const backlinkCount = backlinks.length;
-    const normalizedPath = normalizeTarget(note.path);
-    hubScores.set(normalizedPath, backlinkCount);
-    const title = note.title.toLowerCase();
-    if (!hubScores.has(title) || backlinkCount > hubScores.get(title)) {
-      hubScores.set(title, backlinkCount);
+    const key = normalizeTarget(note.path);
+    if (!nodeIdx.has(key)) {
+      nodeIdx.set(key, nodes.length);
+      nodes.push(key);
+      adj.push([]);
+    }
+    const titleKey = note.title.toLowerCase();
+    if (!nodeIdx.has(titleKey)) {
+      nodeIdx.set(titleKey, nodeIdx.get(key));
     }
   }
-  return hubScores;
+  const N = nodes.length;
+  if (N === 0) return /* @__PURE__ */ new Map();
+  for (const note of index.notes.values()) {
+    const fromIdx = nodeIdx.get(normalizeTarget(note.path));
+    if (fromIdx === void 0) continue;
+    for (const link of note.outlinks) {
+      const target = normalizeTarget(link.target);
+      let toIdx = nodeIdx.get(target);
+      if (toIdx === void 0) {
+        toIdx = nodeIdx.get(link.target.toLowerCase());
+      }
+      if (toIdx !== void 0 && toIdx !== fromIdx) {
+        adj[fromIdx].push(toIdx);
+        adj[toIdx].push(fromIdx);
+      }
+    }
+  }
+  let scores = new Float64Array(N).fill(1 / N);
+  for (let iter = 0; iter < EIGEN_ITERATIONS; iter++) {
+    const next = new Float64Array(N);
+    for (let i = 0; i < N; i++) {
+      for (const j of adj[i]) {
+        next[i] += scores[j];
+      }
+    }
+    let norm = 0;
+    for (let i = 0; i < N; i++) norm += next[i] * next[i];
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+      for (let i = 0; i < N; i++) next[i] /= norm;
+    }
+    scores = next;
+  }
+  let maxScore = 0;
+  for (let i = 0; i < N; i++) {
+    if (scores[i] > maxScore) maxScore = scores[i];
+  }
+  const result = /* @__PURE__ */ new Map();
+  for (let i = 0; i < N; i++) {
+    const scaled = maxScore > 0 ? Math.round(scores[i] / maxScore * 100) : 0;
+    if (scaled > 0) {
+      result.set(nodes[i], scaled);
+    }
+  }
+  return result;
 }
 function updateHubScoresInDb(stateDb2, hubScores) {
   const updateStmt = stateDb2.db.prepare(`
@@ -8510,6 +8559,162 @@ function getConnectionStrength(index, noteAPath, noteBPath) {
   }
   return { score, factors };
 }
+function computeCentralityMetrics(index, limit = 20) {
+  const paths = Array.from(index.notes.keys());
+  const N = paths.length;
+  if (N === 0) return [];
+  const pathIdx = /* @__PURE__ */ new Map();
+  paths.forEach((p, i) => pathIdx.set(p, i));
+  for (const note of index.notes.values()) {
+    const normalized = note.title.toLowerCase();
+    if (!pathIdx.has(normalized)) {
+      pathIdx.set(normalized, pathIdx.get(note.path));
+    }
+  }
+  const outAdj = Array.from({ length: N }, () => []);
+  const inAdj = Array.from({ length: N }, () => []);
+  for (const note of index.notes.values()) {
+    const fromIdx = pathIdx.get(note.path);
+    if (fromIdx === void 0) continue;
+    for (const link of note.outlinks) {
+      let toIdx = pathIdx.get(link.target);
+      if (toIdx === void 0) toIdx = pathIdx.get(link.target.toLowerCase());
+      if (toIdx !== void 0 && toIdx !== fromIdx) {
+        outAdj[fromIdx].push(toIdx);
+        inAdj[toIdx].push(fromIdx);
+      }
+    }
+  }
+  const degree = new Float64Array(N);
+  for (let i = 0; i < N; i++) {
+    degree[i] = outAdj[i].length + inAdj[i].length;
+  }
+  const betweenness = new Float64Array(N);
+  const closenessSum = new Float64Array(N);
+  const reachable = new Int32Array(N);
+  const undirAdj = Array.from({ length: N }, () => []);
+  for (let i = 0; i < N; i++) {
+    for (const j of outAdj[i]) {
+      undirAdj[i].push(j);
+      undirAdj[j].push(i);
+    }
+  }
+  for (let s = 0; s < N; s++) {
+    const stack = [];
+    const pred = Array.from({ length: N }, () => []);
+    const sigma = new Float64Array(N);
+    const dist = new Int32Array(N).fill(-1);
+    sigma[s] = 1;
+    dist[s] = 0;
+    const queue = [s];
+    let head = 0;
+    while (head < queue.length) {
+      const v = queue[head++];
+      stack.push(v);
+      for (const w of undirAdj[v]) {
+        if (dist[w] < 0) {
+          dist[w] = dist[v] + 1;
+          queue.push(w);
+        }
+        if (dist[w] === dist[v] + 1) {
+          sigma[w] += sigma[v];
+          pred[w].push(v);
+        }
+      }
+    }
+    for (let t = 0; t < N; t++) {
+      if (dist[t] > 0) {
+        closenessSum[s] += dist[t];
+        reachable[s]++;
+      }
+    }
+    const delta = new Float64Array(N);
+    while (stack.length > 0) {
+      const w = stack.pop();
+      for (const v of pred[w]) {
+        delta[v] += sigma[v] / sigma[w] * (1 + delta[w]);
+      }
+      if (w !== s) {
+        betweenness[w] += delta[w];
+      }
+    }
+  }
+  const normFactor = N > 2 ? (N - 1) * (N - 2) : 1;
+  const results = [];
+  for (let i = 0; i < N; i++) {
+    const note = index.notes.get(paths[i]);
+    results.push({
+      path: paths[i],
+      title: note?.title || paths[i],
+      degree: degree[i],
+      betweenness: Math.round(betweenness[i] / normFactor * 1e4) / 1e4,
+      closeness: reachable[i] > 0 ? Math.round(reachable[i] / closenessSum[i] * 1e4) / 1e4 : 0
+    });
+  }
+  results.sort((a, b) => b.betweenness - a.betweenness);
+  return results.slice(0, limit);
+}
+function detectCycles(index, maxLength = 10, limit = 20) {
+  const paths = Array.from(index.notes.keys());
+  const N = paths.length;
+  if (N === 0) return [];
+  const pathIdx = /* @__PURE__ */ new Map();
+  paths.forEach((p, i) => pathIdx.set(p, i));
+  for (const note of index.notes.values()) {
+    const normalized = note.title.toLowerCase();
+    if (!pathIdx.has(normalized)) {
+      pathIdx.set(normalized, pathIdx.get(note.path));
+    }
+  }
+  const adj = Array.from({ length: N }, () => []);
+  for (const note of index.notes.values()) {
+    const fromIdx = pathIdx.get(note.path);
+    if (fromIdx === void 0) continue;
+    for (const link of note.outlinks) {
+      let toIdx = pathIdx.get(link.target);
+      if (toIdx === void 0) toIdx = pathIdx.get(link.target.toLowerCase());
+      if (toIdx !== void 0 && toIdx !== fromIdx) {
+        adj[fromIdx].push(toIdx);
+      }
+    }
+  }
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Uint8Array(N);
+  const cycles = [];
+  const stack = [];
+  function dfs(u) {
+    if (cycles.length >= limit) return;
+    color[u] = GRAY;
+    stack.push(u);
+    for (const v of adj[u]) {
+      if (cycles.length >= limit) return;
+      if (color[v] === GRAY) {
+        const cycleStart = stack.indexOf(v);
+        if (cycleStart >= 0) {
+          const cyclePath = stack.slice(cycleStart);
+          if (cyclePath.length <= maxLength) {
+            const note = (idx) => index.notes.get(paths[idx])?.title || paths[idx];
+            cycles.push({
+              cycle: cyclePath.map(note),
+              length: cyclePath.length
+            });
+          }
+        }
+      } else if (color[v] === WHITE) {
+        dfs(v);
+      }
+    }
+    stack.pop();
+    color[u] = BLACK;
+  }
+  for (let i = 0; i < N; i++) {
+    if (color[i] === WHITE && cycles.length < limit) {
+      dfs(i);
+    }
+  }
+  cycles.sort((a, b) => a.length - b.length);
+  return cycles;
+}
 
 // src/core/read/indexGuard.ts
 function requireIndex() {
@@ -9802,6 +10007,7 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig2 = () =>
   });
   const HealthCheckOutputSchema = {
     status: z3.enum(["healthy", "degraded", "unhealthy"]).describe("Overall health status"),
+    vault_health_score: z3.coerce.number().describe("Composite vault health score (0-100)"),
     schema_version: z3.coerce.number().describe("StateDb schema version"),
     vault_accessible: z3.boolean().describe("Whether the vault path is accessible"),
     vault_path: z3.string().describe("The vault path being used"),
@@ -9908,17 +10114,18 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig2 = () =>
         vaultAccessible = false;
         recommendations.push("Vault path is not accessible. Check PROJECT_PATH environment variable.");
       }
+      let dbIntegrityFailed = false;
       const stateDb2 = getStateDb2();
       if (stateDb2) {
         try {
           const result = stateDb2.db.pragma("quick_check");
           const ok = result.length === 1 && Object.values(result[0])[0] === "ok";
           if (!ok) {
-            overall = "unhealthy";
+            dbIntegrityFailed = true;
             recommendations.push(`Database integrity check failed: ${Object.values(result[0])[0] ?? "unknown error"}`);
           }
         } catch (err) {
-          overall = "unhealthy";
+          dbIntegrityFailed = true;
           recommendations.push(`Database integrity check error: ${err instanceof Error ? err.message : err}`);
         }
       }
@@ -9945,7 +10152,7 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig2 = () =>
         recommendations.push("No notes found in vault. Is PROJECT_PATH pointing to a markdown vault?");
       }
       let status;
-      if (!vaultAccessible || indexState2 === "error") {
+      if (!vaultAccessible || indexState2 === "error" || dbIntegrityFailed) {
         status = "unhealthy";
       } else if (indexState2 === "building" || indexStale || recommendations.length > 0) {
         status = "degraded";
@@ -10032,8 +10239,37 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig2 = () =>
         }
       }
       const topDeadLinkTargets = Array.from(deadTargetCounts.entries()).map(([target, mention_count]) => ({ target, mention_count })).sort((a, b) => b.mention_count - a.mention_count).slice(0, 5);
+      let vault_health_score = 0;
+      if (indexBuilt && noteCount > 0) {
+        const avgOutlinks = linkCount / noteCount;
+        const linkDensity = Math.min(1, avgOutlinks / 3);
+        let orphanCount = 0;
+        for (const note of index.notes.values()) {
+          const bl = index.backlinks.get(note.title.toLowerCase());
+          if (!bl || bl.length === 0) orphanCount++;
+        }
+        const orphanRatio = 1 - orphanCount / noteCount;
+        const totalLinks = linkCount > 0 ? linkCount : 1;
+        const deadLinkRatio = 1 - deadLinkCount / totalLinks;
+        let notesWithFm = 0;
+        for (const note of index.notes.values()) {
+          if (Object.keys(note.frontmatter).length > 0) notesWithFm++;
+        }
+        const fmCoverage = notesWithFm / noteCount;
+        const freshCutoff = Date.now() - 90 * 24 * 60 * 60 * 1e3;
+        let freshCount = 0;
+        for (const note of index.notes.values()) {
+          if (note.modified && note.modified.getTime() > freshCutoff) freshCount++;
+        }
+        const freshness = freshCount / noteCount;
+        const entityCoverage = Math.min(1, entityCount / (noteCount * 0.5));
+        vault_health_score = Math.round(
+          linkDensity * 25 + orphanRatio * 20 + deadLinkRatio * 15 + fmCoverage * 15 + freshness * 15 + entityCoverage * 10
+        );
+      }
       const output = {
         status,
+        vault_health_score,
         schema_version: SCHEMA_VERSION,
         vault_accessible: vaultAccessible,
         vault_path: vaultPath2,
@@ -12898,9 +13134,9 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb2
     "graph_analysis",
     {
       title: "Graph Analysis",
-      description: 'Analyze vault link graph structure. Use analysis to pick the mode:\n- "orphans": Notes with no backlinks (params: folder, limit, offset)\n- "dead_ends": Notes with backlinks but no outgoing links (params: folder, min_backlinks, limit, offset)\n- "sources": Notes with outgoing links but no backlinks (params: folder, min_outlinks, limit, offset)\n- "hubs": Highly connected notes (params: min_links, limit, offset)\n- "stale": Important notes not recently modified (params: days [required], min_backlinks, limit, offset)\n- "immature": Notes scored by maturity (params: folder, limit, offset)\n- "emerging_hubs": Entities growing fastest in connection count (params: days, limit, offset)',
+      description: 'Analyze vault link graph structure. Use analysis to pick the mode:\n- "orphans": Notes with no backlinks (params: folder, limit, offset)\n- "dead_ends": Notes with backlinks but no outgoing links (params: folder, min_backlinks, limit, offset)\n- "sources": Notes with outgoing links but no backlinks (params: folder, min_outlinks, limit, offset)\n- "hubs": Highly connected notes (params: min_links, limit, offset)\n- "stale": Important notes not recently modified (params: days [required], min_backlinks, limit, offset)\n- "immature": Notes scored by maturity (params: folder, limit, offset)\n- "emerging_hubs": Entities growing fastest in connection count (params: days, limit, offset)\n- "centrality": Degree, betweenness, and closeness centrality metrics (params: limit, offset)\n- "cycles": Detect circular link chains in the vault (params: limit)',
       inputSchema: {
-        analysis: z8.enum(["orphans", "dead_ends", "sources", "hubs", "stale", "immature", "emerging_hubs"]).describe("Type of graph analysis to perform"),
+        analysis: z8.enum(["orphans", "dead_ends", "sources", "hubs", "stale", "immature", "emerging_hubs", "centrality", "cycles"]).describe("Type of graph analysis to perform"),
         folder: z8.string().optional().describe("Limit to notes in this folder (orphans, dead_ends, sources, immature)"),
         min_links: z8.coerce.number().default(5).describe("Minimum total connections for hubs"),
         min_backlinks: z8.coerce.number().default(1).describe("Minimum backlinks (dead_ends, stale)"),
@@ -13099,6 +13335,28 @@ function registerGraphAnalysisTools(server2, getIndex, getVaultPath, getStateDb2
             }, null, 2) }]
           };
         }
+        case "centrality": {
+          const results = computeCentralityMetrics(index, limit);
+          const paginated = results.slice(offset, offset + limit);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "centrality",
+              total_count: results.length,
+              returned_count: paginated.length,
+              notes: paginated
+            }, null, 2) }]
+          };
+        }
+        case "cycles": {
+          const cycles = detectCycles(index, 10, limit);
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              analysis: "cycles",
+              total_count: cycles.length,
+              cycles
+            }, null, 2) }]
+          };
+        }
       }
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-memory",
-  "version": "2.0.120",
+  "version": "2.0.122",
   "description": "MCP server that gives Claude full read/write access to your Obsidian vault. Select from 69 tools for search, backlinks, graph queries, mutations, agent memory, and hybrid semantic search.",
   "type": "module",
   "main": "dist/index.js",
@@ -49,11 +49,11 @@
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist",
     "postinstall": "node -e \"['bin/flywheel-memory.js','dist/index.js'].forEach(f=>{try{require('fs').chmodSync(f,0o755)}catch{}})\"",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run lint && npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@velvetmonkey/vault-core": "^2.0.120",
+    "@velvetmonkey/vault-core": "^2.0.122",
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.0",
     "gray-matter": "^4.0.3",