@velvetmonkey/flywheel-memory 2.0.143 → 2.0.144

package/dist/index.js

@@ -1883,12 +1883,12 @@ function computePosteriorMean(weightedCorrect, weightedFp) {
   const beta_ = PRIOR_BETA + weightedFp;
   return alpha / (alpha + beta_);
 }
-function recordFeedback(stateDb2, entity, context, notePath, correct, confidence = 1) {
+function recordFeedback(stateDb2, entity, context, notePath, correct, confidence = 1, matchedTerm) {
   try {
-    console.error(`[Flywheel] recordFeedback: entity="${entity}" context="${context}" notePath="${notePath}" correct=${correct}`);
+    console.error(`[Flywheel] recordFeedback: entity="${entity}" term="${matchedTerm ?? entity}" context="${context}" notePath="${notePath}" correct=${correct}`);
     const result = stateDb2.db.prepare(
-      "INSERT INTO wikilink_feedback (entity, context, note_path, correct, confidence) VALUES (?, ?, ?, ?, ?)"
-    ).run(entity, context, notePath, correct ? 1 : 0, confidence);
+      "INSERT INTO wikilink_feedback (entity, context, note_path, correct, confidence, matched_term) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(entity, context, notePath, correct ? 1 : 0, confidence, matchedTerm ?? null);
     console.error(`[Flywheel] recordFeedback: inserted id=${result.lastInsertRowid}`);
   } catch (e) {
     console.error(`[Flywheel] recordFeedback failed for entity="${entity}": ${e}`);
@@ -2173,9 +2173,10 @@ function getAllSuppressionPenalties(stateDb2, now) {
 }
 function trackWikilinkApplications(stateDb2, notePath, entities) {
   const upsert = stateDb2.db.prepare(`
-    INSERT INTO wikilink_applications (entity, note_path, applied_at, status)
-    VALUES (?, ?, datetime('now'), 'applied')
+    INSERT INTO wikilink_applications (entity, note_path, matched_term, applied_at, status)
+    VALUES (?, ?, ?, datetime('now'), 'applied')
     ON CONFLICT(entity, note_path) DO UPDATE SET
+      matched_term = COALESCE(?, matched_term),
       applied_at = datetime('now'),
       status = 'applied'
   `);
@@ -2183,10 +2184,12 @@ function trackWikilinkApplications(stateDb2, notePath, entities) {
     `SELECT name FROM entities WHERE LOWER(name) = LOWER(?) LIMIT 1`
   );
   const transaction = stateDb2.db.transaction(() => {
-    for (const entity of entities) {
-      const row = lookupCanonical.get(entity);
-      const canonicalName = row?.name ?? entity;
-      upsert.run(canonicalName, notePath);
+    for (const item of entities) {
+      const entityName = typeof item === "string" ? item : item.entity;
+      const matchedTerm = typeof item === "string" ? null : item.matchedTerm ?? null;
+      const row = lookupCanonical.get(entityName);
+      const canonicalName = row?.name ?? entityName;
+      upsert.run(canonicalName, notePath, matchedTerm, matchedTerm);
     }
   });
   transaction();
@@ -2199,7 +2202,7 @@ function getTrackedApplications(stateDb2, notePath) {
 }
 function getTrackedApplicationsWithTime(stateDb2, notePath) {
   return stateDb2.db.prepare(
-    `SELECT entity, applied_at FROM wikilink_applications WHERE note_path = ? AND status = 'applied'`
+    `SELECT entity, applied_at, matched_term FROM wikilink_applications WHERE note_path = ? AND status = 'applied'`
   ).all(notePath);
 }
 function computeImplicitRemovalConfidence(appliedAt) {
@@ -2270,10 +2273,10 @@ function processImplicitFeedback(stateDb2, notePath, currentContent) {
     `UPDATE wikilink_applications SET status = 'removed' WHERE entity = ? AND note_path = ?`
   );
   const transaction = stateDb2.db.transaction(() => {
-    for (const { entity, applied_at } of trackedWithTime) {
+    for (const { entity, applied_at, matched_term } of trackedWithTime) {
       if (!currentLinks.has(entity.toLowerCase())) {
         const confidence = computeImplicitRemovalConfidence(applied_at);
-        recordFeedback(stateDb2, entity, "implicit:removed", notePath, false, confidence);
+        recordFeedback(stateDb2, entity, "implicit:removed", notePath, false, confidence, matched_term ?? void 0);
         markRemoved.run(entity, notePath);
         removed.push(entity);
       }
@@ -2288,12 +2291,12 @@ function processImplicitFeedback(stateDb2, notePath, currentContent) {
     `SELECT MAX(created_at) as last FROM wikilink_feedback
      WHERE entity = ? COLLATE NOCASE AND context = 'implicit:survived' AND note_path = ?`
   );
-  for (const { entity } of trackedWithTime) {
+  for (const { entity, matched_term } of trackedWithTime) {
     if (currentLinks.has(entity.toLowerCase())) {
       const lastSurvival = getLastSurvival.get(entity, notePath);
       const lastAt = lastSurvival?.last ? new Date(lastSurvival.last).getTime() : 0;
       if (Date.now() - lastAt > SURVIVAL_COOLDOWN_MS) {
-        recordFeedback(stateDb2, entity, "implicit:survived", notePath, true, 0.8);
+        recordFeedback(stateDb2, entity, "implicit:survived", notePath, true, 0.8, matched_term ?? void 0);
       }
     }
   }
@@ -3688,17 +3691,25 @@ function isLikelyArticleTitle(name) {
 }
 function getCrossFolderBoost(entityPath, notePath) {
   if (!entityPath || !notePath) return 0;
-  const entityFolder = entityPath.split("/")[0];
-  const noteFolder = notePath.split("/")[0];
-  if (entityFolder && noteFolder && entityFolder !== noteFolder) {
-    return CROSS_FOLDER_BOOST;
+  const entityParts = entityPath.split("/");
+  const noteParts = notePath.split("/");
+  const entityFolder = entityParts[0];
+  const noteFolder = noteParts[0];
+  if (!entityFolder || !noteFolder) return 0;
+  if (entityFolder === noteFolder) {
+    if (entityParts[1] && noteParts[1] && entityParts[1] === noteParts[1]) {
+      return 3;
+    }
+    return 2;
   }
-  return 0;
+  if (GENERIC_FOLDERS.has(entityFolder)) return 0;
+  if (GENERIC_FOLDERS.has(noteFolder)) return -1;
+  return -3;
 }
 function getHubBoost(entity) {
   const hubScore = entity.hubScore ?? 0;
   if (hubScore <= 0) return 0;
-  return Math.min(Math.round(Math.log2(hubScore) * 10) / 10, 6);
+  return Math.min(Math.round(Math.log2(hubScore) * 6) / 10, 4);
 }
 function getNoteContext(notePath) {
   const lower = notePath.toLowerCase();
@@ -3955,7 +3966,7 @@ async function suggestRelatedLinks(content, options = {}) {
           const recencyBoostVal = hasContentOverlap && !disabled.has("recency") ? recencyIndex ? getRecencyBoost(entityName, recencyIndex) : 0 : 0;
           const rawCrossFolderBoost = disabled.has("cross_folder") ? 0 : notePath && entity.path ? getCrossFolderBoost(entity.path, notePath) : 0;
           const rawHubBoost = disabled.has("hub_boost") ? 0 : getHubBoost(entity);
-          const hubBoost = hasContentOverlap ? rawHubBoost : Math.min(rawHubBoost, 4);
+          const hubBoost = hasContentOverlap ? rawHubBoost : Math.min(rawHubBoost, 2);
           const crossFolderBoost = hasContentOverlap ? rawCrossFolderBoost : Math.min(rawCrossFolderBoost, 2);
           const feedbackAdj = disabled.has("feedback") ? 0 : feedbackBoosts.get(entityName) ?? 0;
           const edgeWeightBoost = disabled.has("edge_weight") ? 0 : getEdgeWeightBoostScore(entityName, edgeWeightMap);
@@ -4112,11 +4123,37 @@ async function suggestRelatedLinks(content, options = {}) {
     return emptyResult;
   }
   const MAX_SUFFIX_ENTRIES = 3;
+  const MAX_SUFFIX_PER_CATEGORY = 2;
+  const MAX_SUFFIX_PER_FOLDER = 2;
+  const MAX_SUFFIX_APPEARANCES = 5;
   const MIN_SUFFIX_SCORE = noteContext === "daily" ? 8 : 12;
   const MIN_SUFFIX_CONTENT = noteContext === "daily" ? 2 : 3;
-  const suffixEntries = topEntries.filter(
-    (e) => e.score >= MIN_SUFFIX_SCORE && (e.breakdown.contentMatch >= MIN_SUFFIX_CONTENT || e.breakdown.cooccurrenceBoost >= MIN_SUFFIX_CONTENT || (e.breakdown.semanticBoost ?? 0) >= MIN_SUFFIX_CONTENT)
-  ).slice(0, MAX_SUFFIX_ENTRIES);
+  const suffixCandidates = topEntries.filter((e) => {
+    if (e.score < MIN_SUFFIX_SCORE) return false;
+    if (!(e.breakdown.contentMatch >= MIN_SUFFIX_CONTENT || e.breakdown.cooccurrenceBoost >= MIN_SUFFIX_CONTENT || (e.breakdown.semanticBoost ?? 0) >= MIN_SUFFIX_CONTENT)) return false;
+    if (!disabled.has("fatigue")) {
+      const escapedName = e.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const suffixPattern = new RegExp(`\u2192 .*\\[\\[${escapedName}\\]\\]`, "g");
+      const appearances = (content.match(suffixPattern) || []).length;
+      if (appearances >= MAX_SUFFIX_APPEARANCES) return false;
+    }
+    return true;
+  });
+  const suffixEntries = [];
+  const categoryCount = /* @__PURE__ */ new Map();
+  const folderCount = /* @__PURE__ */ new Map();
+  for (const c of suffixCandidates) {
+    const cat = c.category ?? "other";
+    const folder = c.path?.split("/")[0] ?? "";
+    const catN = categoryCount.get(cat) ?? 0;
+    const folderN = folderCount.get(folder) ?? 0;
+    if (catN >= MAX_SUFFIX_PER_CATEGORY) continue;
+    if (folderN >= MAX_SUFFIX_PER_FOLDER) continue;
+    suffixEntries.push(c);
+    categoryCount.set(cat, catN + 1);
+    folderCount.set(folder, folderN + 1);
+    if (suffixEntries.length >= MAX_SUFFIX_ENTRIES) break;
+  }
   const suffix = suffixEntries.length > 0 ? "\u2192 " + suffixEntries.map((e) => `[[${e.name}]]`).join(", ") : "";
   const result = {
     suggestions: topSuggestions,
@@ -4357,7 +4394,7 @@ async function applyProactiveSuggestions(filePath, vaultPath2, suggestions, conf
     skipped: candidates.map((c) => c.entity).filter((e) => !result.linkedEntities.includes(e))
   };
 }
-var moduleStateDb4, moduleConfig, ALL_IMPLICIT_PATTERNS, entityIndex, indexReady, indexError2, lastLoadedAt, cooccurrenceIndex, recencyIndex, DEFAULT_EXCLUDE_FOLDERS, SUGGESTION_PATTERN, GENERIC_WORDS, MAX_ENTITY_LENGTH, MAX_ENTITY_WORDS, ARTICLE_PATTERNS, STRICTNESS_CONFIGS, TYPE_BOOST, CROSS_FOLDER_BOOST, SEMANTIC_MIN_SIMILARITY, SEMANTIC_MAX_BOOST, CONTEXT_BOOST, MIN_SUGGESTION_SCORE, MIN_MATCH_RATIO, FULL_ALIAS_MATCH_BONUS;
+var moduleStateDb4, moduleConfig, ALL_IMPLICIT_PATTERNS, entityIndex, indexReady, indexError2, lastLoadedAt, cooccurrenceIndex, recencyIndex, DEFAULT_EXCLUDE_FOLDERS, SUGGESTION_PATTERN, GENERIC_WORDS, MAX_ENTITY_LENGTH, MAX_ENTITY_WORDS, ARTICLE_PATTERNS, STRICTNESS_CONFIGS, TYPE_BOOST, GENERIC_FOLDERS, SEMANTIC_MIN_SIMILARITY, SEMANTIC_MAX_BOOST, CONTEXT_BOOST, MIN_SUGGESTION_SCORE, MIN_MATCH_RATIO, FULL_ALIAS_MATCH_BONUS;
 var init_wikilinks = __esm({
   "src/core/write/wikilinks.ts"() {
     "use strict";
@@ -4547,7 +4584,7 @@ var init_wikilinks = __esm({
       other: 0
       // Unknown category
     };
-    CROSS_FOLDER_BOOST = 3;
+    GENERIC_FOLDERS = /* @__PURE__ */ new Set(["daily-notes", "weekly-notes", "clippings", "templates", "new"]);
     SEMANTIC_MIN_SIMILARITY = 0.3;
     SEMANTIC_MAX_BOOST = 12;
     CONTEXT_BOOST = {
@@ -10868,9 +10905,9 @@ This server manages multiple vaults. Every tool has an optional "vault" paramete
   }
   parts.push(`
 **Frontmatter matters more than content** for Flywheel's intelligence. When creating or updating notes, always set:
-  - \`type:\` \u2014 drives entity categorization (person, project, technology). Without it, the category is guessed from the name alone.
-  - \`aliases:\` \u2014 alternative names so the entity is found when referred to differently.
-  - \`description:\` \u2014 one-line summary shown in search results and used by recall.
+  - \`type:\` \u2014 drives entity categorization (person, project, technology). Without it, the category is guessed from the name alone and is often wrong.
+  - \`aliases:\` \u2014 alternative names so the entity is found when referred to differently. Without it, the entity is invisible to searches using alternate names.
+  - \`description:\` \u2014 one-line summary shown in search results and used by recall. Without it, search results and recall are degraded.
   - Tags \u2014 used for filtering, suggestion scoring, and schema analysis.
 Good frontmatter is the highest-leverage action for improving suggestions, recall, and link quality.`);
   if (categories.has("read")) {
@@ -10889,6 +10926,10 @@ Escalation: "search" (enriched metadata + content preview) \u2192 "get_note_stru
 created with the correct structure and frontmatter for this vault. Use a matching policy instead of
 raw write tools when one exists. Fall back to direct tools only when no policy fits.
 
+**Every new note should have \`type\`, \`aliases\`, and \`description\` in frontmatter** \u2014 this is what powers
+entity categorization, search ranking, and link suggestions. Notes without frontmatter are nearly invisible
+to the intelligence layer.
+
 Write to existing notes with "vault_add_to_section". Create new notes with "vault_create_note".
 Update metadata with "vault_update_frontmatter". These are fallback tools \u2014 use them when no policy fits.
 All writes auto-link entities \u2014 no manual [[wikilinks]] needed.
@@ -18363,7 +18404,7 @@ import { z as z15 } from "zod";
 function registerFrontmatterTools(server2, getVaultPath) {
   server2.tool(
     "vault_update_frontmatter",
-    `Update frontmatter fields in a note (merge with existing). Set only_if_missing=true to only add fields that don't already exist (absorbed vault_add_frontmatter_field).
+    `Update frontmatter fields in a note (merge with existing). Use this to backfill type, aliases, and description on notes missing them \u2014 these fields are critical for search and link quality. Set only_if_missing=true to only add fields that don't already exist (absorbed vault_add_frontmatter_field).
 
 Example: vault_update_frontmatter({ path: "projects/alpha.md", frontmatter: { status: "active", priority: 1 }, only_if_missing: true })`,
     {
@@ -18430,12 +18471,12 @@ import path26 from "path";
 function registerNoteTools(server2, getVaultPath, getIndex) {
   server2.tool(
     "vault_create_note",
-    'Create a new note in the vault with optional frontmatter and content.\n\nExample: vault_create_note({ path: "people/Jane Smith.md", content: "# Jane Smith\\n\\nProduct manager at Acme.", frontmatter: { type: "person", company: "Acme" } })',
+    'Create a new note in the vault. Always include frontmatter with at least type, aliases, and description \u2014 these drive entity categorization, search, and link suggestions.\n\nExample: vault_create_note({ path: "people/Jane Smith.md", content: "# Jane Smith\\n\\nProduct manager at Acme.", frontmatter: { type: "person", aliases: ["Jane"], description: "Product manager at Acme", company: "Acme" } })',
     {
       path: z16.string().describe('Vault-relative path for the new note (e.g., "daily-notes/2026-01-28.md")'),
       content: z16.string().default("").describe("Initial content for the note"),
       template: z16.string().optional().describe('Vault-relative path to a template file (e.g., "templates/person.md"). Template variables {{date}} and {{title}} are substituted. Template frontmatter is merged with the frontmatter parameter (explicit values take precedence).'),
-      frontmatter: z16.record(z16.any()).default({}).describe("Frontmatter fields (JSON object)"),
+      frontmatter: z16.record(z16.any()).default({}).describe("Frontmatter fields (JSON object). At minimum set type, aliases, and description \u2014 without these the note is nearly invisible to search and suggestions."),
       overwrite: z16.boolean().default(false).describe("If true, overwrite existing file"),
       commit: z16.boolean().default(false).describe("If true, commit this change to git (creates undo point)"),
       skipWikilinks: z16.boolean().default(false).describe("If true, skip auto-wikilink application (wikilinks are applied by default)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-memory",
-  "version": "2.0.143",
+  "version": "2.0.144",
   "description": "MCP server that gives Claude full read/write access to your Obsidian vault. Select from 74 tools for search, backlinks, graph queries, mutations, agent memory, and hybrid semantic search.",
   "type": "module",
   "main": "dist/index.js",
@@ -54,7 +54,7 @@
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@velvetmonkey/vault-core": "^2.0.143",
+    "@velvetmonkey/vault-core": "^2.0.144",
     "better-sqlite3": "^12.0.0",
     "chokidar": "^4.0.0",
     "gray-matter": "^4.0.3",