@velvetmonkey/flywheel-memory 2.0.77 → 2.0.79

package/dist/index.js

@@ -121,7 +121,7 @@ function isEmptyPlaceholder(line) {
   const trimmed = line.trim();
   return EMPTY_PLACEHOLDER_PATTERNS.some((p) => p.test(trimmed));
 }
-function extractHeadings2(content) {
+function extractHeadings3(content) {
   const lines = content.split("\n");
   const headings = [];
   let inCodeBlock = false;
@@ -144,7 +144,7 @@ function extractHeadings2(content) {
   return headings;
 }
 function findSection(content, sectionName) {
-  const headings = extractHeadings2(content);
+  const headings = extractHeadings3(content);
   const lines = content.split("\n");
   const normalizedSearch = sectionName.replace(/^#+\s*/, "").trim().toLowerCase();
   const headingIndex = headings.findIndex(
@@ -1707,6 +1707,14 @@ function extractWikilinks(content) {
   }
   return links;
 }
+function extractHeadings(markdown) {
+  const headings = [];
+  for (const line of markdown.split("\n")) {
+    const match = line.match(/^(#{1,6})\s+(.+)/);
+    if (match) headings.push(match[2].trim());
+  }
+  return headings;
+}
 function extractTags(content, frontmatter) {
   const tags = /* @__PURE__ */ new Set();
   const fmTags = frontmatter.tags;
@@ -1808,6 +1816,7 @@ async function parseNoteWithWarnings(file) {
       frontmatter,
       outlinks: extractWikilinks(markdown),
       tags: extractTags(markdown, frontmatter),
+      headings: extractHeadings(markdown),
       modified: file.modified,
       created
     },
@@ -7213,7 +7222,7 @@ function searchFTS5(_vaultPath, query, limit = 10) {
       SELECT
         path,
         title,
-        snippet(notes_fts, 3, '<mark>', '</mark>', '...', 20) as snippet
+        snippet(notes_fts, 3, '<mark>', '</mark>', '...', 64) as snippet
       FROM notes_fts
       WHERE notes_fts MATCH ?
       ORDER BY bm25(notes_fts, 0.0, 5.0, 10.0, 1.0)
@@ -7231,6 +7240,19 @@ function searchFTS5(_vaultPath, query, limit = 10) {
 function getFTS5State() {
   return { ...state };
 }
+function getContentPreview(notePath, maxChars = 300) {
+  if (!db2) return null;
+  try {
+    const row = db2.prepare(
+      "SELECT substr(content, 1, ?) as preview FROM notes_fts WHERE path = ?"
+    ).get(maxChars + 50, notePath);
+    if (!row?.preview) return null;
+    const truncated = row.preview.length > maxChars ? row.preview.slice(0, maxChars).replace(/\s\S*$/, "") + "..." : row.preview;
+    return truncated;
+  } catch {
+    return null;
+  }
+}
 function countFTS5Mentions(term) {
   if (!db2) return 0;
   try {
@@ -9592,7 +9614,8 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
 import { z as z4 } from "zod";
 import {
   searchEntities,
-  searchEntitiesPrefix
+  searchEntitiesPrefix,
+  getEntityByName as getEntityByName2
 } from "@velvetmonkey/vault-core";
 function matchesFrontmatter(note, where) {
   for (const [key, value] of Object.entries(where)) {
@@ -9640,6 +9663,50 @@ function inFolder(note, folder) {
   const normalizedFolder = folder.endsWith("/") ? folder : folder + "/";
   return note.path.startsWith(normalizedFolder) || note.path.split("/")[0] === folder.replace("/", "");
 }
+function enrichResult(result, index, stateDb2) {
+  const note = index.notes.get(result.path);
+  const normalizedPath = result.path.toLowerCase().replace(/\.md$/, "");
+  const backlinks = index.backlinks.get(normalizedPath) || [];
+  const enriched = {
+    path: result.path,
+    title: result.title
+  };
+  if (result.snippet) enriched.snippet = result.snippet;
+  if (note) {
+    enriched.frontmatter = note.frontmatter;
+    enriched.tags = note.tags;
+    enriched.aliases = note.aliases;
+    enriched.backlink_count = backlinks.length;
+    enriched.backlinks = backlinks.map((bl) => ({ source: bl.source, line: bl.line }));
+    enriched.outlink_count = note.outlinks.length;
+    enriched.outlinks = note.outlinks.map((l) => {
+      const targetLower = l.target.toLowerCase();
+      const exists = index.entities.has(targetLower);
+      const out = { target: l.target, line: l.line, exists };
+      if (l.alias) out.alias = l.alias;
+      return out;
+    });
+    enriched.headings = note.headings || [];
+    enriched.modified = note.modified.toISOString();
+    if (note.created) enriched.created = note.created.toISOString();
+  }
+  if (stateDb2) {
+    try {
+      const entity = getEntityByName2(stateDb2, result.title);
+      if (entity) {
+        enriched.category = entity.category;
+        enriched.hub_score = entity.hubScore;
+        if (entity.description) enriched.description = entity.description;
+      }
+    } catch {
+    }
+  }
+  if (!result.snippet) {
+    const preview = getContentPreview(result.path);
+    if (preview) enriched.content_preview = preview;
+  }
+  return enriched;
+}
 function sortNotes(notes, sortBy, order) {
   const sorted = [...notes];
   sorted.sort((a, b) => {
@@ -9664,7 +9731,7 @@ function sortNotes(notes, sortBy, order) {
 function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
   server2.tool(
     "search",
-    'Search the vault across metadata, content, and entities. Scope controls what to search: "metadata" for frontmatter/tags/folders, "content" for full-text search (FTS5), "entities" for people/projects/technologies, "all" (default) tries metadata then falls back to content search. When embeddings have been built (via init_semantic), content and all scopes automatically include embedding-based results via hybrid ranking.\n\nExample: search({ query: "quarterly review", scope: "content", limit: 5 })\nExample: search({ where: { type: "project", status: "active" }, scope: "metadata" })',
+    'Search the vault \u2014 always try this before reading files. Returns frontmatter, backlinks (with lines), outlinks (with lines + exists), headings, content snippet or preview, entity metadata, and timestamps for every hit.\n\nSearch the vault across metadata, content, and entities. Scope controls what to search: "metadata" for frontmatter/tags/folders, "content" for full-text search (FTS5), "entities" for people/projects/technologies, "all" (default) tries metadata then falls back to content search. When embeddings have been built (via init_semantic), content and all scopes automatically include embedding-based results via hybrid ranking.\n\nExample: search({ query: "quarterly review", scope: "content", limit: 5 })\nExample: search({ where: { type: "project", status: "active" }, scope: "metadata" })',
     {
       query: z4.string().optional().describe('Search query text. Required for scope "content", "entities", "all". For "metadata" scope, use filters instead.'),
       scope: z4.enum(["metadata", "content", "entities", "all"]).default("all").describe("What to search: metadata (frontmatter/tags/folders), content (FTS5 full-text), entities (people/projects), all (metadata then content). Semantic results are automatically included when embeddings have been built (via init_semantic)."),
@@ -9751,14 +9818,10 @@ function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
         matchingNotes = sortNotes(matchingNotes, sort_by ?? "modified", order ?? "desc");
         const totalMatches = matchingNotes.length;
         const limitedNotes = matchingNotes.slice(0, limit);
-        const notes = limitedNotes.map((note) => ({
-          path: note.path,
-          title: note.title,
-          modified: note.modified.toISOString(),
-          created: note.created?.toISOString(),
-          tags: note.tags,
-          frontmatter: note.frontmatter
-        }));
+        const stateDb2 = getStateDb();
+        const notes = limitedNotes.map(
+          (note) => enrichResult({ path: note.path, title: note.title }, index, stateDb2)
+        );
         if (scope === "metadata" || hasMetadataFilters || totalMatches > 0) {
           return { content: [{ type: "text", text: JSON.stringify({
             scope: "metadata",
@@ -9847,22 +9910,20 @@ function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
             const fts5Map = new Map(fts5Results.map((r) => [normalizePath2(r.path), r]));
             const semanticMap = new Map(semanticResults.map((r) => [normalizePath2(r.path), r]));
             const entityMap = new Map(entityResults.map((r) => [normalizePath2(r.path), r]));
-            const merged = Array.from(allPaths).map((p) => ({
-              path: p,
-              title: fts5Map.get(p)?.title || semanticMap.get(p)?.title || entityMap.get(p)?.name || p.replace(/\.md$/, "").split("/").pop() || p,
-              snippet: fts5Map.get(p)?.snippet,
-              rrf_score: Math.round((rrfScores.get(p) || 0) * 1e4) / 1e4,
-              in_fts5: fts5Map.has(p),
-              in_semantic: semanticMap.has(p),
-              in_entity: entityMap.has(p)
-            }));
-            merged.sort((a, b) => b.rrf_score - a.rrf_score);
+            const merged = Array.from(allPaths).map((p) => {
+              const title = fts5Map.get(p)?.title || semanticMap.get(p)?.title || entityMap.get(p)?.name || p.replace(/\.md$/, "").split("/").pop() || p;
+              const snippet = fts5Map.get(p)?.snippet;
+              const rrfScore = rrfScores.get(p) || 0;
+              return { rrfScore, ...enrichResult({ path: p, title, snippet }, index, getStateDb()) };
+            });
+            merged.sort((a, b) => b.rrfScore - a.rrfScore);
+            const results = merged.slice(0, limit).map(({ rrfScore, ...rest }) => rest);
             return { content: [{ type: "text", text: JSON.stringify({
               scope,
               method: "hybrid",
               query,
               total_results: Math.min(merged.length, limit),
-              results: merged.slice(0, limit)
+              results
             }, null, 2) }] };
           } catch (err) {
             console.error("[Semantic] Hybrid search failed, falling back to FTS5:", err instanceof Error ? err.message : err);
@@ -9871,11 +9932,10 @@ function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
         if (entityResults.length > 0) {
           const normalizePath2 = (p) => p.replace(/\\/g, "/").replace(/\/+/g, "/");
           const fts5Map = new Map(fts5Results.map((r) => [normalizePath2(r.path), r]));
-          const entityNormMap = new Map(entityResults.map((r) => [normalizePath2(r.path), r]));
           const entityRanked = entityResults.filter((r) => !fts5Map.has(normalizePath2(r.path)));
           const merged = [
-            ...fts5Results.map((r) => ({ path: r.path, title: r.title, snippet: r.snippet, in_entity: entityNormMap.has(normalizePath2(r.path)) })),
-            ...entityRanked.map((r) => ({ path: r.path, title: r.name, snippet: void 0, in_entity: true }))
+            ...fts5Results.map((r) => enrichResult({ path: r.path, title: r.title, snippet: r.snippet }, index, getStateDb())),
+            ...entityRanked.map((r) => enrichResult({ path: r.path, title: r.name }, index, getStateDb()))
           ];
           return { content: [{ type: "text", text: JSON.stringify({
             scope: "content",
@@ -9885,12 +9945,13 @@ function registerQueryTools(server2, getIndex, getVaultPath, getStateDb) {
             results: merged.slice(0, limit)
           }, null, 2) }] };
         }
+        const enrichedFts5 = fts5Results.map((r) => enrichResult({ path: r.path, title: r.title, snippet: r.snippet }, index, getStateDb()));
         return { content: [{ type: "text", text: JSON.stringify({
           scope: "content",
           method: "fts5",
           query,
-          total_results: fts5Results.length,
-          results: fts5Results
+          total_results: enrichedFts5.length,
+          results: enrichedFts5
         }, null, 2) }] };
       }
       return { content: [{ type: "text", text: JSON.stringify({ error: "Invalid scope" }, null, 2) }] };
@@ -10260,104 +10321,6 @@ function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfi
       };
     }
   );
-  const GetNoteMetadataOutputSchema = {
-    path: z5.string().describe("Path to the note"),
-    title: z5.string().describe("Note title"),
-    exists: z5.boolean().describe("Whether the note exists"),
-    frontmatter: z5.record(z5.unknown()).describe("Frontmatter properties"),
-    tags: z5.array(z5.string()).describe("Tags on this note"),
-    aliases: z5.array(z5.string()).describe("Aliases for this note"),
-    outlink_count: z5.number().describe("Number of outgoing links"),
-    backlink_count: z5.number().describe("Number of incoming links"),
-    word_count: z5.number().optional().describe("Approximate word count"),
-    created: z5.string().optional().describe("Created date (ISO format)"),
-    modified: z5.string().describe("Last modified date (ISO format)")
-  };
-  server2.registerTool(
-    "get_note_metadata",
-    {
-      title: "Get Note Metadata",
-      description: "Get metadata about a note (frontmatter, tags, link counts) without reading full content. Useful for quick analysis.",
-      inputSchema: {
-        path: z5.string().describe("Path to the note"),
-        include_word_count: z5.boolean().default(false).describe("Count words (requires reading file)")
-      },
-      outputSchema: GetNoteMetadataOutputSchema
-    },
-    async ({
-      path: notePath,
-      include_word_count
-    }) => {
-      requireIndex();
-      const index = getIndex();
-      const vaultPath2 = getVaultPath();
-      let resolvedPath = notePath;
-      if (!notePath.endsWith(".md")) {
-        const resolved = index.entities.get(notePath.toLowerCase());
-        if (resolved) {
-          resolvedPath = resolved;
-        } else {
-          resolvedPath = notePath + ".md";
-        }
-      }
-      const note = index.notes.get(resolvedPath);
-      if (!note) {
-        const output2 = {
-          path: resolvedPath,
-          title: resolvedPath.replace(/\.md$/, "").split("/").pop() || "",
-          exists: false,
-          frontmatter: {},
-          tags: [],
-          aliases: [],
-          outlink_count: 0,
-          backlink_count: 0,
-          modified: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(output2, null, 2)
-            }
-          ],
-          structuredContent: output2
-        };
-      }
-      const normalizedPath = resolvedPath.toLowerCase().replace(/\.md$/, "");
-      const backlinks = index.backlinks.get(normalizedPath) || [];
-      let wordCount;
-      if (include_word_count) {
-        try {
-          const fullPath = path14.join(vaultPath2, resolvedPath);
-          const content = await fs11.promises.readFile(fullPath, "utf-8");
-          wordCount = content.split(/\s+/).filter((w) => w.length > 0).length;
-        } catch {
-        }
-      }
-      const output = {
-        path: note.path,
-        title: note.title,
-        exists: true,
-        frontmatter: note.frontmatter,
-        tags: note.tags,
-        aliases: note.aliases,
-        outlink_count: note.outlinks.length,
-        backlink_count: backlinks.length,
-        word_count: wordCount,
-        created: note.created?.toISOString(),
-        modified: note.modified.toISOString()
-      };
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(output, null, 2)
-          }
-        ],
-        structuredContent: output
-      };
-    }
-  );
   const GetFolderStructureOutputSchema = {
     folder_count: z5.number().describe("Total number of folders"),
     folders: z5.array(
@@ -10561,7 +10524,7 @@ import { z as z6 } from "zod";
 import * as fs12 from "fs";
 import * as path15 from "path";
 var HEADING_REGEX2 = /^(#{1,6})\s+(.+)$/;
-function extractHeadings(content) {
+function extractHeadings2(content) {
   const lines = content.split("\n");
   const headings = [];
   let inCodeBlock = false;
@@ -10621,7 +10584,7 @@ async function getNoteStructure(index, notePath, vaultPath2) {
     return null;
   }
   const lines = content.split("\n");
-  const headings = extractHeadings(content);
+  const headings = extractHeadings2(content);
   const sections = buildSections(headings, lines.length);
   const contentWithoutCode = content.replace(/```[\s\S]*?```/g, "");
   const words = contentWithoutCode.split(/\s+/).filter((w) => w.length > 0);
@@ -10644,7 +10607,7 @@ async function getSectionContent(index, notePath, headingText, vaultPath2, inclu
     return null;
   }
   const lines = content.split("\n");
-  const headings = extractHeadings(content);
+  const headings = extractHeadings2(content);
   const targetHeading = headings.find(
     (h) => h.text.toLowerCase() === headingText.toLowerCase()
   );
@@ -10685,7 +10648,7 @@ async function findSections(index, headingPattern, vaultPath2, folder) {
     } catch {
       continue;
     }
-    const headings = extractHeadings(content);
+    const headings = extractHeadings2(content);
     for (const heading of headings) {
       if (regex.test(heading.text)) {
         results.push({
@@ -10701,12 +10664,13 @@ async function findSections(index, headingPattern, vaultPath2, folder) {
 }
 
 // src/tools/read/primitives.ts
-function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = () => ({})) {
+import { getEntityByName as getEntityByName3 } from "@velvetmonkey/vault-core";
+function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = () => ({}), getStateDb = () => null) {
   server2.registerTool(
     "get_note_structure",
     {
       title: "Get Note Structure",
-      description: "Get the heading structure and sections of a note. Returns headings, sections hierarchy, word count, and line count.",
+      description: "Read the structure of a specific note. Use after search identifies a note you need more detail on. Returns headings, frontmatter, tags, word count. Set include_content: true to get the full markdown.",
       inputSchema: {
         path: z6.string().describe("Path to the note"),
         include_content: z6.boolean().default(false).describe("Include the text content under each top-level section")
@@ -10729,8 +10693,31 @@ function registerPrimitiveTools(server2, getIndex, getVaultPath, getConfig = ()
           }
         }
       }
+      const note = index.notes.get(path33);
+      const enriched = { ...result };
+      if (note) {
+        enriched.frontmatter = note.frontmatter;
+        enriched.tags = note.tags;
+        enriched.aliases = note.aliases;
+        const normalizedPath = path33.toLowerCase().replace(/\.md$/, "");
+        const backlinks = index.backlinks.get(normalizedPath) || [];
+        enriched.backlink_count = backlinks.length;
+        enriched.outlink_count = note.outlinks.length;
+      }
+      const stateDb2 = getStateDb();
+      if (stateDb2 && note) {
+        try {
+          const entity = getEntityByName3(stateDb2, note.title);
+          if (entity) {
+            enriched.category = entity.category;
+            enriched.hub_score = entity.hubScore;
+            if (entity.description) enriched.description = entity.description;
+          }
+        } catch {
+        }
+      }
       return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(enriched, null, 2) }]
       };
     }
   );
@@ -13270,7 +13257,7 @@ function ensureSectionExists(content, section, notePath) {
   if (boundary) {
     return { boundary };
   }
-  const headings = extractHeadings2(content);
+  const headings = extractHeadings3(content);
   let message;
   if (headings.length === 0) {
     message = `Section '${section}' not found. This file has no headings. Add section structure (## Heading) to enable section-scoped mutations.`;
@@ -19333,59 +19320,58 @@ var watcherStatus = null;
 function getWatcherStatus() {
   return watcherStatus;
 }
-var PRESETS = {
-  // Presets
-  minimal: ["search", "structure", "append", "frontmatter", "notes"],
-  writer: ["search", "structure", "append", "frontmatter", "notes", "tasks"],
-  agent: ["search", "structure", "append", "frontmatter", "notes", "memory"],
-  researcher: ["search", "structure", "backlinks", "hubs", "paths"],
-  full: [
-    "search",
-    "backlinks",
-    "orphans",
-    "hubs",
-    "paths",
-    "schema",
-    "structure",
-    "tasks",
-    "health",
-    "wikilinks",
-    "append",
-    "frontmatter",
-    "notes",
-    "note-ops",
-    "git",
-    "policy",
-    "memory"
-  ],
-  // Composable bundles
-  graph: ["backlinks", "orphans", "hubs", "paths"],
-  analysis: ["schema", "wikilinks"],
-  tasks: ["tasks"],
-  health: ["health"],
-  ops: ["git", "policy"],
-  "note-ops": ["note-ops"]
-};
 var ALL_CATEGORIES = [
-  "backlinks",
-  "orphans",
-  "hubs",
-  "paths",
   "search",
+  "read",
+  "write",
+  "graph",
   "schema",
-  "structure",
-  "tasks",
-  "health",
   "wikilinks",
-  "append",
-  "frontmatter",
-  "notes",
+  "corrections",
+  "tasks",
+  "memory",
   "note-ops",
-  "git",
-  "policy",
-  "memory"
+  "diagnostics",
+  "automation"
 ];
-var DEFAULT_PRESET = "full";
+var PRESETS = {
+  // Presets
+  default: ["search", "read", "write", "tasks"],
+  agent: ["search", "read", "write", "memory"],
+  full: ALL_CATEGORIES,
+  // Composable bundles (one per category)
+  graph: ["graph"],
+  schema: ["schema"],
+  wikilinks: ["wikilinks"],
+  corrections: ["corrections"],
+  tasks: ["tasks"],
+  memory: ["memory"],
+  "note-ops": ["note-ops"],
+  diagnostics: ["diagnostics"],
+  automation: ["automation"]
+};
+var DEFAULT_PRESET = "default";
+var DEPRECATED_ALIASES = {
+  minimal: "default",
+  writer: "default",
+  // writer was default+tasks, now default includes tasks
+  researcher: "default",
+  // use default,graph for graph exploration
+  backlinks: "graph",
+  // get_backlinks moved to graph
+  structure: "read",
+  append: "write",
+  frontmatter: "write",
+  notes: "write",
+  orphans: "graph",
+  hubs: "graph",
+  paths: "graph",
+  health: "diagnostics",
+  analysis: "wikilinks",
+  git: "automation",
+  ops: "automation",
+  policy: "automation"
+};
 function parseEnabledCategories() {
   const envValue = (process.env.FLYWHEEL_TOOLS ?? process.env.FLYWHEEL_PRESET)?.trim();
   if (!envValue) {
@@ -19395,13 +19381,25 @@ function parseEnabledCategories() {
   if (PRESETS[lowerValue]) {
     return new Set(PRESETS[lowerValue]);
   }
+  if (DEPRECATED_ALIASES[lowerValue]) {
+    const resolved = DEPRECATED_ALIASES[lowerValue];
+    serverLog("server", `Preset "${lowerValue}" is deprecated \u2014 use "${resolved}" instead`, "warn");
+    if (PRESETS[resolved]) {
+      return new Set(PRESETS[resolved]);
+    }
+    return /* @__PURE__ */ new Set([resolved]);
+  }
   const categories = /* @__PURE__ */ new Set();
   for (const item of envValue.split(",")) {
-    const category = item.trim().toLowerCase();
-    if (ALL_CATEGORIES.includes(category)) {
-      categories.add(category);
-    } else if (PRESETS[category]) {
-      for (const c of PRESETS[category]) {
+    const raw = item.trim().toLowerCase();
+    const resolved = DEPRECATED_ALIASES[raw] ?? raw;
+    if (resolved !== raw) {
+      serverLog("server", `Category "${raw}" is deprecated \u2014 use "${resolved}" instead`, "warn");
+    }
+    if (ALL_CATEGORIES.includes(resolved)) {
+      categories.add(resolved);
+    } else if (PRESETS[resolved]) {
+      for (const c of PRESETS[resolved]) {
         categories.add(c);
       }
     } else {
@@ -19416,88 +19414,146 @@ function parseEnabledCategories() {
 }
 var enabledCategories = parseEnabledCategories();
 var TOOL_CATEGORY = {
-  // health (includes periodic detection in output)
-  health_check: "health",
-  get_vault_stats: "health",
-  get_folder_structure: "health",
-  refresh_index: "health",
-  // absorbed rebuild_search_index
-  get_all_entities: "health",
-  list_entities: "hubs",
-  get_unlinked_mentions: "health",
-  // search (unified: metadata + content + entities)
+  // search (3 tools)
   search: "search",
   init_semantic: "search",
-  // backlinks
-  get_backlinks: "backlinks",
-  get_forward_links: "backlinks",
-  // orphans (graph_analysis covers orphans, dead_ends, sources, hubs, stale)
-  graph_analysis: "orphans",
-  get_connection_strength: "hubs",
-  // paths
-  get_link_path: "paths",
-  get_common_neighbors: "paths",
-  // schema (vault_schema + note_intelligence cover all schema tools)
+  find_similar: "search",
+  // read (3 tools) — note reading
+  get_note_structure: "read",
+  get_section_content: "read",
+  find_sections: "read",
+  // write (5 tools) — content mutations + frontmatter + note creation
+  vault_add_to_section: "write",
+  vault_remove_from_section: "write",
+  vault_replace_in_section: "write",
+  vault_update_frontmatter: "write",
+  vault_create_note: "write",
+  // graph (9 tools) — structural analysis + link detail
+  graph_analysis: "graph",
+  get_backlinks: "graph",
+  get_forward_links: "graph",
+  get_connection_strength: "graph",
+  list_entities: "graph",
+  get_link_path: "graph",
+  get_common_neighbors: "graph",
+  get_weighted_links: "graph",
+  get_strong_connections: "graph",
+  // schema (5 tools) — schema intelligence + migrations
   vault_schema: "schema",
   note_intelligence: "schema",
-  // structure (absorbed get_headings + vault_list_sections)
-  get_note_structure: "structure",
-  get_section_content: "structure",
-  find_sections: "structure",
-  get_note_metadata: "structure",
-  // tasks (unified: all task queries + write)
+  rename_field: "schema",
+  migrate_field_values: "schema",
+  rename_tag: "schema",
+  // wikilinks (7 tools) — suggestions, validation, discovery
+  suggest_wikilinks: "wikilinks",
+  validate_links: "wikilinks",
+  wikilink_feedback: "wikilinks",
+  discover_stub_candidates: "wikilinks",
+  discover_cooccurrence_gaps: "wikilinks",
+  suggest_entity_aliases: "wikilinks",
+  unlinked_mentions_report: "wikilinks",
+  // corrections (4 tools)
+  vault_record_correction: "corrections",
+  vault_list_corrections: "corrections",
+  vault_resolve_correction: "corrections",
+  absorb_as_alias: "corrections",
+  // tasks (3 tools)
   tasks: "tasks",
   vault_toggle_task: "tasks",
   vault_add_task: "tasks",
-  // wikilinks
-  suggest_wikilinks: "wikilinks",
-  validate_links: "wikilinks",
-  // append (content mutations)
-  vault_add_to_section: "append",
-  vault_remove_from_section: "append",
-  vault_replace_in_section: "append",
-  // frontmatter (absorbed vault_add_frontmatter_field via only_if_missing)
-  vault_update_frontmatter: "frontmatter",
-  // notes (create only)
-  vault_create_note: "notes",
-  // note-ops (file management)
+  // memory (3 tools) — agent working memory
+  memory: "memory",
+  recall: "memory",
+  brief: "memory",
+  // note-ops (4 tools) — file management
   vault_delete_note: "note-ops",
   vault_move_note: "note-ops",
   vault_rename_note: "note-ops",
-  // git
-  vault_undo_last_mutation: "git",
-  // policy
-  policy: "policy",
-  // schema (migrations + tag rename)
-  rename_field: "schema",
-  migrate_field_values: "schema",
-  rename_tag: "schema",
-  // health (growth metrics)
-  vault_growth: "health",
-  // wikilinks (feedback)
-  wikilink_feedback: "wikilinks",
-  // health (activity tracking)
-  vault_activity: "health",
-  // schema (content similarity)
-  find_similar: "schema",
-  // health (config management)
-  flywheel_config: "health",
-  // health (server activity log)
-  server_log: "health",
-  // health (merge suggestions)
-  suggest_entity_merges: "health",
-  dismiss_merge_suggestion: "health",
-  // note-ops (entity merge)
   merge_entities: "note-ops",
-  // memory (agent working memory)
-  memory: "memory",
-  recall: "memory",
-  brief: "memory"
+  // diagnostics (13 tools) — vault health, stats, config, activity
+  health_check: "diagnostics",
+  get_vault_stats: "diagnostics",
+  get_folder_structure: "diagnostics",
+  refresh_index: "diagnostics",
+  get_all_entities: "diagnostics",
+  get_unlinked_mentions: "diagnostics",
+  vault_growth: "diagnostics",
+  vault_activity: "diagnostics",
+  flywheel_config: "diagnostics",
+  server_log: "diagnostics",
+  suggest_entity_merges: "diagnostics",
+  dismiss_merge_suggestion: "diagnostics",
+  vault_init: "diagnostics",
+  // automation (2 tools) — git undo + policy engine
+  vault_undo_last_mutation: "automation",
+  policy: "automation"
 };
-var server = new McpServer({
-  name: "flywheel-memory",
-  version: pkg.version
-});
+function generateInstructions(categories) {
+  const parts = [];
+  parts.push(`Flywheel provides tools to search, read, and write an Obsidian vault's knowledge graph.
+
+Tool selection:
+  1. "search" is the primary tool. Each result includes: frontmatter, tags, aliases,
+     backlinks (with line numbers), outlinks (with line numbers and existence check),
+     headings, content snippet or preview, entity category, hub score, and timestamps.
+     This is usually enough to answer without reading any files.
+  2. Escalate to "get_note_structure" only when you need the full markdown content
+     or word count. Use "get_section_content" to read one section by heading name.
+  3. Use vault write tools instead of raw file writes \u2014 they auto-link entities
+     and commit changes.`);
+  if (categories.has("read")) {
+    parts.push(`
+## Read
+
+Escalation: "search" (enriched metadata + content preview) \u2192 "get_note_structure"
+(full content + word count) \u2192 "get_section_content" (single section).
+"find_sections" finds headings across the vault by pattern.`);
+  }
+  if (categories.has("write")) {
+    parts.push(`
+## Write
+
+Write to existing notes with "vault_add_to_section". Create new notes with "vault_create_note". Update metadata with "vault_update_frontmatter". All writes auto-link entities \u2014 no manual [[wikilinks]] needed.`);
+  }
+  if (categories.has("memory")) {
+    parts.push(`
+## Memory
+
+Session workflow: call "brief" at conversation start for vault context (recent sessions, active entities, stored memories). Use "recall" before answering questions \u2014 it searches entities, notes, and memories with graph-boosted ranking. Use "memory" to store observations that should persist across sessions.`);
+  }
+  if (categories.has("graph")) {
+    parts.push(`
+## Graph
+
+Use "get_backlinks" for per-backlink surrounding text (reads source files).
+Use "get_forward_links" for resolved file paths and alias text.
+Use "graph_analysis" for structural queries (hubs, orphans, dead ends).
+Use "get_connection_strength" to measure link strength between notes.
+Use "get_link_path" to find shortest paths.`);
+  }
+  if (categories.has("tasks")) {
+    parts.push(`
+## Tasks
+
+Use "tasks" to query tasks across the vault (filter by status, due date, path). Use "vault_add_task" to create tasks and "vault_toggle_task" to complete them.`);
+  }
+  if (categories.has("schema")) {
+    parts.push(`
+## Schema
+
+Use "vault_schema" before bulk operations to understand field conventions, inconsistencies, and note types. Use "note_intelligence" for per-note analysis.`);
+  }
+  return parts.join("\n");
+}
+var server = new McpServer(
+  {
+    name: "flywheel-memory",
+    version: pkg.version
+  },
+  {
+    instructions: generateInstructions(enabledCategories)
+  }
+);
 var _registeredCount = 0;
 var _skippedCount = 0;
 function gateByCategory(name) {
@@ -19587,7 +19643,7 @@ registerSystemTools(
 registerGraphTools(server, () => vaultIndex, () => vaultPath, () => stateDb);
 registerWikilinkTools(server, () => vaultIndex, () => vaultPath);
 registerQueryTools(server, () => vaultIndex, () => vaultPath, () => stateDb);
-registerPrimitiveTools(server, () => vaultIndex, () => vaultPath, () => flywheelConfig);
+registerPrimitiveTools(server, () => vaultIndex, () => vaultPath, () => flywheelConfig, () => stateDb);
 registerGraphAnalysisTools(server, () => vaultIndex, () => vaultPath, () => stateDb, () => flywheelConfig);
 registerVaultSchemaTools(server, () => vaultIndex, () => vaultPath);
 registerNoteIntelligenceTools(server, () => vaultIndex, () => vaultPath, () => flywheelConfig);

package/package.json

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