@velvetmonkey/flywheel-memory 2.0.33 → 2.0.34

package/dist/index.js

@@ -2487,7 +2487,10 @@ var DEFAULT_CONFIG = {
   exclude_task_tags: [],
   exclude_analysis_tags: [],
   exclude_entities: [],
-  exclude_entity_folders: []
+  exclude_entity_folders: [],
+  wikilink_strictness: "balanced",
+  implicit_detection: true,
+  adaptive_strictness: true
 };
 function loadConfig(stateDb2) {
   if (stateDb2) {
@@ -4902,6 +4905,24 @@ function setWriteStateDb(stateDb2) {
 function getWriteStateDb() {
   return moduleStateDb4;
 }
+var moduleConfig = null;
+var ALL_IMPLICIT_PATTERNS = ["proper-nouns", "single-caps", "quoted-terms", "camel-case", "acronyms"];
+function setWikilinkConfig(config) {
+  moduleConfig = config;
+}
+function getWikilinkStrictness() {
+  return moduleConfig?.wikilink_strictness ?? "balanced";
+}
+function getEffectiveStrictness(notePath) {
+  const base = getWikilinkStrictness();
+  if (moduleConfig?.adaptive_strictness === false) return base;
+  const context = notePath ? getNoteContext(notePath) : "general";
+  if (context === "daily") return "aggressive";
+  return base;
+}
+function getCooccurrenceIndex() {
+  return cooccurrenceIndex;
+}
 var entityIndex = null;
 var indexReady = false;
 var indexError2 = null;
@@ -5062,9 +5083,11 @@ function processWikilinks(content, notePath) {
     firstOccurrenceOnly: true,
     caseInsensitive: true
   });
+  const implicitEnabled = moduleConfig?.implicit_detection !== false;
+  const implicitPatterns = moduleConfig?.implicit_patterns?.length ? moduleConfig.implicit_patterns : [...ALL_IMPLICIT_PATTERNS];
   const implicitMatches = detectImplicitEntities(result.content, {
-    detectImplicit: true,
-    implicitPatterns: ["proper-nouns", "single-caps", "quoted-terms", "camel-case", "acronyms"],
+    detectImplicit: implicitEnabled,
+    implicitPatterns,
     minEntityLength: 3
   });
   const alreadyLinked = new Set(
@@ -5294,7 +5317,6 @@ var STRICTNESS_CONFIGS = {
     // Standard bonus for exact matches
   }
 };
-var DEFAULT_STRICTNESS = "conservative";
 var TYPE_BOOST = {
   people: 5,
   // Names are high value for connections
@@ -5481,7 +5503,7 @@ async function suggestRelatedLinks(content, options = {}) {
   const {
     maxSuggestions = 3,
     excludeLinked = true,
-    strictness = DEFAULT_STRICTNESS,
+    strictness = getEffectiveStrictness(options.notePath),
     notePath,
     detail = false
   } = options;
@@ -6046,6 +6068,17 @@ function searchFTS5(_vaultPath, query, limit = 10) {
 function getFTS5State() {
   return { ...state };
 }
+function countFTS5Mentions(term) {
+  if (!db2) return 0;
+  try {
+    const result = db2.prepare(
+      "SELECT COUNT(*) as cnt FROM notes_fts WHERE content MATCH ?"
+    ).get(`"${term}"`);
+    return result?.cnt ?? 0;
+  } catch {
+    return 0;
+  }
+}
 
 // src/core/read/taskCache.ts
 import * as path10 from "path";
@@ -7057,12 +7090,13 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
       inputSchema: {
         path: z2.string().optional().describe("Path to a specific note to validate. If omitted, validates all notes."),
         typos_only: z2.boolean().default(false).describe("If true, only report broken links that have a similar existing note (likely typos)"),
+        group_by_target: z2.boolean().default(false).describe("If true, aggregate dead links by target and rank by mention frequency. Returns targets[] instead of broken[]."),
         limit: z2.coerce.number().default(50).describe("Maximum number of broken links to return"),
         offset: z2.coerce.number().default(0).describe("Number of broken links to skip (for pagination)")
       },
       outputSchema: ValidateLinksOutputSchema
     },
-    async ({ path: notePath, typos_only, limit: requestedLimit, offset }) => {
+    async ({ path: notePath, typos_only, group_by_target, limit: requestedLimit, offset }) => {
       const limit = Math.min(requestedLimit ?? 50, MAX_LIMIT);
       const index = getIndex();
       const allBroken = [];
@@ -7103,6 +7137,41 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
           }
         }
       }
+      if (group_by_target) {
+        const targetMap = /* @__PURE__ */ new Map();
+        for (const broken2 of allBroken) {
+          const key = broken2.target.toLowerCase();
+          const existing = targetMap.get(key);
+          if (existing) {
+            existing.count++;
+            if (existing.sources.size < 5) existing.sources.add(broken2.source);
+            if (!existing.suggestion && broken2.suggestion) existing.suggestion = broken2.suggestion;
+          } else {
+            targetMap.set(key, {
+              count: 1,
+              sources: /* @__PURE__ */ new Set([broken2.source]),
+              suggestion: broken2.suggestion
+            });
+          }
+        }
+        const targets = Array.from(targetMap.entries()).map(([target, data]) => ({
+          target,
+          mention_count: data.count,
+          sources: Array.from(data.sources),
+          ...data.suggestion ? { suggestion: data.suggestion } : {}
+        })).sort((a, b) => b.mention_count - a.mention_count).slice(offset, offset + limit);
+        const grouped = {
+          scope: notePath || "all",
+          total_dead_targets: targetMap.size,
+          total_broken_links: allBroken.length,
+          returned_count: targets.length,
+          targets
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(grouped, null, 2) }],
+          structuredContent: grouped
+        };
+      }
       const broken = allBroken.slice(offset, offset + limit);
       const output = {
         scope: notePath || "all",
@@ -7123,6 +7192,106 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
       };
     }
   );
+  server2.registerTool(
+    "discover_stub_candidates",
+    {
+      title: "Discover Stub Candidates",
+      description: `Find terms referenced via dead wikilinks across the vault that have no backing note. These are "invisible concepts" \u2014 topics your vault considers important enough to link to but that don't have their own notes yet. Ranked by reference frequency.`,
+      inputSchema: {
+        min_frequency: z2.coerce.number().default(2).describe("Minimum number of references to include (default 2)"),
+        limit: z2.coerce.number().default(20).describe("Maximum candidates to return (default 20)")
+      }
+    },
+    async ({ min_frequency, limit: requestedLimit }) => {
+      const index = getIndex();
+      const limit = Math.min(requestedLimit ?? 20, 100);
+      const minFreq = min_frequency ?? 2;
+      const targetMap = /* @__PURE__ */ new Map();
+      for (const note of index.notes.values()) {
+        for (const link of note.outlinks) {
+          if (!resolveTarget(index, link.target)) {
+            const key = link.target.toLowerCase();
+            const existing = targetMap.get(key);
+            if (existing) {
+              existing.count++;
+              if (existing.sources.size < 3) existing.sources.add(note.path);
+            } else {
+              targetMap.set(key, { count: 1, sources: /* @__PURE__ */ new Set([note.path]) });
+            }
+          }
+        }
+      }
+      const candidates = Array.from(targetMap.entries()).filter(([, data]) => data.count >= minFreq).map(([target, data]) => {
+        const fts5Mentions = countFTS5Mentions(target);
+        return {
+          term: target,
+          wikilink_references: data.count,
+          content_mentions: fts5Mentions,
+          sample_notes: Array.from(data.sources)
+        };
+      }).sort((a, b) => b.wikilink_references - a.wikilink_references).slice(0, limit);
+      const output = {
+        total_dead_targets: targetMap.size,
+        candidates_above_threshold: candidates.length,
+        candidates
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+      };
+    }
+  );
+  server2.registerTool(
+    "discover_cooccurrence_gaps",
+    {
+      title: "Discover Co-occurrence Gaps",
+      description: "Find entity pairs that frequently co-occur across vault notes but where one or both entities lack a backing note. These represent relationship patterns worth making explicit with hub notes or links.",
+      inputSchema: {
+        min_cooccurrence: z2.coerce.number().default(3).describe("Minimum co-occurrence count to include (default 3)"),
+        limit: z2.coerce.number().default(20).describe("Maximum gaps to return (default 20)")
+      }
+    },
+    async ({ min_cooccurrence, limit: requestedLimit }) => {
+      const index = getIndex();
+      const coocIndex = getCooccurrenceIndex();
+      const limit = Math.min(requestedLimit ?? 20, 100);
+      const minCount = min_cooccurrence ?? 3;
+      if (!coocIndex) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: "Co-occurrence index not built yet. Wait for entity index initialization." }) }]
+        };
+      }
+      const gaps = [];
+      const seenPairs = /* @__PURE__ */ new Set();
+      for (const [entityA, associations] of Object.entries(coocIndex.associations)) {
+        for (const [entityB, count] of associations) {
+          if (count < minCount) continue;
+          const pairKey = [entityA, entityB].sort().join("||");
+          if (seenPairs.has(pairKey)) continue;
+          seenPairs.add(pairKey);
+          const aHasNote = resolveTarget(index, entityA) !== null;
+          const bHasNote = resolveTarget(index, entityB) !== null;
+          if (aHasNote && bHasNote) continue;
+          gaps.push({
+            entity_a: entityA,
+            entity_b: entityB,
+            cooccurrence_count: count,
+            a_has_note: aHasNote,
+            b_has_note: bHasNote
+          });
+        }
+      }
+      gaps.sort((a, b) => b.cooccurrence_count - a.cooccurrence_count);
+      const top = gaps.slice(0, limit);
+      const output = {
+        total_gaps: gaps.length,
+        returned_count: top.length,
+        gaps: top
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+      };
+    }
+  );
 }
 
 // src/tools/read/health.ts
@@ -7488,6 +7657,93 @@ function purgeOldIndexEvents(stateDb2, retentionDays = 90) {
   return result.changes;
 }
 
+// src/core/read/sweep.ts
+var DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1e3;
+var MIN_SWEEP_INTERVAL_MS = 30 * 1e3;
+var cachedResults = null;
+var sweepTimer = null;
+var sweepRunning = false;
+function runSweep(index) {
+  const start = Date.now();
+  let deadLinkCount = 0;
+  const deadTargetCounts = /* @__PURE__ */ new Map();
+  for (const note of index.notes.values()) {
+    for (const link of note.outlinks) {
+      if (!resolveTarget(index, link.target)) {
+        deadLinkCount++;
+        const key = link.target.toLowerCase();
+        deadTargetCounts.set(key, (deadTargetCounts.get(key) || 0) + 1);
+      }
+    }
+  }
+  const topDeadTargets = Array.from(deadTargetCounts.entries()).filter(([, count]) => count >= 2).map(([target, wikilink_references]) => ({
+    target,
+    wikilink_references,
+    content_mentions: countFTS5Mentions(target)
+  })).sort((a, b) => b.wikilink_references - a.wikilink_references).slice(0, 10);
+  const linkedCounts = /* @__PURE__ */ new Map();
+  for (const note of index.notes.values()) {
+    for (const link of note.outlinks) {
+      const key = link.target.toLowerCase();
+      linkedCounts.set(key, (linkedCounts.get(key) || 0) + 1);
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const unlinkedEntities = [];
+  for (const [name, entityPath] of index.entities) {
+    if (seen.has(entityPath)) continue;
+    seen.add(entityPath);
+    const totalMentions = countFTS5Mentions(name);
+    if (totalMentions === 0) continue;
+    const pathKey = entityPath.toLowerCase().replace(/\.md$/, "");
+    const linked = Math.max(linkedCounts.get(name) || 0, linkedCounts.get(pathKey) || 0);
+    const unlinked = Math.max(0, totalMentions - linked - 1);
+    if (unlinked <= 0) continue;
+    const note = index.notes.get(entityPath);
+    const displayName = note?.title || name;
+    unlinkedEntities.push({ entity: displayName, path: entityPath, unlinked_mentions: unlinked });
+  }
+  unlinkedEntities.sort((a, b) => b.unlinked_mentions - a.unlinked_mentions);
+  const results = {
+    last_sweep_at: Date.now(),
+    sweep_duration_ms: Date.now() - start,
+    dead_link_count: deadLinkCount,
+    top_dead_targets: topDeadTargets,
+    top_unlinked_entities: unlinkedEntities.slice(0, 10)
+  };
+  cachedResults = results;
+  return results;
+}
+function startSweepTimer(getIndex, intervalMs) {
+  const interval = Math.max(intervalMs ?? DEFAULT_SWEEP_INTERVAL_MS, MIN_SWEEP_INTERVAL_MS);
+  setTimeout(() => {
+    doSweep(getIndex);
+  }, 5e3);
+  sweepTimer = setInterval(() => {
+    doSweep(getIndex);
+  }, interval);
+  if (sweepTimer && typeof sweepTimer === "object" && "unref" in sweepTimer) {
+    sweepTimer.unref();
+  }
+}
+function doSweep(getIndex) {
+  if (sweepRunning) return;
+  sweepRunning = true;
+  try {
+    const index = getIndex();
+    if (index && index.notes && index.notes.size > 0) {
+      runSweep(index);
+    }
+  } catch (err) {
+    console.error("[Flywheel] Sweep error:", err);
+  } finally {
+    sweepRunning = false;
+  }
+}
+function getSweepResults() {
+  return cachedResults;
+}
+
 // src/tools/read/health.ts
 var STALE_THRESHOLD_SECONDS = 300;
 function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () => ({}), getStateDb = () => null) {
@@ -7563,6 +7819,26 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
     embeddings_count: z3.coerce.number().describe("Number of notes with semantic embeddings"),
     tasks_ready: z3.boolean().describe("Whether the task cache is ready to serve queries"),
     tasks_building: z3.boolean().describe("Whether the task cache is currently rebuilding"),
+    dead_link_count: z3.coerce.number().describe("Total number of broken/dead wikilinks across the vault"),
+    top_dead_link_targets: z3.array(z3.object({
+      target: z3.string().describe("The dead link target"),
+      mention_count: z3.coerce.number().describe("How many notes reference this dead target")
+    })).describe("Top 5 most-referenced dead link targets (highest-ROI candidates to create)"),
+    sweep: z3.object({
+      last_sweep_at: z3.number().describe("When the last background sweep completed (ms epoch)"),
+      sweep_duration_ms: z3.number().describe("How long the last sweep took"),
+      dead_link_count: z3.number().describe("Dead links found by sweep"),
+      top_dead_targets: z3.array(z3.object({
+        target: z3.string(),
+        wikilink_references: z3.number(),
+        content_mentions: z3.number()
+      })).describe("Top dead link targets with FTS5 content mention counts"),
+      top_unlinked_entities: z3.array(z3.object({
+        entity: z3.string(),
+        path: z3.string(),
+        unlinked_mentions: z3.number()
+      })).describe("Entities with the most unlinked plain-text mentions")
+    }).optional().describe("Background sweep results (graph hygiene metrics, updated every 5 min)"),
     recommendations: z3.array(z3.string()).describe("Suggested actions if any issues detected")
   };
   server2.registerTool(
@@ -7685,6 +7961,20 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
         }
       }
       const ftsState = getFTS5State();
+      let deadLinkCount = 0;
+      const deadTargetCounts = /* @__PURE__ */ new Map();
+      if (indexBuilt) {
+        for (const note of index.notes.values()) {
+          for (const link of note.outlinks) {
+            if (!resolveTarget(index, link.target)) {
+              deadLinkCount++;
+              const key = link.target.toLowerCase();
+              deadTargetCounts.set(key, (deadTargetCounts.get(key) || 0) + 1);
+            }
+          }
+        }
+      }
+      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);
       const output = {
         status,
         schema_version: SCHEMA_VERSION,
@@ -7712,6 +8002,9 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
         embeddings_count: getEmbeddingsCount(),
         tasks_ready: isTaskCacheReady(),
         tasks_building: isTaskCacheBuilding(),
+        dead_link_count: deadLinkCount,
+        top_dead_link_targets: topDeadLinkTargets,
+        sweep: getSweepResults() ?? void 0,
         recommendations
       };
       return {
@@ -8205,6 +8498,14 @@ function generateAliasCandidates(entityName, existingAliases) {
         candidates.push({ candidate: short, type: "short_form" });
       }
     }
+    const STOPWORDS2 = /* @__PURE__ */ new Set(["the", "and", "for", "with", "from", "into", "that", "this", "are", "was", "has", "its"]);
+    for (const word of words) {
+      if (word.length < 4) continue;
+      if (STOPWORDS2.has(word.toLowerCase())) continue;
+      if (existing.has(word.toLowerCase())) continue;
+      if (words.length >= 3 && word === words[0]) continue;
+      candidates.push({ candidate: word, type: "name_fragment" });
+    }
   }
   return candidates;
 }
@@ -8231,6 +8532,7 @@ function suggestEntityAliases(stateDb2, folder) {
         mentions = result?.cnt ?? 0;
       } catch {
       }
+      if (type === "name_fragment" && mentions < 5) continue;
       suggestions.push({
         entity: row.name,
         entity_path: row.path,
@@ -8761,6 +9063,61 @@ function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfi
       };
     }
   );
+  server2.registerTool(
+    "unlinked_mentions_report",
+    {
+      title: "Unlinked Mentions Report",
+      description: "Find which entities have the most unlinked mentions across the vault \u2014 highest-ROI linking opportunities. Uses FTS5 to count mentions and subtracts known wikilinks.",
+      inputSchema: {
+        limit: z5.coerce.number().default(20).describe("Maximum entities to return (default 20)")
+      }
+    },
+    async ({ limit: requestedLimit }) => {
+      requireIndex();
+      const index = getIndex();
+      const limit = Math.min(requestedLimit ?? 20, 100);
+      const linkedCounts = /* @__PURE__ */ new Map();
+      for (const note of index.notes.values()) {
+        for (const link of note.outlinks) {
+          const key = link.target.toLowerCase();
+          linkedCounts.set(key, (linkedCounts.get(key) || 0) + 1);
+        }
+      }
+      const results = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const [name, entityPath] of index.entities) {
+        if (seen.has(entityPath)) continue;
+        seen.add(entityPath);
+        const totalMentions = countFTS5Mentions(name);
+        if (totalMentions === 0) continue;
+        const pathKey = entityPath.toLowerCase().replace(/\.md$/, "");
+        const linkedByName = linkedCounts.get(name) || 0;
+        const linkedByPath = linkedCounts.get(pathKey) || 0;
+        const linked = Math.max(linkedByName, linkedByPath);
+        const unlinked = Math.max(0, totalMentions - linked - 1);
+        if (unlinked <= 0) continue;
+        const note = index.notes.get(entityPath);
+        const displayName = note?.title || name;
+        results.push({
+          entity: displayName,
+          path: entityPath,
+          total_mentions: totalMentions,
+          linked_mentions: linked,
+          unlinked_mentions: unlinked
+        });
+      }
+      results.sort((a, b) => b.unlinked_mentions - a.unlinked_mentions);
+      const top = results.slice(0, limit);
+      const output = {
+        total_entities_checked: seen.size,
+        entities_with_unlinked: results.length,
+        top_entities: top
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+      };
+    }
+  );
 }
 
 // src/tools/read/primitives.ts
@@ -12119,8 +12476,12 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
             return formatMcpResult(errorResult(notePath, `Template not found: ${template}`));
           }
         }
+        const now = /* @__PURE__ */ new Date();
         if (!effectiveFrontmatter.date) {
-          effectiveFrontmatter.date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+          effectiveFrontmatter.date = now.toISOString().split("T")[0];
+        }
+        if (!effectiveFrontmatter.created) {
+          effectiveFrontmatter.created = now.toISOString();
         }
         const warnings = [];
         const noteName = path21.basename(notePath, ".md");
@@ -15931,6 +16292,7 @@ registerSystemTools(
   () => vaultPath,
   (newConfig) => {
     flywheelConfig = newConfig;
+    setWikilinkConfig(newConfig);
   },
   () => stateDb
 );
@@ -15957,6 +16319,7 @@ registerConfigTools(
   () => flywheelConfig,
   (newConfig) => {
     flywheelConfig = newConfig;
+    setWikilinkConfig(newConfig);
   },
   () => stateDb
 );
@@ -16139,6 +16502,7 @@ async function runPostIndexWork(index) {
     saveConfig(stateDb, inferred, existing);
   }
   flywheelConfig = loadConfig(stateDb);
+  setWikilinkConfig(flywheelConfig);
   const configKeys = Object.keys(flywheelConfig).filter((k) => flywheelConfig[k] != null);
   serverLog("config", `Config inferred: ${configKeys.join(", ")}`);
   if (stateDb) {
@@ -16376,6 +16740,8 @@ async function runPostIndexWork(index) {
     watcher.start();
     serverLog("watcher", "File watcher started");
   }
+  startSweepTimer(() => vaultIndex);
+  serverLog("server", "Sweep timer started (5 min interval)");
   const postDuration = Date.now() - postStart;
   serverLog("server", `Post-index work complete in ${postDuration}ms`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-memory",
-  "version": "2.0.33",
+  "version": "2.0.34",
   "description": "MCP server that gives Claude full read/write access to your Obsidian vault. 42 tools for search, backlinks, graph queries, mutations, and hybrid semantic search.",
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@velvetmonkey/vault-core": "^2.0.33",
+    "@velvetmonkey/vault-core": "^2.0.34",
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.0",
     "gray-matter": "^4.0.3",