threadnote 1.1.5 → 1.2.0

package/.threadnoteignore

@@ -1,5 +1,7 @@
 .git/
 node_modules/
+.claude/worktrees/
+.worktrees/
 bazel-*/
 dist/
 build/

package/README.md

@@ -12,6 +12,14 @@ It is intentionally scoped to curated docs, memories, skills, and handoffs.
 **Walkthrough:** https://kashkovsky.github.io/threadnote/  
 **Wiki:** https://github.com/Kashkovsky/threadnote/wiki
 
+## Quickstart
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh
+threadnote mcp-install claude --apply   # or codex / cursor / copilot
+threadnote doctor --dry-run
+```
+
 ## Real-World Uses
 
 **Want to continue work in a fresh agent session?**  

package/dist/mcp_server.cjs

@@ -36192,6 +36192,8 @@ function grepUrisFromJson(output) {
     return [];
   }
 }
+var RECALL_CATEGORY_ORDER = ["memories", "resources", "skills"];
+var RECALL_PROMOTED_EXACT_SCORE = 0;
 function recallSnippet(value) {
   if (typeof value !== "string") {
     return "";
@@ -36217,7 +36219,7 @@ function parseRecallHits(output, options = {}) {
       return [];
     }
     const hits = [];
-    for (const key of ["memories", "resources", "skills"]) {
+    for (const key of RECALL_CATEGORY_ORDER) {
       const items = result[key];
       if (!Array.isArray(items)) {
         continue;
@@ -36230,6 +36232,7 @@ function parseRecallHits(output, options = {}) {
           continue;
         }
         hits.push({
+          category: key,
           contextType: typeof item.context_type === "string" ? item.context_type : "result",
           score: typeof item.score === "number" ? item.score : 0,
           snippet: recallSnippet(item.abstract ?? item.overview),
@@ -36242,33 +36245,135 @@ function parseRecallHits(output, options = {}) {
     return [];
   }
 }
+function stripAnchor(uri) {
+  return uri.replace(/#.*$/, "");
+}
 function mergeRecallHits(passes) {
   const byDocument = /* @__PURE__ */ new Map();
   for (const pass of passes) {
     for (const hit of pass) {
-      const documentUri = hit.uri.replace(/#.*$/, "");
+      const documentUri = stripAnchor(hit.uri);
       const existing = byDocument.get(documentUri);
       if (!existing || hit.score > existing.score) {
         byDocument.set(documentUri, { ...hit, uri: documentUri });
       }
     }
   }
-  return [...byDocument.values()].sort((left, right) => right.score - left.score);
+  return [...byDocument.values()].sort(
+    (left, right) => recallCategoryRank(left.category) - recallCategoryRank(right.category) || right.score - left.score
+  );
+}
+function recallCategoryRank(category) {
+  const index = RECALL_CATEGORY_ORDER.indexOf(category);
+  return index === -1 ? RECALL_CATEGORY_ORDER.length : index;
+}
+function dedupeByContent(hits) {
+  const seen = /* @__PURE__ */ new Set();
+  const kept = [];
+  for (const hit of hits) {
+    if (hit.category !== "memories" && hit.snippet.length > 0) {
+      const key = `${hit.category}
+${hit.snippet}`;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+    }
+    kept.push(hit);
+  }
+  return kept;
+}
+function categoryForUri(uri) {
+  if (uri.includes("/memories/")) {
+    return "memories";
+  }
+  if (uri.startsWith("viking://resources/agent-skills/")) {
+    return "skills";
+  }
+  return "resources";
 }
-function formatRecallHits(hits, maxHits) {
-  if (hits.length === 0) {
+function contextTypeForCategory(category) {
+  if (category === "memories") {
+    return "memory";
+  }
+  return category === "skills" ? "skill" : "resource";
+}
+function applyExactMatchBoost(hits, exactMatches) {
+  if (exactMatches.length === 0) {
+    return hits;
+  }
+  const termsByUri = new Map(exactMatches.map((match) => [stripAnchor(match.uri), match.terms]));
+  const annotated = hits.map((hit) => {
+    const terms = termsByUri.get(stripAnchor(hit.uri));
+    return terms ? { ...hit, exactTerms: terms } : hit;
+  });
+  const present = new Set(annotated.map((hit) => stripAnchor(hit.uri)));
+  const promoted = [...termsByUri.keys()].filter((uri) => !present.has(uri)).map((uri) => {
+    const category = categoryForUri(uri);
+    return {
+      category,
+      contextType: contextTypeForCategory(category),
+      exactTerms: termsByUri.get(uri) ?? [],
+      score: RECALL_PROMOTED_EXACT_SCORE,
+      snippet: "",
+      uri
+    };
+  });
+  return [...annotated, ...promoted].sort(
+    (left, right) => recallCategoryRank(left.category) - recallCategoryRank(right.category) || (right.exactTerms?.length ?? 0) - (left.exactTerms?.length ?? 0) || right.score - left.score
+  );
+}
+function renderRecallHits(shown, overflow) {
+  if (shown.length === 0) {
     return void 0;
   }
-  const shown = hits.slice(0, maxHits);
   const lines = shown.flatMap((hit, index) => {
-    const head = `${index + 1}. ${hit.contextType} \xB7 score ${hit.score.toFixed(2)} \xB7 ${hit.uri}`;
+    const scorePart = hit.score > 0 ? `score ${hit.score.toFixed(2)}` : void 0;
+    const exactPart = hit.exactTerms?.length ? `exact: ${hit.exactTerms.join(", ")}` : void 0;
+    const head = `${index + 1}. ${[hit.contextType, scorePart, exactPart].filter(Boolean).join(" \xB7 ")} \xB7 ${hit.uri}`;
     return hit.snippet ? [head, `   ${hit.snippet}`] : [head];
   });
-  if (hits.length > maxHits) {
-    lines.push(`(+${hits.length - maxHits} more \u2014 refine the query or read a URI above)`);
+  if (overflow > 0) {
+    lines.push(`(+${overflow} more \u2014 refine the query or read a URI above)`);
   }
   return lines.join("\n");
 }
+var RECALL_CATEGORY_RESERVE = 2;
+function selectShownHits(ranked, limit, reserve) {
+  if (ranked.length <= limit) {
+    return ranked;
+  }
+  const selected = /* @__PURE__ */ new Set();
+  for (const category of RECALL_CATEGORY_ORDER) {
+    let taken = 0;
+    for (const hit of ranked) {
+      if (selected.size >= limit || taken >= reserve) {
+        break;
+      }
+      if (hit.category === category && !selected.has(hit.uri)) {
+        selected.add(hit.uri);
+        taken += 1;
+      }
+    }
+  }
+  for (const hit of ranked) {
+    if (selected.size >= limit) {
+      break;
+    }
+    selected.add(hit.uri);
+  }
+  return ranked.filter((hit) => selected.has(hit.uri));
+}
+function buildRecallSections(passes, exactMatches, limit) {
+  const ranked = dedupeByContent(applyExactMatchBoost(mergeRecallHits(passes), exactMatches));
+  const shown = selectShownHits(ranked, limit, RECALL_CATEGORY_RESERVE);
+  const shownUris = new Set(shown.map((hit) => stripAnchor(hit.uri)));
+  return {
+    exactTail: formatExactMatchPointers(exactMatches.filter((match) => !shownUris.has(stripAnchor(match.uri)))),
+    ranked,
+    semanticSection: renderRecallHits(shown, ranked.length - shown.length)
+  };
+}
 function exactMemoryScopeUris(params) {
   const { agentMemoriesUri, includeArchived, intents, projectName, projectResourceUri, userBase } = params;
   const durable = projectName ? `${userBase}/durable/projects/${projectName}` : `${userBase}/durable/projects`;
@@ -38453,14 +38558,14 @@ function registerTools(server, config2) {
     "grep",
     {
       annotations: { readOnlyHint: true, destructiveHint: false },
-      description: "Run exact text search in OpenViking.",
+      description: "Run exact text search in OpenViking. Defaults to your memories subtree when uri is omitted (OpenViking grep requires a scope).",
       inputSchema: {
         caseInsensitive: external_exports.boolean().optional().describe("Case-insensitive search"),
         case_insensitive: external_exports.boolean().optional().describe("Case-insensitive search"),
         nodeLimit: external_exports.number().int().positive().max(1e3).optional().describe("Maximum result count"),
         node_limit: external_exports.number().int().positive().max(1e3).optional().describe("Maximum result count"),
         pattern: external_exports.string().optional().describe("Required text or regex pattern"),
-        uri: external_exports.string().optional().describe("Optional viking:// subtree")
+        uri: external_exports.string().optional().describe("Optional viking:// subtree (defaults to your memories root)")
       }
     },
     async ({ caseInsensitive, case_insensitive, nodeLimit, node_limit, pattern, uri }) => {
@@ -38476,7 +38581,7 @@ function registerTools(server, config2) {
         case_insensitive: caseInsensitive ?? case_insensitive,
         node_limit: nodeLimit ?? node_limit,
         pattern: checkedPattern.value,
-        uri: checkedUri.value
+        uri: checkedUri.value ?? `viking://user/${uriSegment2(config2.user)}/memories`
       });
     }
   );
@@ -39041,7 +39146,8 @@ async function runRecallTool(config2, params) {
     passes.push(seeded.hits);
   }
   const sections = [];
-  const semanticSection = formatRecallHits(mergeRecallHits(passes), params.nodeLimit ?? 12);
+  const exactMatches = await collectExactMemoryMatches(config2, query, params.includeArchived, project);
+  const { semanticSection, exactTail } = buildRecallSections(passes, exactMatches, params.nodeLimit ?? 12);
   if (semanticSection) {
     sections.push(semanticSection);
   } else if (!base.ok) {
@@ -39050,9 +39156,8 @@ async function runRecallTool(config2, params) {
   if (indexRepairMessages.length > 0) {
     sections.push(indexRepairMessages.join("\n"));
   }
-  const exactMatches = await exactMemoryMatchesText(config2, query, params.includeArchived, project);
-  if (exactMatches) {
-    sections.push(exactMatches);
+  if (exactTail) {
+    sections.push(exactTail);
   }
   const hygieneHints = await recallHygieneHintsSection(config2, sections.join("\n\n"));
   if (hygieneHints) {
@@ -39099,14 +39204,14 @@ async function recallHygieneHintsSection(config2, recallText) {
   const nudges = recallHygieneNudges(recallText, { records, user: config2.user });
   return nudges.length > 0 ? ["Memory hygiene hints:", ...nudges.map((nudge) => `- ${nudge}`)].join("\n") : void 0;
 }
-async function exactMemoryMatchesText(config2, query, includeArchived, project) {
+async function collectExactMemoryMatches(config2, query, includeArchived, project) {
   const terms = exactRecallTerms(query);
   if (terms.length === 0) {
-    return void 0;
+    return [];
   }
   const ov = await requiredOpenVikingCli2();
   const scopes = exactMemoryScopes(config2, includeArchived, query, project);
-  const matches = await collectExactMatches(terms, scopes, async (term, scope) => {
+  return collectExactMatches(terms, scopes, async (term, scope) => {
     const result = await runCommand(
       ov,
       withIdentity2(config2, ["grep", term, "--uri", scope, "--node-limit", "5", "--output", "json"]),
@@ -39114,7 +39219,6 @@ async function exactMemoryMatchesText(config2, query, includeArchived, project)
     );
     return result.exitCode === 0 ? result.stdout : void 0;
   });
-  return formatExactMatchPointers(matches);
 }
 function registerReadTool(server, config2, name, description) {
   server.registerTool(