threadnote 1.4.5 → 1.6.0

package/config/seed-manifest.example.yaml

@@ -13,3 +13,12 @@ projects:
       - .claude/commands/*.md
       - .claude/skills/**/SKILL.md
       - docs/**/*.md
+
+# Optional: worksets group related projects into one recall working set.
+# `threadnote recall --workset <name>` (or a query mentioning the name) expands
+# recall across every member's durable + seeded scope. Unknown member names are
+# ignored. Inspect with `threadnote workset list` / `threadnote workset show`.
+# worksets:
+#   - name: example-stack
+#     description: service plus its client
+#     projects: [example-service, example-client]

package/dist/mcp_server.cjs

@@ -35519,6 +35519,9 @@ function redactText(content) {
     "$1[REDACTED]"
   ).replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]").replace(/sk-[A-Za-z0-9_-]{16,}/g, "sk-[REDACTED]").replace(/gh[pousr]_[A-Za-z0-9_]{16,}/g, "gh_[REDACTED]");
 }
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 async function requiredOpenVikingCli() {
   const command2 = await findOpenVikingCli();
   if (!command2) {
@@ -35906,14 +35909,19 @@ function exactRecallTerms(query) {
     "after",
     "agent",
     "anything",
+    "been",
     "branch",
     "case",
     "current",
+    "does",
     "durable",
     "find",
     "feature",
     "features",
+    "from",
     "handoff",
+    "have",
+    "into",
     "issue",
     "issues",
     "knowledge",
@@ -35927,11 +35935,22 @@ function exactRecallTerms(query) {
     "related",
     "search",
     "stored",
+    "than",
+    "that",
+    "them",
+    "then",
+    "they",
     "this",
     "the",
+    "were",
+    "what",
+    "when",
+    "which",
+    "while",
     "with",
     "workspace",
-    "worktree"
+    "worktree",
+    "your"
   ]);
   const seen = /* @__PURE__ */ new Set();
   const terms = [];
@@ -35965,6 +35984,12 @@ function exactRecallScopeIntents(query) {
 function isSummarySidecarUri(uri) {
   return /\.(?:overview|abstract)\.md(?:#|$)/.test(uri);
 }
+function isAgentArtifactPackUri(uri) {
+  return /\/agent-artifacts\/packs\//.test(uri);
+}
+function isExcludedRecallUri(uri) {
+  return isSummarySidecarUri(uri) || isAgentArtifactPackUri(uri);
+}
 function grepUrisFromJson(output) {
   const start = output.search(/^\{/m);
   if (start < 0) {
@@ -35979,7 +36004,7 @@ function grepUrisFromJson(output) {
     }
     const uris = [];
     for (const match of matches) {
-      if (isJsonObject(match) && typeof match.uri === "string" && !isSummarySidecarUri(match.uri)) {
+      if (isJsonObject(match) && typeof match.uri === "string" && !isExcludedRecallUri(match.uri)) {
         uris.push(match.uri);
       }
     }
@@ -36021,7 +36046,7 @@ function parseRecallHits(output, options = {}) {
         continue;
       }
       for (const item of items) {
-        if (!isJsonObject(item) || typeof item.uri !== "string" || isSummarySidecarUri(item.uri)) {
+        if (!isJsonObject(item) || typeof item.uri !== "string" || isExcludedRecallUri(item.uri)) {
           continue;
         }
         if (options.includeArchived !== true && isArchivedMemoryUri(item.uri)) {
@@ -36080,6 +36105,9 @@ ${hit.snippet}`;
   return kept;
 }
 function categoryForUri(uri) {
+  if (uri.includes("/agent-artifacts/")) {
+    return "skills";
+  }
   if (uri.includes("/memories/")) {
     return "memories";
   }
@@ -36094,6 +36122,36 @@ function contextTypeForCategory(category) {
   }
   return category === "skills" ? "skill" : "resource";
 }
+var RECALL_EXACT_SLUG_BONUS = 4;
+function uriSlug(uri) {
+  const withoutExtension = stripAnchor(uri).replace(/\.[a-z0-9]+$/i, "");
+  return withoutExtension.slice(withoutExtension.lastIndexOf("/") + 1).toLowerCase();
+}
+function exactTermDocumentFrequency(matches) {
+  const frequency = /* @__PURE__ */ new Map();
+  for (const match of matches) {
+    for (const term of new Set(match.terms.map((term2) => term2.toLowerCase()))) {
+      frequency.set(term, (frequency.get(term) ?? 0) + 1);
+    }
+  }
+  return frequency;
+}
+function slugNamesTerm(slug, term) {
+  return new RegExp(`(^|[^a-z0-9])${escapeRegExp(term)}([^a-z0-9]|$)`).test(slug);
+}
+function exactMatchStrength(hit, documentFrequency) {
+  if (!hit.exactTerms?.length) {
+    return 0;
+  }
+  const slug = uriSlug(hit.uri);
+  let strength = 0;
+  for (const term of hit.exactTerms) {
+    const normalized = term.toLowerCase();
+    const rarity = 1 / (documentFrequency.get(normalized) ?? 1);
+    strength += rarity * (slugNamesTerm(slug, normalized) ? RECALL_EXACT_SLUG_BONUS : 1);
+  }
+  return strength;
+}
 function applyExactMatchBoost(hits, exactMatches) {
   if (exactMatches.length === 0) {
     return hits;
@@ -36115,24 +36173,33 @@ function applyExactMatchBoost(hits, exactMatches) {
       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
+  const documentFrequency = exactTermDocumentFrequency(exactMatches);
+  const merged = [...annotated, ...promoted];
+  const combinedRelevanceByUri = /* @__PURE__ */ new Map();
+  for (const hit of merged) {
+    combinedRelevanceByUri.set(stripAnchor(hit.uri), exactMatchStrength(hit, documentFrequency) + hit.score);
+  }
+  return merged.sort(
+    (left, right) => recallCategoryRank(left.category) - recallCategoryRank(right.category) || (combinedRelevanceByUri.get(stripAnchor(right.uri)) ?? 0) - (combinedRelevanceByUri.get(stripAnchor(left.uri)) ?? 0) || right.score - left.score
   );
 }
+var RECALL_LOW_CONFIDENCE_NOTE = "\u26A0 No semantically-relevant matches \u2014 the results below only contain the query words (the corpus may not cover this topic).";
 function renderRecallHits(shown, overflow) {
   if (shown.length === 0) {
     return void 0;
   }
   const lines = shown.flatMap((hit, index) => {
     const scorePart = hit.score > 0 ? `score ${hit.score.toFixed(2)}` : void 0;
-    const exactPart = hit.exactTerms?.length ? `exact: ${hit.exactTerms.join(", ")}` : void 0;
+    const exactLabel = hit.score > 0 ? "exact" : "keyword-only";
+    const exactPart = hit.exactTerms?.length ? `${exactLabel}: ${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 (overflow > 0) {
     lines.push(`(+${overflow} more \u2014 refine the query or read a URI above)`);
   }
-  return lines.join("\n");
+  const noSemanticMatch = shown.every((hit) => hit.score === 0);
+  return (noSemanticMatch ? [RECALL_LOW_CONFIDENCE_NOTE, ...lines] : lines).join("\n");
 }
 var RECALL_CATEGORY_RESERVE = 2;
 function selectShownHits(ranked, limit, reserve) {
@@ -36301,6 +36368,35 @@ async function inferProjectFromQuery(manifestPath, query) {
     return void 0;
   }
 }
+function resolveWorksetProjects(manifest, workset) {
+  const byName = new Map(manifest.projects.map((project) => [project.name.toLowerCase(), project]));
+  const projects = workset.projects.map((name) => byName.get(name.toLowerCase())).filter((project) => project !== void 0);
+  return { name: workset.name, projects };
+}
+async function requireWorkset(manifestPath, worksetName) {
+  const manifest = await readSeedManifest(manifestPath);
+  const workset = manifest.worksets?.find((entry) => entry.name.toLowerCase() === worksetName.toLowerCase());
+  if (!workset) {
+    throw new Error(`No workset named "${worksetName}" in ${manifestPath}.`);
+  }
+  return resolveWorksetProjects(manifest, workset);
+}
+async function inferWorksetFromQuery(manifestPath, query) {
+  try {
+    const manifest = await readSeedManifest(manifestPath);
+    if (!manifest.worksets || manifest.worksets.length === 0) {
+      return void 0;
+    }
+    const workset = manifest.worksets.find((entry) => containsNameToken(query, entry.name));
+    return workset ? resolveWorksetProjects(manifest, workset) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function containsNameToken(query, name) {
+  const escaped = escapeRegExp(name.toLowerCase());
+  return new RegExp(`(^|[^a-z0-9])${escaped}($|[^a-z0-9])`).test(query.toLowerCase());
+}
 async function readSeedManifest(path) {
   const raw = await (0, import_promises2.readFile)(path, "utf8");
   const loaded = index_vite_proxy_tmp_default.load(raw);
@@ -36332,7 +36428,33 @@ async function readSeedManifest(path) {
       uri: readString(loaded.future_monorepo, "uri")
     };
   }
-  return { futureMonorepo, projects, version: version2 };
+  let worksets;
+  if (loaded.worksets !== void 0) {
+    if (!Array.isArray(loaded.worksets)) {
+      throw new Error(`Manifest worksets must be an array: ${path}`);
+    }
+    worksets = loaded.worksets.map((worksetValue) => {
+      if (!isJsonObject(worksetValue)) {
+        throw new Error(`Manifest workset must be an object: ${path}`);
+      }
+      return {
+        description: readOptionalString(worksetValue, "description"),
+        name: readString(worksetValue, "name"),
+        projects: readStringArray(worksetValue, "projects")
+      };
+    });
+  }
+  return { futureMonorepo, projects, version: version2, worksets };
+}
+function readOptionalString(object3, key) {
+  const value = object3[key];
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`Expected string for ${key}`);
+  }
+  return value;
 }
 function readString(object3, key) {
   const value = object3[key];
@@ -37391,7 +37513,7 @@ async function collectPackMembers(manifestDir, manifest) {
   }
   return [...members.values()].sort((a, b) => compareStrings(a.relativePath, b.relativePath));
 }
-function escapeRegExp(value) {
+function escapeRegExp2(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function tokenizePackPaths(text, rewriteRoots) {
@@ -37399,7 +37521,7 @@ function tokenizePackPaths(text, rewriteRoots) {
   for (const root of rewriteRoots) {
     if (root.length > 0) {
       out = out.replace(
-        new RegExp(`(?<![A-Za-z0-9/._~-])${escapeRegExp(root)}(?=[/\\\\]|["'\`\\s),>:\\]};=]|$)`, "g"),
+        new RegExp(`(?<![A-Za-z0-9/._~-])${escapeRegExp2(root)}(?=[/\\\\]|["'\`\\s),>:\\]};=]|$)`, "g"),
         PACK_ROOT_TOKEN
       );
     }
@@ -38521,7 +38643,7 @@ function stripPersonalProvenance(content) {
   }
   const cleaned = [];
   for (let index = 0; index < headerEnd; index += 1) {
-    if (/^(?:supersedes|archived_from):\s/.test(lines[index])) {
+    if (/^(?:supersedes|archived_from|references):\s/.test(lines[index])) {
       continue;
     }
     cleaned.push(lines[index]);
@@ -38935,6 +39057,7 @@ function parseMemoryDocument(uri, content) {
       archivedFrom: headerValue(header, "archived_from"),
       kind,
       project: normalizeOptionalMetadata(headerValue(header, "project") ?? headerValue(header, "repo")),
+      references: headerValues(header, "references"),
       sourceAgentClient: headerValue(header, "source_agent_client") ?? "unknown",
       status,
       supersedes: headerValue(header, "supersedes"),
@@ -39136,6 +39259,24 @@ function recallHygieneNudges(text, options) {
   }
   return [...new Set(nudges)];
 }
+function referencedUrisFromRecords(records, recallOutput) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const record2 of records) {
+    for (const uri of record2.metadata.references ?? []) {
+      if (seen.has(uri) || recallOutput.includes(uri)) {
+        continue;
+      }
+      seen.add(uri);
+      result.push(uri);
+    }
+  }
+  return result;
+}
+function referencedContextExcerpt(body, maxLines) {
+  const lines = body.split("\n").map((line) => line.trimEnd()).filter((line) => line.trim().length > 0).slice(0, maxLines);
+  return lines.map((line) => `  ${line}`).join("\n");
+}
 function activePersonalMemoryUrisFromText(text, user) {
   const userSegment = uriSegment(user);
   const matches = text.matchAll(/viking:\/\/[^\s)]+/g);
@@ -39276,7 +39417,8 @@ function formatMemoryDocument(title, metadata, body) {
     `source_agent_client: ${metadata.sourceAgentClient}`,
     `timestamp: ${metadata.timestamp}`,
     metadata.supersedes ? `supersedes: ${metadata.supersedes}` : void 0,
-    metadata.archivedFrom ? `archived_from: ${metadata.archivedFrom}` : void 0
+    metadata.archivedFrom ? `archived_from: ${metadata.archivedFrom}` : void 0,
+    ...(metadata.references ?? []).map((uri) => `references: ${uri}`)
   ].filter((line) => line !== void 0);
   return [...header, "", body.trim()].join("\n");
 }
@@ -39284,6 +39426,11 @@ function headerValue(header, key) {
   const prefix = `${key}:`;
   return header.split("\n").find((line) => line.startsWith(prefix))?.slice(prefix.length).trim();
 }
+function headerValues(header, key) {
+  const prefix = `${key}:`;
+  const values = header.split("\n").filter((line) => line.startsWith(prefix)).map((line) => line.slice(prefix.length).trim()).filter((value) => value.length > 0);
+  return values.length > 0 ? values : void 0;
+}
 function parseOptionalMemoryKind(value) {
   if (!value) {
     return void 0;
@@ -40040,10 +40187,13 @@ function registerSearchTool(server, config2, name, description) {
         includeArchived: external_exports.boolean().optional().describe("Include archived memories in recall results"),
         threshold: external_exports.number().min(0).max(1).optional().describe(
           "Minimum relevance score 0-1 (default 0.5); lower it (toward 0) to broaden when a recall comes back empty"
+        ),
+        workset: external_exports.string().optional().describe(
+          "Optional named workset (a set of related repos from the seed manifest) to recall across as one working set"
         )
       }
     },
-    async ({ callerCwd, includeArchived, nodeLimit, query, threshold, uri }) => {
+    async ({ callerCwd, includeArchived, nodeLimit, query, threshold, uri, workset }) => {
       const checkedQuery = requiredText(query, name, "query", { query: "unity-ui-ccc latest handoff" });
       if (!checkedQuery.ok) {
         return checkedQuery.error;
@@ -40059,7 +40209,8 @@ function registerSearchTool(server, config2, name, description) {
           pinnedUri: checkedUri.value,
           nodeLimit,
           includeArchived: includeArchived === true,
-          threshold: threshold === void 0 ? void 0 : String(threshold)
+          threshold: threshold === void 0 ? void 0 : String(threshold),
+          workset: workset?.trim() || void 0
         })
       );
     }
@@ -40094,6 +40245,7 @@ async function runRecallTool(config2, params) {
   const project = params.pinnedUri ? void 0 : await inferProjectFromQuery(config2.manifestPath, projectQuery);
   const limitArgs = params.nodeLimit ? ["--node-limit", String(params.nodeLimit)] : [];
   const threshold = params.threshold ?? RECALL_SCORE_THRESHOLD;
+  const explicitWorkset = params.workset ? await requireWorkset(config2.manifestPath, params.workset) : void 0;
   const pinnedArgs = params.pinnedUri ? ["--uri", params.pinnedUri] : [];
   const base = await recallSearchHits(
     config2,
@@ -40113,6 +40265,21 @@ async function runRecallTool(config2, params) {
     passes.push(seeded.hits);
   }
   const sections = [];
+  const workset = params.pinnedUri ? void 0 : explicitWorkset ? explicitWorkset : await inferWorksetFromQuery(config2.manifestPath, projectQuery);
+  if (workset && workset.projects.length > 0) {
+    sections.push(`Workset scope: ${workset.name} (${workset.projects.map((member) => member.name).join(", ")})`);
+    const alreadyScoped = new Set([params.pinnedUri, seededUri].filter((uri) => uri !== void 0));
+    const worksetScopes = worksetScopeUris(config2, workset).filter((uri) => !alreadyScoped.has(uri)).slice(0, MAX_WORKSET_PASSES);
+    for (const scope of worksetScopes) {
+      const worksetPass = await recallSearchHits(
+        config2,
+        ["search", query, "--uri", scope, ...limitArgs],
+        threshold,
+        params.includeArchived
+      );
+      passes.push(worksetPass.hits);
+    }
+  }
   const exactMatches = await collectExactMemoryMatches(config2, query, params.includeArchived, project);
   const { semanticSection, exactTail } = buildRecallSections(passes, exactMatches, params.nodeLimit ?? 12);
   if (semanticSection) {
@@ -40126,6 +40293,10 @@ async function runRecallTool(config2, params) {
   if (exactTail) {
     sections.push(exactTail);
   }
+  const referencedContext = await referencedContextSection(config2, sections.join("\n\n"));
+  if (referencedContext) {
+    sections.push(referencedContext);
+  }
   const hygieneHints = await recallHygieneHintsSection(config2, sections.join("\n\n"));
   if (hygieneHints) {
     sections.push(hygieneHints);
@@ -40171,6 +40342,36 @@ 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;
 }
+var MAX_REFERENCED_CONTEXT = 5;
+var REFERENCED_EXCERPT_LINES = 12;
+async function referencedContextSection(config2, recallText) {
+  const surfacedUris = activePersonalMemoryUrisFromText(recallText, config2.user);
+  if (surfacedUris.length === 0) {
+    return void 0;
+  }
+  const surfaced = await readMemoryRecordsByUri(config2, surfacedUris);
+  const referenced = referencedUrisFromRecords(surfaced, recallText);
+  if (referenced.length === 0) {
+    return void 0;
+  }
+  const capped = referenced.slice(0, MAX_REFERENCED_CONTEXT);
+  const records = await readMemoryRecordsByUri(config2, capped);
+  const byUri = new Map(records.map((record2) => [record2.uri, record2]));
+  const lines = ["Referenced read-only context (one-way pointers from surfaced memories):"];
+  for (const uri of capped) {
+    const record2 = byUri.get(uri);
+    if (record2) {
+      lines.push(`- ${uri}`, referencedContextExcerpt(record2.body, REFERENCED_EXCERPT_LINES));
+    } else {
+      lines.push(`- ${uri} [reference unavailable locally]`);
+    }
+  }
+  if (referenced.length > capped.length) {
+    const omitted = referenced.length - capped.length;
+    lines.push(`- \u2026 ${omitted} more referenced ${omitted === 1 ? "memory" : "memories"} omitted`);
+  }
+  return lines.join("\n");
+}
 async function collectExactMemoryMatches(config2, query, includeArchived, project) {
   const terms = exactRecallTerms(query);
   if (terms.length === 0) {
@@ -40263,6 +40464,9 @@ function registerStoreTool(server, config2, name, description) {
       inputSchema: {
         kind: external_exports.enum(["durable", "handoff", "incident", "preference", "smoke"]).optional().describe("Memory lifecycle kind; durable facts and handoffs are most common"),
         project: external_exports.string().optional().describe("Project/repo namespace, for example threadnote or mobile-native"),
+        references: external_exports.union([external_exports.string(), external_exports.array(external_exports.string())]).optional().describe(
+          "Optional viking:// URI(s) to record as one-way, read-only prior context for this memory. Recall surfaces a short excerpt of each. Stripped from shared copies on publish."
+        ),
         replaceUri: external_exports.string().optional().describe(
           "Optional viking:// memory URI to replace. Shared URIs are updated in place and pushed; personal URIs are forgotten after the replacement is safely stored."
         ),
@@ -40272,7 +40476,7 @@ function registerStoreTool(server, config2, name, description) {
         topic: external_exports.string().optional().describe("Stable topic; active project/topic memories update one file")
       }
     },
-    async ({ kind, project, replaceUri, sourceAgentClient, status, text, topic }) => {
+    async ({ kind, project, references, replaceUri, sourceAgentClient, status, text, topic }) => {
       const checkedText = requiredText(text, name, "text", { text: "Durable engineering note..." });
       if (!checkedText.ok) {
         return checkedText.error;
@@ -40281,9 +40485,14 @@ function registerStoreTool(server, config2, name, description) {
       if (!checkedReplaceUri.ok) {
         return checkedReplaceUri.error;
       }
+      const checkedReferences = optionalVikingUriList(references, name);
+      if (!checkedReferences.ok) {
+        return checkedReferences.error;
+      }
       const metadata = {
         kind: kind ?? "durable",
         project: normalizeOptionalMetadata2(project),
+        references: checkedReferences.value,
         sourceAgentClient: sourceAgentClient ?? "mcp",
         status: status ?? "active",
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -40734,6 +40943,18 @@ function exactMemoryScopes(config2, includeArchived, query, project) {
     userBase: `viking://user/${uriSegment2(config2.user)}/memories`
   });
 }
+var MAX_WORKSET_PASSES = 12;
+function worksetScopeUris(config2, workset) {
+  const scopes = [];
+  for (const member of workset.projects) {
+    scopes.push(`viking://user/${uriSegment2(config2.user)}/memories/durable/projects/${uriSegment2(member.name)}`);
+    const seeded = trimTrailingSlash(member.uri);
+    if (seeded.startsWith("viking://")) {
+      scopes.push(seeded);
+    }
+  }
+  return [...new Set(scopes)];
+}
 function formatMemoryDocument2(title, metadata, body) {
   const header = [
     title,
@@ -40744,7 +40965,8 @@ function formatMemoryDocument2(title, metadata, body) {
     `source_agent_client: ${metadata.sourceAgentClient}`,
     `timestamp: ${metadata.timestamp}`,
     metadata.supersedes ? `supersedes: ${metadata.supersedes}` : void 0,
-    metadata.archivedFrom ? `archived_from: ${metadata.archivedFrom}` : void 0
+    metadata.archivedFrom ? `archived_from: ${metadata.archivedFrom}` : void 0,
+    ...(metadata.references ?? []).map((uri) => `references: ${uri}`)
   ].filter((line) => line !== void 0);
   return [...header, "", body.trim()].join("\n");
 }
@@ -40800,6 +41022,23 @@ function optionalVikingUri(value, toolName) {
     ok: false
   };
 }
+function optionalVikingUriList(value, toolName) {
+  const rawValues = Array.isArray(value) ? value : value === void 0 ? [] : [value];
+  const uris = rawValues.map((uri) => uri.trim()).filter(Boolean);
+  if (uris.length === 0) {
+    return { ok: true, value: void 0 };
+  }
+  const invalid = uris.find((uri) => !uri.startsWith("viking://"));
+  if (invalid) {
+    return {
+      error: argumentError(
+        `Threadnote MCP tool "${toolName}" needs viking:// URI values for "references". Received: ${invalid}`
+      ),
+      ok: false
+    };
+  }
+  return { ok: true, value: [...new Set(uris)] };
+}
 function requiredVikingUriList(value, toolName, exampleUri) {
   const rawValues = Array.isArray(value) ? value : value === void 0 ? [] : [value];
   const uris = rawValues.map((uri) => uri.trim()).filter(Boolean);