threadnote 0.7.4 → 0.7.6

package/dist/threadnote.cjs

@@ -3524,7 +3524,7 @@ var DEFAULT_SEED_PATTERNS = [
 
 // src/hooks.ts
 var import_promises7 = require("node:fs/promises");
-var import_node_path8 = require("node:path");
+var import_node_path9 = require("node:path");
 
 // src/mcp.ts
 var import_node_fs2 = require("node:fs");
@@ -3850,6 +3850,27 @@ async function exists(path) {
     return false;
   }
 }
+async function isExecutable(path) {
+  try {
+    await (0, import_promises.access)(path, import_node_fs.constants.X_OK);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+function suggestedShellRc(shellPath, currentPlatform) {
+  const shell = shellPath ?? "";
+  if (shell.endsWith("/zsh")) {
+    return "~/.zshrc";
+  }
+  if (shell.endsWith("/bash")) {
+    return currentPlatform === "darwin" ? "~/.bash_profile" : "~/.bashrc";
+  }
+  if (shell.endsWith("/fish")) {
+    return "~/.config/fish/config.fish";
+  }
+  return "your shell rc";
+}
 async function isFile(path) {
   try {
     return (await (0, import_promises.stat)(path)).isFile();
@@ -3937,6 +3958,57 @@ function portablePath(path) {
 function getInvocationCwd() {
   return process.env.THREADNOTE_CALLER_CWD ?? process.cwd();
 }
+function recallQueryRequestsWorkspaceContext(query) {
+  const normalized = query.toLowerCase();
+  return /\b(?:this|current)\s+(?:branch|repo|repository|workspace|worktree)\b/.test(normalized);
+}
+async function enrichRecallQueryWithWorkspaceContext(query, options = {}) {
+  return enrichRecallQueryWithWorkspaceTerms(query, options, true);
+}
+async function enrichRecallQueryWithWorkspaceProjectContext(query, options = {}) {
+  return enrichRecallQueryWithWorkspaceTerms(query, options, false);
+}
+async function enrichRecallQueryWithWorkspaceTerms(query, options, includeBranch) {
+  if (!recallQueryRequestsWorkspaceContext(query)) {
+    return query;
+  }
+  const terms = await currentWorkspaceRecallTerms(options, includeBranch);
+  const additions = terms.filter((term) => !query.toLowerCase().includes(term.toLowerCase()));
+  return additions.length > 0 ? `${query} ${additions.join(" ")}` : query;
+}
+async function currentWorkspaceRecallTerms(options, includeBranch) {
+  const cwd = options.cwd ?? (options.includeProcessCwd === false ? void 0 : getInvocationCwd());
+  if (!cwd || !(0, import_node_path.isAbsolute)(cwd)) {
+    return [];
+  }
+  const repoRoot = await gitValue(["rev-parse", "--show-toplevel"], cwd);
+  if (!repoRoot) {
+    return [];
+  }
+  const branch = await gitValue(["branch", "--show-current"], repoRoot);
+  const parent = (0, import_node_path.dirname)(repoRoot);
+  return uniqueUsefulWorkspaceTerms([
+    { source: "branch", value: includeBranch ? branch : void 0 },
+    { source: "path", value: (0, import_node_path.basename)(repoRoot) },
+    { source: "path", value: parent === (0, import_node_os.homedir)() ? void 0 : (0, import_node_path.basename)(parent) }
+  ]);
+}
+function uniqueUsefulWorkspaceTerms(values) {
+  const ignored = /* @__PURE__ */ new Set(["repos", "repositories", "workspaces", "worktrees"]);
+  const seen = /* @__PURE__ */ new Set();
+  const terms = [];
+  for (const { source, value } of values) {
+    const term = value?.trim();
+    const normalized = term?.toLowerCase();
+    const tooShort = source === "branch" ? false : (term?.length ?? 0) < 4;
+    if (!term || !normalized || tooShort || ignored.has(normalized) || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    terms.push(term);
+  }
+  return terms;
+}
 function toPosixPath(path) {
   return path.split(import_node_path.sep).join("/");
 }
@@ -3960,19 +4032,29 @@ function exactRecallTerms(query) {
     "branch",
     "case",
     "current",
+    "durable",
     "find",
+    "feature",
+    "features",
     "handoff",
     "issue",
     "issues",
+    "knowledge",
     "latest",
     "memory",
     "memories",
+    "project",
     "recall",
+    "repo",
+    "repository",
     "related",
     "search",
-    "the",
+    "stored",
     "this",
-    "with"
+    "the",
+    "with",
+    "workspace",
+    "worktree"
   ]);
   const seen = /* @__PURE__ */ new Set();
   const terms = [];
@@ -4520,7 +4602,7 @@ function existsSyncDirectory(path) {
 
 // src/memory.ts
 var import_promises5 = require("node:fs/promises");
-var import_node_path5 = require("node:path");
+var import_node_path6 = require("node:path");
 
 // src/manifest.ts
 var import_promises3 = require("node:fs/promises");
@@ -7218,10 +7300,445 @@ function readStringArray(object, key) {
   return value;
 }
 
+// src/memory_hygiene.ts
+var import_node_path3 = require("node:path");
+var HYGIENE_SOURCES_HEADING = "## Threadnote Hygiene Sources";
+var STALE_HANDOFF_AGE_MS = 14 * 24 * 60 * 60 * 1e3;
+function parseMemoryDocument(uri, content) {
+  const trimmed = content.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  const separatorIndex = trimmed.indexOf("\n\n");
+  const header = separatorIndex === -1 ? trimmed : trimmed.slice(0, separatorIndex);
+  const body = separatorIndex === -1 ? "" : trimmed.slice(separatorIndex + 2).trim();
+  const firstLine2 = header.split("\n")[0]?.trim();
+  if (firstLine2 !== "MEMORY" && firstLine2 !== "HANDOFF") {
+    return void 0;
+  }
+  const kind = parseOptionalMemoryKind(headerValue(header, "kind")) ?? (firstLine2 === "HANDOFF" ? "handoff" : void 0);
+  const status = parseOptionalMemoryStatus(headerValue(header, "status")) ?? "active";
+  if (!kind) {
+    return void 0;
+  }
+  return {
+    body,
+    content: trimmed,
+    headerTitle: firstLine2,
+    metadata: {
+      archivedFrom: headerValue(header, "archived_from"),
+      kind,
+      project: normalizeOptionalMetadata(headerValue(header, "project") ?? headerValue(header, "repo")),
+      sourceAgentClient: headerValue(header, "source_agent_client") ?? "unknown",
+      status,
+      supersedes: headerValue(header, "supersedes"),
+      timestamp: headerValue(header, "timestamp") ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+      topic: normalizeOptionalMetadata(headerValue(header, "topic"))
+    },
+    uri
+  };
+}
+function buildCompactPlan(records, options) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const groupedRecords = records.map((record) => groupableRecord(record)).filter((item) => item !== void 0).filter((item) => item.project === options.project).filter((item) => options.topic === void 0 || item.topic === options.topic).filter((item) => options.kind === void 0 || item.record.metadata.kind === options.kind);
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of groupedRecords) {
+    groups.set(item.groupKey, [...groups.get(item.groupKey) ?? [], item]);
+  }
+  const keepUpdates = [];
+  const archives = [];
+  const forgets = [];
+  const manualReview = [];
+  for (const group of [...groups.values()].sort(compareGroupedRecordLists)) {
+    const recordsInGroup = group.map((item) => item.record);
+    const kind = recordsInGroup[0]?.metadata.kind;
+    const topic = group[0]?.topic;
+    const project = group[0]?.project;
+    if (!kind || !project || !isCompactableKind(kind)) {
+      continue;
+    }
+    const duplicateGroups = groupBy(recordsInGroup, (record) => comparableMemoryBody(record.body));
+    const duplicateForgetUris = /* @__PURE__ */ new Set();
+    const distinctBodyCount = duplicateGroups.size;
+    for (const duplicateGroup of duplicateGroups.values()) {
+      if (duplicateGroup.length < 2) {
+        continue;
+      }
+      const duplicateKeep = preferredKeepRecord(duplicateGroup, topic);
+      for (const duplicate of sortedNewestFirst(duplicateGroup).filter((record) => record.uri !== duplicateKeep.uri)) {
+        duplicateForgetUris.add(duplicate.uri);
+        forgets.push({ reason: `exact duplicate of ${duplicateKeep.uri}`, uri: duplicate.uri });
+      }
+      if (distinctBodyCount === 1 || kind !== "handoff") {
+        keepUpdates.push({
+          content: memoryContentWithHygieneSources(
+            duplicateKeep,
+            duplicateGroup.map((record) => record.uri)
+          ),
+          reason: "keep exact duplicate group with source URIs",
+          sourceUris: duplicateGroup.map((record) => record.uri),
+          uri: duplicateKeep.uri
+        });
+      }
+    }
+    const remainingRecords = recordsInGroup.filter((record) => !duplicateForgetUris.has(record.uri));
+    if (recordsInGroup.length > 1 && distinctBodyCount === 1) {
+      continue;
+    }
+    if (remainingRecords.length === 0) {
+      continue;
+    }
+    if (remainingRecords.length === 1) {
+      const [record] = remainingRecords;
+      if (!record) {
+        continue;
+      }
+      if (record.metadata.supersedes === record.uri) {
+        keepUpdates.push({
+          content: memoryContentWithHygieneSources(record, [record.uri]),
+          reason: "strip self-supersedes header",
+          sourceUris: [record.uri],
+          uri: record.uri
+        });
+      }
+      if (isStaleLookingHandoff(record, now)) {
+        manualReview.push({ reason: "stale-looking active handoff", uri: record.uri });
+      }
+      continue;
+    }
+    if (kind === "handoff") {
+      const keep = preferredKeepRecord(remainingRecords, topic);
+      const sourceUris = recordsInGroup.map((record) => record.uri);
+      keepUpdates.push({
+        content: memoryContentWithHygieneSources(keep, sourceUris),
+        reason: "keep latest handoff and preserve source URIs",
+        sourceUris,
+        uri: keep.uri
+      });
+      for (const record of sortedNewestFirst(remainingRecords).filter((item) => item.uri !== keep.uri)) {
+        archives.push({
+          kind,
+          project,
+          reason: `older handoff for ${project}/${topic ?? "unknown"}`,
+          topic,
+          uri: record.uri
+        });
+      }
+      continue;
+    }
+    for (const record of sortedNewestFirst(remainingRecords)) {
+      manualReview.push({ reason: `non-exact ${kind} memory in overlapping group`, uri: record.uri });
+    }
+  }
+  return {
+    archives: dedupeByUri(archives),
+    forgets: dedupeByUri(forgets),
+    keepUpdates: dedupeByUri(keepUpdates),
+    manualReview: dedupeByUri(manualReview),
+    options,
+    recordsScanned: groupedRecords.length
+  };
+}
+function memoryContentWithHygieneSources(record, sourceUris) {
+  const body = stripHygieneSources(record.body);
+  const uniqueSourceUris = [...new Set(sourceUris)].sort();
+  const metadata = {
+    ...record.metadata,
+    supersedes: record.metadata.supersedes === record.uri ? void 0 : record.metadata.supersedes
+  };
+  return formatMemoryDocument(
+    record.headerTitle,
+    metadata,
+    [body, "", HYGIENE_SOURCES_HEADING, "", ...uniqueSourceUris.map((uri) => `- ${uri}`)].join("\n")
+  );
+}
+function formatCompactPlan(plan, options) {
+  const scope = [
+    `project ${plan.options.project}`,
+    plan.options.topic ? `topic ${plan.options.topic}` : void 0,
+    plan.options.kind ? `kind ${plan.options.kind}` : void 0
+  ].filter((item) => item !== void 0).join(", ");
+  const lines = [
+    `${options.apply ? "Applying" : "Dry-run"} memory hygiene plan for ${scope}`,
+    `Records scanned: ${plan.recordsScanned}`,
+    "",
+    formatPlanSection(
+      "Keep/update",
+      plan.keepUpdates.map((action) => `${action.uri} (${action.reason}; sources: ${action.sourceUris.length})`)
+    ),
+    formatPlanSection(
+      "Archive old handoffs",
+      plan.archives.map((action) => `${action.uri} (${action.reason})`)
+    ),
+    formatPlanSection(
+      "Forget exact duplicates",
+      plan.forgets.map((action) => `${action.uri} (${action.reason})`)
+    ),
+    formatPlanSection(
+      "Manual review",
+      plan.manualReview.map((item) => `${item.uri} (${item.reason})`)
+    )
+  ];
+  if (!options.apply) {
+    lines.push("", "No changes made. Re-run with --apply to execute this plan.");
+  }
+  return lines.join("\n");
+}
+function recallHygieneNudges(text, options) {
+  const activeUris = activePersonalMemoryUrisFromText(text, options.user);
+  const nudges = [];
+  const returnedUriSet = new Set(activeUris);
+  const returnedRecords = options.records?.filter((record) => returnedUriSet.has(record.uri)).map((record) => groupableRecord(record)) ?? [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of returnedRecords) {
+    if (!item) {
+      continue;
+    }
+    groups.set(item.groupKey, [...groups.get(item.groupKey) ?? [], item]);
+  }
+  for (const group of [...groups.values()].sort(compareGroupedRecordLists)) {
+    if (group.length < 3) {
+      continue;
+    }
+    const first = group[0];
+    if (!first || !isCompactableKind(first.record.metadata.kind)) {
+      continue;
+    }
+    const topic = first.topic;
+    if (!topic) {
+      continue;
+    }
+    nudges.push(
+      `${group.length} active ${memoryKindPlural(first.record.metadata.kind)} look overlapping for ${first.project}/${topic}; run compact_context({"project":"${first.project}","topic":"${topic}","dryRun":true}).`
+    );
+  }
+  const projectCounts = /* @__PURE__ */ new Map();
+  for (const uri of activeUris) {
+    const parsed = parsePersonalMemoryUri(uri, options.user);
+    if (!parsed || parsed.kind !== "handoff" || parsed.status !== "active") {
+      continue;
+    }
+    projectCounts.set(parsed.project, (projectCounts.get(parsed.project) ?? 0) + 1);
+  }
+  for (const [project, count] of [...projectCounts.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    if (count < 10) {
+      continue;
+    }
+    nudges.push(
+      `Many active handoffs surfaced for ${project}; run compact_context({"project":"${project}","dryRun":true}).`
+    );
+  }
+  return [...new Set(nudges)];
+}
+function activePersonalMemoryUrisFromText(text, user) {
+  const userSegment = uriSegment(user);
+  const matches = text.matchAll(/viking:\/\/[^\s)]+/g);
+  const uris = [];
+  for (const match of matches) {
+    const uri = match[0]?.replace(/[.,;:]+$/g, "");
+    if (!uri || !parsePersonalMemoryUri(uri, userSegment)) {
+      continue;
+    }
+    uris.push(uri);
+  }
+  return [...new Set(uris)];
+}
+function parsePersonalMemoryUri(uri, user) {
+  const prefix = `viking://user/${uriSegment(user)}/memories/`;
+  if (!uri.startsWith(prefix) || uri.includes("/shared/")) {
+    return void 0;
+  }
+  const rest = uri.slice(prefix.length);
+  const parts = rest.split("/").filter(Boolean);
+  if (parts.length < 4) {
+    return void 0;
+  }
+  if (parts[0] === "handoffs" && parts[1] === "active" && parts[2] && parts[3]?.endsWith(".md")) {
+    return { kind: "handoff", project: parts[2], status: "active", topic: parts[3].replace(/\.md$/, "") };
+  }
+  if (parts[0] === "durable" && parts[1] === "projects" && parts[2] && parts[3]?.endsWith(".md")) {
+    return { kind: "durable", project: parts[2], status: "active", topic: parts[3].replace(/\.md$/, "") };
+  }
+  if (parts[0] === "incidents" && parts[1] === "active" && parts[2] && parts[3]?.endsWith(".md")) {
+    return { kind: "incident", project: parts[2], status: "active", topic: parts[3].replace(/\.md$/, "") };
+  }
+  return void 0;
+}
+function handoffTopicForBranch(branch, options) {
+  const topic = normalizeOptionalMetadata(options.topic);
+  if (options.timestamped === true) {
+    if (topic) {
+      throw new Error("Cannot combine --timestamped with --topic.");
+    }
+    return void 0;
+  }
+  return topic ?? normalizeOptionalMetadata(branch) ?? "current";
+}
+function groupableRecord(record) {
+  if (record.metadata.status !== "active" || !isCompactableKind(record.metadata.kind)) {
+    return void 0;
+  }
+  const project = normalizeOptionalMetadata(record.metadata.project) ?? parseProjectFromUri(record.uri);
+  if (!project) {
+    return void 0;
+  }
+  const topic = topicForRecord(record);
+  const groupKey = [record.metadata.kind, project, topic ?? record.uri].join("\0");
+  return { groupKey, project, record, topic };
+}
+function topicForRecord(record) {
+  return normalizeOptionalMetadata(record.metadata.topic) ?? normalizeOptionalMetadata(branchFromBody(record.body)) ?? topicFromUri(record.uri);
+}
+function branchFromBody(body) {
+  const branch = /^branch:\s*(.+)$/m.exec(body)?.[1]?.trim();
+  return branch?.split(/\s+/)[0]?.replace(/[.,;:]+$/g, "");
+}
+function topicFromUri(uri) {
+  const name = (0, import_node_path3.basename)(uri).replace(/\.md$/, "");
+  return name.startsWith("threadnote-") ? void 0 : name;
+}
+function parseProjectFromUri(uri) {
+  const parts = uri.split("/memories/")[1]?.split("/").filter(Boolean) ?? [];
+  if ((parts[0] === "handoffs" || parts[0] === "incidents") && parts[1] === "active") {
+    return parts[2];
+  }
+  if (parts[0] === "durable" && parts[1] === "projects") {
+    return parts[2];
+  }
+  return void 0;
+}
+function comparableMemoryBody(body) {
+  return stripHygieneSources(body).trim().replace(/\s+/g, " ");
+}
+function stripHygieneSources(body) {
+  const index = body.indexOf(`
+${HYGIENE_SOURCES_HEADING}`);
+  if (index !== -1) {
+    return body.slice(0, index).trim();
+  }
+  return body.startsWith(HYGIENE_SOURCES_HEADING) ? "" : body.trim();
+}
+function preferredKeepRecord(records, topic) {
+  const stableRecords = records.filter((record) => isStableRecord(record, topic));
+  return sortedNewestFirst(stableRecords.length > 0 ? stableRecords : records)[0] ?? records[0];
+}
+function isStableRecord(record, topic) {
+  const recordTopic = topic ?? topicForRecord(record);
+  return recordTopic !== void 0 && (0, import_node_path3.basename)(record.uri) === `${uriSegment(recordTopic)}.md`;
+}
+function sortedNewestFirst(records) {
+  return [...records].sort((left, right) => {
+    const timestampDiff = timestampMs(right) - timestampMs(left);
+    return timestampDiff === 0 ? left.uri.localeCompare(right.uri) : timestampDiff;
+  });
+}
+function timestampMs(record) {
+  const parsed = Date.parse(record.metadata.timestamp);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function isStaleLookingHandoff(record, now) {
+  if (record.metadata.kind !== "handoff") {
+    return false;
+  }
+  if (now.getTime() - timestampMs(record) < STALE_HANDOFF_AGE_MS) {
+    return false;
+  }
+  return /\b(?:PR|pull request)\s+(?:OPEN|open|is open)|awaiting review|waiting for review|next steps?:\s*address PR review/i.test(
+    record.body
+  );
+}
+function groupBy(values, keyForValue) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const key = keyForValue(value);
+    groups.set(key, [...groups.get(key) ?? [], value]);
+  }
+  return groups;
+}
+function compareGroupedRecordLists(left, right) {
+  return (left[0]?.groupKey ?? "").localeCompare(right[0]?.groupKey ?? "");
+}
+function dedupeByUri(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of items) {
+    if (seen.has(item.uri)) {
+      continue;
+    }
+    seen.add(item.uri);
+    result.push(item);
+  }
+  return result;
+}
+function formatMemoryDocument(title, metadata, body) {
+  const header = [
+    title,
+    `kind: ${metadata.kind}`,
+    `status: ${metadata.status}`,
+    metadata.project ? `project: ${metadata.project}` : void 0,
+    metadata.topic ? `topic: ${metadata.topic}` : void 0,
+    `source_agent_client: ${metadata.sourceAgentClient}`,
+    `timestamp: ${metadata.timestamp}`,
+    metadata.supersedes ? `supersedes: ${metadata.supersedes}` : void 0,
+    metadata.archivedFrom ? `archived_from: ${metadata.archivedFrom}` : void 0
+  ].filter((line) => line !== void 0);
+  return [...header, "", body.trim()].join("\n");
+}
+function headerValue(header, key) {
+  const prefix = `${key}:`;
+  return header.split("\n").find((line) => line.startsWith(prefix))?.slice(prefix.length).trim();
+}
+function parseOptionalMemoryKind(value) {
+  if (!value) {
+    return void 0;
+  }
+  if (["durable", "handoff", "incident", "preference", "smoke"].includes(value)) {
+    return value;
+  }
+  return void 0;
+}
+function parseOptionalMemoryStatus(value) {
+  if (!value) {
+    return void 0;
+  }
+  if (["active", "archived", "superseded"].includes(value)) {
+    return value;
+  }
+  return void 0;
+}
+function normalizeOptionalMetadata(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+}
+function isCompactableKind(kind) {
+  return kind === "durable" || kind === "handoff" || kind === "incident";
+}
+function memoryKindPlural(kind) {
+  switch (kind) {
+    case "handoff":
+      return "handoffs";
+    case "incident":
+      return "incidents";
+    case "durable":
+      return "durable memories";
+    case "preference":
+      return "preferences";
+    case "smoke":
+      return "smoke memories";
+  }
+}
+function formatPlanSection(title, lines) {
+  if (lines.length === 0) {
+    return `${title}:
+- none`;
+  }
+  return [`${title}:`, ...lines.map((line) => `- ${line}`)].join("\n");
+}
+
 // src/runtime.ts
 var import_node_fs3 = require("node:fs");
 var import_node_os3 = require("node:os");
-var import_node_path3 = require("node:path");
+var import_node_path4 = require("node:path");
 function getRuntimeConfig(program2, manifestOverride) {
   const options = program2.opts();
   const threadnoteHome = expandPath(options.home ?? process.env.THREADNOTE_HOME ?? "~/.openviking");
@@ -7240,32 +7757,36 @@ function getRuntimeConfig(program2, manifestOverride) {
   };
 }
 function defaultManifestPath(agentContextHome) {
-  const userManifest = (0, import_node_path3.join)(agentContextHome, USER_MANIFEST_NAME);
+  const userManifest = (0, import_node_path4.join)(agentContextHome, USER_MANIFEST_NAME);
   return (0, import_node_fs3.existsSync)(userManifest) ? userManifest : builtInExampleManifestPath();
 }
 function builtInExampleManifestPath() {
-  return (0, import_node_path3.join)(toolRoot(), "config", "seed-manifest.example.yaml");
+  return (0, import_node_path4.join)(toolRoot(), "config", "seed-manifest.example.yaml");
 }
 function openVikingHealthUrl(config) {
   return `http://${config.host}:${config.port}/health`;
 }
 function openVikingLogPath(config) {
-  return (0, import_node_path3.join)(config.agentContextHome, "logs", "server.log");
+  return (0, import_node_path4.join)(config.agentContextHome, "logs", "server.log");
 }
 function openVikingServerArgs(config) {
-  return ["--config", (0, import_node_path3.join)(config.agentContextHome, "ov.conf"), "--host", config.host, "--port", String(config.port)];
+  return ["--config", (0, import_node_path4.join)(config.agentContextHome, "ov.conf"), "--host", config.host, "--port", String(config.port)];
 }
 function withIdentity(config, args) {
   return [...args, "--account", config.account, "--user", config.user, "--agent-id", config.agentId];
 }
-function renderTemplate(template, config) {
-  return template.replaceAll("{{THREADNOTE_HOME}}", config.agentContextHome).replaceAll("{{OPENVIKING_ACCOUNT}}", config.account).replaceAll("{{OPENVIKING_AGENT_ID}}", config.agentId).replaceAll("{{OPENVIKING_HOST}}", config.host).replaceAll("{{OPENVIKING_PORT}}", String(config.port)).replaceAll("{{OPENVIKING_USER}}", config.user);
+function renderTemplate(template, config, extras = {}) {
+  let rendered = template.replaceAll("{{THREADNOTE_HOME}}", config.agentContextHome).replaceAll("{{OPENVIKING_ACCOUNT}}", config.account).replaceAll("{{OPENVIKING_AGENT_ID}}", config.agentId).replaceAll("{{OPENVIKING_HOST}}", config.host).replaceAll("{{OPENVIKING_PORT}}", String(config.port)).replaceAll("{{OPENVIKING_USER}}", config.user);
+  for (const [key, value] of Object.entries(extras)) {
+    rendered = rendered.replaceAll(`{{${key}}}`, () => value);
+  }
+  return rendered;
 }
 
 // src/share.ts
 var import_promises4 = require("node:fs/promises");
 var import_node_os4 = require("node:os");
-var import_node_path4 = require("node:path");
+var import_node_path5 = require("node:path");
 var TEAMS_FILE_VERSION = 1;
 var SHARED_SEGMENT = "shared";
 var SHAREABLE_MEMORY_KIND_DIRS = ["durable"];
@@ -7334,8 +7855,8 @@ async function runShareInit(config, remoteUrl, options) {
   if (await exists(gitdir)) {
     throw new Error(`Gitdir already exists at ${gitdir}; remove it or pick a different team name.`);
   }
-  await ensureDirectory((0, import_node_path4.dirname)(worktree), dryRun);
-  await ensureDirectory((0, import_node_path4.dirname)(gitdir), dryRun);
+  await ensureDirectory((0, import_node_path5.dirname)(worktree), dryRun);
+  await ensureDirectory((0, import_node_path5.dirname)(gitdir), dryRun);
   const git = await requiredExecutable("git");
   await maybeRun(dryRun, git, ["clone", `--separate-git-dir=${gitdir}`, "--", remoteUrl, worktree]);
   const newConfig = {
@@ -7366,7 +7887,7 @@ async function runShareInit(config, remoteUrl, options) {
 var SHARED_GITIGNORE_PATTERNS = ["**/.abstract.md", "**/.overview.md"];
 var SHARED_GITIGNORE_HEADER = "# Threadnote: ignore OpenViking-generated directory summaries.";
 async function ensureSharedGitignore(worktree, git, push) {
-  const gitignorePath = (0, import_node_path4.join)(worktree, ".gitignore");
+  const gitignorePath = (0, import_node_path5.join)(worktree, ".gitignore");
   const existing = await readFileIfExists(gitignorePath) ?? "";
   const lines = existing.split("\n").map((line) => line.trim());
   const missingPatterns = SHARED_GITIGNORE_PATTERNS.filter((pattern) => !lines.includes(pattern));
@@ -7467,7 +7988,7 @@ function autoShareState(config) {
   return state;
 }
 function pendingReindexesPath(config) {
-  return (0, import_node_path4.join)(config.agentContextHome, "share", "auto-sync-pending-reindexes.json");
+  return (0, import_node_path5.join)(config.agentContextHome, "share", "auto-sync-pending-reindexes.json");
 }
 async function loadPendingReindexes(config, state) {
   const raw = await readFileIfExists(pendingReindexesPath(config));
@@ -7511,7 +8032,7 @@ async function writePendingReindexes(config, state) {
     teams: Object.fromEntries(state.pendingReindexes),
     version: 1
   };
-  await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(path), { recursive: true });
+  await (0, import_promises4.mkdir)((0, import_node_path5.dirname)(path), { recursive: true });
   const tempPath = `${path}.${process.pid}.tmp`;
   await (0, import_promises4.writeFile)(tempPath, `${JSON.stringify(contents, void 0, 2)}
 `, { encoding: "utf8", mode: 384 });
@@ -7604,7 +8125,7 @@ async function runShareSync(config, options) {
   if (dryRun) {
     console.log(`Would run: ${formatShellCommand(git, ["-C", worktree, "pull", "--rebase", DEFAULT_GIT_REMOTE_NAME])}`);
   } else if (pullResult && pullResult.exitCode !== 0) {
-    if (await exists((0, import_node_path4.join)(team.config.gitdir, "rebase-merge")) || await exists((0, import_node_path4.join)(team.config.gitdir, "rebase-apply"))) {
+    if (await exists((0, import_node_path5.join)(team.config.gitdir, "rebase-merge")) || await exists((0, import_node_path5.join)(team.config.gitdir, "rebase-apply"))) {
       throw new Error(
         `git pull --rebase reported conflicts in ${worktree}. The worktree is in a rebase-in-progress state.
 Resolve the conflicts in-place, run \`git -C ${worktree} rebase --continue\` (or --abort), then re-run \`threadnote share sync\`.`
@@ -7659,7 +8180,7 @@ async function runShareSyncQuiet(config, state, options) {
   const beforeRev = await gitOutput(worktree, ["rev-parse", "HEAD"], false);
   const pullResult = await runCommand(git, ["-C", worktree, "rebase", "@{u}"], { allowFailure: true });
   if (pullResult.exitCode !== 0) {
-    if (await exists((0, import_node_path4.join)(team.config.gitdir, "rebase-merge")) || await exists((0, import_node_path4.join)(team.config.gitdir, "rebase-apply"))) {
+    if (await exists((0, import_node_path5.join)(team.config.gitdir, "rebase-merge")) || await exists((0, import_node_path5.join)(team.config.gitdir, "rebase-apply"))) {
       throw new Error(
         `Automatic share sync hit git conflicts in ${worktree}. Resolve them in-place, run \`git -C ${worktree} rebase --continue\` (or --abort), then rerun recall/read.`
       );
@@ -7833,10 +8354,10 @@ function normalizeTeamName(input2) {
   return candidate;
 }
 function teamsFilePath(config) {
-  return (0, import_node_path4.join)(config.agentContextHome, "share", "teams.json");
+  return (0, import_node_path5.join)(config.agentContextHome, "share", "teams.json");
 }
 function teamWorktreePath(config, team) {
-  return (0, import_node_path4.join)(
+  return (0, import_node_path5.join)(
     config.agentContextHome,
     "data",
     "viking",
@@ -7849,7 +8370,7 @@ function teamWorktreePath(config, team) {
   );
 }
 function teamGitdirPath(config, team) {
-  return (0, import_node_path4.join)(config.agentContextHome, "share", "teams", `${team}.gitdir`);
+  return (0, import_node_path5.join)(config.agentContextHome, "share", "teams", `${team}.gitdir`);
 }
 async function readTeamsFile(config) {
   const path = teamsFilePath(config);
@@ -7892,7 +8413,7 @@ async function readTeamsFile(config) {
 }
 async function writeTeamsFile(config, contents) {
   const path = teamsFilePath(config);
-  await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(path), { recursive: true });
+  await (0, import_promises4.mkdir)((0, import_node_path5.dirname)(path), { recursive: true });
   const serializable = {
     defaultTeam: contents.defaultTeam,
     teams: contents.teams,
@@ -7961,7 +8482,7 @@ async function walkMemoryFiles(root) {
       if (entry.name === ".git") {
         continue;
       }
-      const full = (0, import_node_path4.join)(path, entry.name);
+      const full = (0, import_node_path5.join)(path, entry.name);
       if (entry.isDirectory()) {
         if (depth === 0 && !SHAREABLE_MEMORY_KIND_DIRS.includes(entry.name)) {
           continue;
@@ -7985,7 +8506,7 @@ async function walkMemoryFiles(root) {
   return out;
 }
 function workfileToVikingUri(config, team, filePath) {
-  const rel = (0, import_node_path4.relative)(team.worktree, filePath).split(import_node_path4.sep).join("/");
+  const rel = (0, import_node_path5.relative)(team.worktree, filePath).split(import_node_path5.sep).join("/");
   return `viking://user/${uriSegment(config.user)}/memories/${SHARED_SEGMENT}/${team.name}/${rel}`;
 }
 function isInSharedNamespace(config, uri) {
@@ -8105,8 +8626,8 @@ async function writeMemoryFile(config, ov, uri, content, initialMode, dryRun, op
     }
     return;
   }
-  const stagingDir = await (0, import_promises4.mkdtemp)((0, import_node_path4.join)((0, import_node_os4.tmpdir)(), "threadnote-share-"));
-  const tempPath = (0, import_node_path4.join)(stagingDir, "body.txt");
+  const stagingDir = await (0, import_promises4.mkdtemp)((0, import_node_path5.join)((0, import_node_os4.tmpdir)(), "threadnote-share-"));
+  const tempPath = (0, import_node_path5.join)(stagingDir, "body.txt");
   try {
     await (0, import_promises4.writeFile)(tempPath, content, { encoding: "utf8", mode: 384 });
     await writeOvFileWithRetry(config, ov, uri, tempPath, initialMode, options);
@@ -8228,7 +8749,7 @@ async function bestEffortRemoveWorktreeFile(rollbackUri, worktree, label) {
   if (!relative3) {
     return;
   }
-  await (0, import_promises4.rm)((0, import_node_path4.join)(worktree, relative3), { force: true });
+  await (0, import_promises4.rm)((0, import_node_path5.join)(worktree, relative3), { force: true });
 }
 async function removeMemoryUri(config, ov, uri, dryRun, options = {}) {
   const args = withIdentity(config, ["rm", uri]);
@@ -8292,8 +8813,8 @@ async function listChangedFiles(worktree, beforeRev, afterRev) {
       const oldRel = entries[index + 1];
       const newRel = entries[index + 2];
       if (oldRel && newRel) {
-        changes.push({ path: (0, import_node_path4.join)(worktree, oldRel), relativePath: oldRel, status: "removed" });
-        changes.push({ path: (0, import_node_path4.join)(worktree, newRel), relativePath: newRel, status: "added" });
+        changes.push({ path: (0, import_node_path5.join)(worktree, oldRel), relativePath: oldRel, status: "removed" });
+        changes.push({ path: (0, import_node_path5.join)(worktree, newRel), relativePath: newRel, status: "added" });
       }
       index += 3;
       continue;
@@ -8301,7 +8822,7 @@ async function listChangedFiles(worktree, beforeRev, afterRev) {
     const rel = entries[index + 1];
     if (rel) {
       const status = head === "A" ? "added" : head === "D" ? "removed" : "modified";
-      changes.push({ path: (0, import_node_path4.join)(worktree, rel), relativePath: rel, status });
+      changes.push({ path: (0, import_node_path5.join)(worktree, rel), relativePath: rel, status });
     }
     index += 2;
   }
@@ -8385,6 +8906,12 @@ function parseMemoryStatus(value) {
   }
   throw new Error(`Unsupported memory status "${value}". Expected active, archived, or superseded.`);
 }
+function parseCompactKind(value) {
+  if (["durable", "handoff", "incident"].includes(value)) {
+    return value;
+  }
+  throw new Error(`Unsupported compact kind "${value}". Expected durable, handoff, or incident.`);
+}
 async function runRemember(config, options) {
   const text = await getInputText(options.text, options.stdin === true);
   if (!text.trim()) {
@@ -8392,11 +8919,11 @@ async function runRemember(config, options) {
   }
   const metadata = {
     kind: options.kind ?? "durable",
-    project: normalizeOptionalMetadata(options.project),
+    project: normalizeOptionalMetadata2(options.project),
     sourceAgentClient: options.sourceAgentClient ?? "codex",
     status: options.status ?? "active",
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    topic: normalizeOptionalMetadata(options.topic)
+    topic: normalizeOptionalMetadata2(options.topic)
   };
   await storeMemory(config, {
     bodyText: text.trim(),
@@ -8417,7 +8944,7 @@ async function runMigrateMemories(config, options) {
   const candidates = await legacyMemoryCandidates(config, sourceAccounts);
   const existingHashes = await existingDurableMemoryHashes(config);
   const ov = await openVikingCliForMode(dryRun);
-  const migrationPath = (0, import_node_path5.join)(config.agentContextHome, "legacy-memory-migration.txt");
+  const migrationPath = (0, import_node_path6.join)(config.agentContextHome, "legacy-memory-migration.txt");
   let duplicateCount = 0;
   let migratedCount = 0;
   let sensitiveCount = 0;
@@ -8480,7 +9007,7 @@ async function runMigrateLifecycle(config, options) {
   const limit = options.limit ? parsePositiveInteger(options.limit, "lifecycle migration limit") : void 0;
   const ov = await openVikingCliForMode(dryRun);
   const candidates = await legacyLifecycleHandoffCandidates(config);
-  const migrationPath = (0, import_node_path5.join)(config.agentContextHome, "lifecycle-memory-migration.txt");
+  const migrationPath = (0, import_node_path6.join)(config.agentContextHome, "lifecycle-memory-migration.txt");
   let existingCount = 0;
   let migratedCount = 0;
   let skippedCount = 0;
@@ -8490,7 +9017,7 @@ async function runMigrateLifecycle(config, options) {
         break;
       }
       const destinationUri = lifecycleMigrationUri(config, candidate.metadata, sha256(candidate.original.trim()));
-      const migratedMemory = formatMemoryDocument(
+      const migratedMemory = formatMemoryDocument2(
         "HANDOFF",
         candidate.metadata,
         ["Migrated legacy handoff from the historical events trail.", "", candidate.original.trim()].join("\n")
@@ -8536,8 +9063,10 @@ async function runRecall(config, options) {
     await syncSharedReposAndLog(config);
   }
   const ov = await openVikingCliForMode(options.dryRun === true);
-  const inferredUri = options.uri ?? (options.inferScope === false ? void 0 : await inferRecallUri(config, options.query));
-  const args = ["search", options.query];
+  const query = await enrichRecallQueryWithWorkspaceContext(options.query);
+  const projectQuery = await enrichRecallQueryWithWorkspaceProjectContext(options.query);
+  const inferredUri = options.uri ?? (options.inferScope === false ? void 0 : await inferRecallUri(config, projectQuery));
+  const args = ["search", query];
   if (inferredUri) {
     args.push("--uri", inferredUri);
     console.log(`Recall scope: ${inferredUri}`);
@@ -8545,24 +9074,41 @@ async function runRecall(config, options) {
   if (options.nodeLimit) {
     args.push("--node-limit", String(parsePositiveInteger(options.nodeLimit, "node limit")));
   }
-  await maybeRun(options.dryRun === true, ov, withIdentity(config, args));
-  await augmentRecallWithSeededResources(config, ov, options, inferredUri);
-  await printExactMemoryMatches(config, ov, options.query, {
+  const recallOutputs = [];
+  const baseResult = await maybeRun(options.dryRun === true, ov, withIdentity(config, args));
+  if (baseResult) {
+    recallOutputs.push([baseResult.stdout.trim(), baseResult.stderr.trim()].filter(Boolean).join("\n"));
+  }
+  const seededOutput = await augmentRecallWithSeededResources(
+    config,
+    ov,
+    { ...options, query },
+    inferredUri,
+    projectQuery
+  );
+  if (seededOutput) {
+    recallOutputs.push(seededOutput);
+  }
+  const exactOutput = await printExactMemoryMatches(config, ov, query, {
     dryRun: options.dryRun === true,
     includeArchived: options.includeArchived === true
   });
+  if (exactOutput) {
+    recallOutputs.push(exactOutput);
+  }
+  await printRecallHygieneNudges(config, recallOutputs.join("\n"));
 }
-async function augmentRecallWithSeededResources(config, ov, options, inferredUri) {
+async function augmentRecallWithSeededResources(config, ov, options, inferredUri, projectQuery = options.query) {
   if (options.uri || options.inferScope === false) {
-    return;
+    return void 0;
   }
-  const project = await inferProjectFromQuery(config.manifestPath, options.query);
+  const project = await inferProjectFromQuery(config.manifestPath, projectQuery);
   if (!project) {
-    return;
+    return void 0;
   }
   const projectResourceUri = trimTrailingSlash(project.uri);
   if (!projectResourceUri.startsWith("viking://") || projectResourceUri === inferredUri) {
-    return;
+    return void 0;
   }
   const args = ["search", options.query, "--uri", projectResourceUri];
   if (options.nodeLimit) {
@@ -8570,7 +9116,8 @@ async function augmentRecallWithSeededResources(config, ov, options, inferredUri
   }
   console.log(`
 Also searching seeded resources: ${projectResourceUri}`);
-  await maybeRun(options.dryRun === true, ov, withIdentity(config, args));
+  const result = await maybeRun(options.dryRun === true, ov, withIdentity(config, args));
+  return result ? [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n") : void 0;
 }
 async function runRead(config, uri, options) {
   assertVikingUri(uri);
@@ -8598,6 +9145,147 @@ async function syncSharedReposAndLog(config) {
     console.error(`Auto-sync warning: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
+async function printRecallHygieneNudges(config, recallOutput) {
+  const uris = activePersonalMemoryUrisFromText(recallOutput, config.user);
+  if (uris.length === 0) {
+    return;
+  }
+  const records = await readMemoryRecordsByUri(config, uris);
+  const nudges = recallHygieneNudges(recallOutput, { records, user: config.user });
+  if (nudges.length === 0) {
+    return;
+  }
+  console.log("\nMemory hygiene hints:");
+  for (const nudge of nudges) {
+    console.log(`- ${nudge}`);
+  }
+}
+async function runCompact(config, options) {
+  const project = normalizeOptionalMetadata2(options.project);
+  if (!project) {
+    throw new Error("Provide --project for scoped memory hygiene.");
+  }
+  if (options.apply === true && options.dryRun === true) {
+    throw new Error("Cannot combine --apply with --dry-run.");
+  }
+  const apply = options.apply === true;
+  const records = await scopedCompactRecords(config, {
+    kind: options.kind,
+    project
+  });
+  const plan = buildCompactPlan(records, {
+    kind: options.kind,
+    project,
+    topic: normalizeOptionalMetadata2(options.topic)
+  });
+  console.log(formatCompactPlan(plan, { apply }));
+  if (!apply) {
+    return;
+  }
+  const ov = await openVikingCliForMode(false);
+  const updatePath = (0, import_node_path6.join)(config.agentContextHome, "compact-memory-update.txt");
+  try {
+    for (const action of plan.keepUpdates) {
+      await (0, import_promises5.writeFile)(updatePath, action.content, { encoding: "utf8", mode: 384 });
+      await (0, import_promises5.chmod)(updatePath, 384);
+      await writeDurableMemoryFile(ov, config, action.uri, updatePath, "replace");
+    }
+  } finally {
+    await (0, import_promises5.rm)(updatePath, { force: true });
+  }
+  for (const action of plan.archives) {
+    await runArchive(config, action.uri, {
+      dryRun: false,
+      kind: action.kind,
+      project: action.project,
+      topic: action.topic
+    });
+  }
+  for (const action of plan.forgets) {
+    await runForget(config, action.uri, { dryRun: false });
+  }
+}
+async function scopedCompactRecords(config, options) {
+  const kinds = options.kind ? [options.kind] : ["handoff", "durable", "incident"];
+  const records = [];
+  for (const kind of kinds) {
+    const directory = localMemoryDirectoryForCompact(config, kind, options.project);
+    const uriDirectory = memoryUriDirectoryForCompact(config, kind, options.project);
+    let entries;
+    try {
+      entries = await (0, import_promises5.readdir)(directory, { withFileTypes: true });
+    } catch (_err) {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || entry.name.startsWith(".") || !entry.name.endsWith(".md")) {
+        continue;
+      }
+      const content = await readTextIfExists((0, import_node_path6.join)(directory, entry.name));
+      if (!content) {
+        continue;
+      }
+      const record = parseMemoryDocument(`${uriDirectory}/${entry.name}`, content);
+      if (record) {
+        records.push(record);
+      }
+    }
+  }
+  return records;
+}
+async function readMemoryRecordsByUri(config, uris) {
+  const records = [];
+  for (const uri of uris) {
+    const localPath = localMemoryPathForUri(config, uri);
+    if (!localPath) {
+      continue;
+    }
+    const content = await readTextIfExists(localPath);
+    if (!content) {
+      continue;
+    }
+    const record = parseMemoryDocument(uri, content);
+    if (record) {
+      records.push(record);
+    }
+  }
+  return records;
+}
+function localMemoryDirectoryForCompact(config, kind, project) {
+  const root = localUserMemoriesRoot(config);
+  const projectSegment = uriSegment(project);
+  switch (kind) {
+    case "durable":
+      return (0, import_node_path6.join)(root, "durable", "projects", projectSegment);
+    case "handoff":
+      return (0, import_node_path6.join)(root, "handoffs", "active", projectSegment);
+    case "incident":
+      return (0, import_node_path6.join)(root, "incidents", "active", projectSegment);
+  }
+}
+function memoryUriDirectoryForCompact(config, kind, project) {
+  const base = `viking://user/${uriSegment(config.user)}/memories`;
+  const projectSegment = uriSegment(project);
+  switch (kind) {
+    case "durable":
+      return `${base}/durable/projects/${projectSegment}`;
+    case "handoff":
+      return `${base}/handoffs/active/${projectSegment}`;
+    case "incident":
+      return `${base}/incidents/active/${projectSegment}`;
+  }
+}
+function localMemoryPathForUri(config, uri) {
+  const prefix = `viking://user/${uriSegment(config.user)}/memories/`;
+  if (!uri.startsWith(prefix) || uri.includes("/shared/")) {
+    return void 0;
+  }
+  const relative3 = uri.slice(prefix.length);
+  if (relative3.includes("..") || relative3.startsWith("/")) {
+    return void 0;
+  }
+  return (0, import_node_path6.join)(localUserMemoriesRoot(config), ...relative3.split("/"));
+}
 async function runList(config, uri, options) {
   assertVikingUri(uri);
   const ov = await openVikingCliForMode(options.dryRun === true);
@@ -8635,11 +9323,11 @@ async function runArchive(config, uri, options) {
     const fallbackMetadata = {
       archivedFrom: uri,
       kind: options.kind ?? "handoff",
-      project: normalizeOptionalMetadata(options.project),
+      project: normalizeOptionalMetadata2(options.project),
       sourceAgentClient: "threadnote",
       status: "archived",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      topic: normalizeOptionalMetadata(options.topic)
+      topic: normalizeOptionalMetadata2(options.topic)
     };
     await storeMemory(config, {
       bodyText: ["Archived original Threadnote memory.", "", "<original memory content would be read here>"].join("\n"),
@@ -8657,11 +9345,11 @@ async function runArchive(config, uri, options) {
   const metadata = {
     archivedFrom: uri,
     kind: options.kind ?? inferredMetadata.kind ?? "handoff",
-    project: normalizeOptionalMetadata(options.project) ?? inferredMetadata.project,
+    project: normalizeOptionalMetadata2(options.project) ?? inferredMetadata.project,
     sourceAgentClient: "threadnote",
     status: "archived",
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    topic: normalizeOptionalMetadata(options.topic) ?? inferredMetadata.topic
+    topic: normalizeOptionalMetadata2(options.topic) ?? inferredMetadata.topic
   };
   await storeMemory(config, {
     bodyText: ["Archived original Threadnote memory.", "", original].join("\n"),
@@ -8690,7 +9378,7 @@ async function runForget(config, uri, options) {
 }
 async function runExportPack(config, options) {
   const ov = await openVikingCliForMode(options.dryRun === true);
-  const defaultPath = (0, import_node_path5.join)(config.agentContextHome, `threadnote-${safeTimestamp()}.ovpack`);
+  const defaultPath = (0, import_node_path6.join)(config.agentContextHome, `threadnote-${safeTimestamp()}.ovpack`);
   const outputPath = expandPath(options.path ?? defaultPath);
   await maybeRun(options.dryRun === true, ov, withIdentity(config, ["export", options.uri ?? "viking://", outputPath]));
 }
@@ -8715,7 +9403,7 @@ async function inferRecallUri(config, query) {
 async function printExactMemoryMatches(config, ov, query, options) {
   const terms = exactRecallTerms(query);
   if (terms.length === 0) {
-    return;
+    return void 0;
   }
   const scopes = exactMemoryScopes(config, options.includeArchived);
   const outputs = [];
@@ -8727,30 +9415,32 @@ async function printExactMemoryMatches(config, ov, query, options) {
         continue;
       }
       const result = await runCommand(ov, args, { allowFailure: true });
-      const output2 = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
-      if (result.exitCode === 0 && grepOutputHasMatches(output2)) {
-        outputs.push(output2);
+      const output3 = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+      if (result.exitCode === 0 && grepOutputHasMatches(output3)) {
+        outputs.push(output3);
       }
     }
   }
   if (outputs.length === 0) {
-    return;
+    return void 0;
   }
-  console.log("\nExact durable memory matches:");
-  console.log(outputs.join("\n\n"));
+  console.log("\nExact memory/resource matches:");
+  const output2 = outputs.join("\n\n");
+  console.log(output2);
+  return output2;
 }
 async function storeMemory(config, options) {
   if (options.replaceUri) {
     assertVikingUri(options.replaceUri);
   }
   const ov = await openVikingCliForMode(options.dryRun);
-  const memoryPath = (0, import_node_path5.join)(config.agentContextHome, "last-memory.txt");
+  const memoryPath = (0, import_node_path6.join)(config.agentContextHome, "last-memory.txt");
   const candidateMetadata = { ...options.metadata, supersedes: options.replaceUri };
-  const candidateMemory = formatMemoryDocument(options.title, candidateMetadata, options.bodyText);
+  const candidateMemory = formatMemoryDocument2(options.title, candidateMetadata, options.bodyText);
   const memoryUri = memoryUriFor(config, candidateMemory, candidateMetadata);
   const isInPlaceUpdate = options.replaceUri !== void 0 && options.replaceUri === memoryUri;
   const finalMetadata = isInPlaceUpdate ? { ...options.metadata, supersedes: void 0 } : candidateMetadata;
-  const memory = isInPlaceUpdate ? formatMemoryDocument(options.title, finalMetadata, options.bodyText) : candidateMemory;
+  const memory = isInPlaceUpdate ? formatMemoryDocument2(options.title, finalMetadata, options.bodyText) : candidateMemory;
   const writeMode = await memoryWriteMode(ov, config, memoryUri, finalMetadata);
   if (options.dryRun) {
     console.log(memory);
@@ -8892,7 +9582,7 @@ async function hasLegacyLifecycleHandoffCandidates(config) {
   return (await legacyLifecycleHandoffCandidates(config, 1)).length > 0;
 }
 async function legacyLifecycleHandoffCandidates(config, limit) {
-  const eventsRoot = (0, import_node_path5.join)(localUserMemoriesRoot(config), "events");
+  const eventsRoot = (0, import_node_path6.join)(localUserMemoriesRoot(config), "events");
   let entries;
   try {
     entries = await (0, import_promises5.readdir)(eventsRoot, { withFileTypes: true });
@@ -8904,7 +9594,7 @@ async function legacyLifecycleHandoffCandidates(config, limit) {
     if (!entry.isFile() || entry.name.startsWith(".") || !entry.name.endsWith(".md")) {
       continue;
     }
-    const sourcePath = (0, import_node_path5.join)(eventsRoot, entry.name);
+    const sourcePath = (0, import_node_path6.join)(eventsRoot, entry.name);
     const original = await readTextIfExists(sourcePath);
     if (!original || !isClearLegacyHandoffMemory(original) || sensitiveMemoryReason(original)) {
       continue;
@@ -8990,7 +9680,7 @@ function vikingDirectoryChain(directoryUri) {
   }
   return chain;
 }
-function formatMemoryDocument(title, metadata, body) {
+function formatMemoryDocument2(title, metadata, body) {
   const header = [
     title,
     `kind: ${metadata.kind}`,
@@ -9007,10 +9697,10 @@ function formatMemoryDocument(title, metadata, body) {
 function inferMemoryMetadata(memory) {
   const header = memory.slice(0, Math.max(0, memory.indexOf("\n\n")) || memory.length);
   const firstLine2 = header.split("\n")[0]?.trim();
-  const kind = parseOptionalMemoryKind(parseHeaderValue(header, "kind")) ?? (firstLine2 === "HANDOFF" ? "handoff" : void 0);
-  const status = parseOptionalMemoryStatus(parseHeaderValue(header, "status"));
-  const project = normalizeOptionalMetadata(parseHeaderValue(header, "project")) ?? normalizeOptionalMetadata(parseHeaderValue(header, "repo"));
-  const topic = normalizeOptionalMetadata(parseHeaderValue(header, "topic")) ?? normalizeOptionalMetadata(parseHeaderValue(header, "task"));
+  const kind = parseOptionalMemoryKind2(parseHeaderValue(header, "kind")) ?? (firstLine2 === "HANDOFF" ? "handoff" : void 0);
+  const status = parseOptionalMemoryStatus2(parseHeaderValue(header, "status"));
+  const project = normalizeOptionalMetadata2(parseHeaderValue(header, "project")) ?? normalizeOptionalMetadata2(parseHeaderValue(header, "repo"));
+  const topic = normalizeOptionalMetadata2(parseHeaderValue(header, "topic")) ?? normalizeOptionalMetadata2(parseHeaderValue(header, "task"));
   return {
     kind,
     project,
@@ -9046,9 +9736,9 @@ function inferLegacyProject(memory) {
     return "general";
   }
   const trimmed = explicit.trim().replace(/[`.,;]+$/g, "");
-  return trimmed.includes("/") ? (0, import_node_path5.basename)(trimmed) : trimmed;
+  return trimmed.includes("/") ? (0, import_node_path6.basename)(trimmed) : trimmed;
 }
-function parseOptionalMemoryKind(value) {
+function parseOptionalMemoryKind2(value) {
   if (!value) {
     return void 0;
   }
@@ -9058,7 +9748,7 @@ function parseOptionalMemoryKind(value) {
     return void 0;
   }
 }
-function parseOptionalMemoryStatus(value) {
+function parseOptionalMemoryStatus2(value) {
   if (!value) {
     return void 0;
   }
@@ -9068,7 +9758,7 @@ function parseOptionalMemoryStatus(value) {
     return void 0;
   }
 }
-function normalizeOptionalMetadata(value) {
+function normalizeOptionalMetadata2(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : void 0;
 }
@@ -9086,14 +9776,14 @@ async function legacySourceAccounts(config, options) {
 async function legacyMemoryCandidates(config, sourceAccounts) {
   const candidates = [];
   for (const sourceAccount of sourceAccounts) {
-    const sessionRoot = (0, import_node_path5.join)(localVikingDataRoot(config), sourceAccount, "session");
+    const sessionRoot = (0, import_node_path6.join)(localVikingDataRoot(config), sourceAccount, "session");
     for (const sourceSession of await childDirectoryNames(sessionRoot)) {
-      const historyRoot = (0, import_node_path5.join)(sessionRoot, sourceSession, "history");
+      const historyRoot = (0, import_node_path6.join)(sessionRoot, sourceSession, "history");
       for (const sourceArchive of await childDirectoryNames(historyRoot)) {
         if (!sourceArchive.startsWith("archive_")) {
           continue;
         }
-        const sourcePath = (0, import_node_path5.join)(historyRoot, sourceArchive, "messages.jsonl");
+        const sourcePath = (0, import_node_path6.join)(historyRoot, sourceArchive, "messages.jsonl");
         for (const text of await legacyMemoryTexts(sourcePath)) {
           candidates.push({
             comparableHash: sha256(comparableMemoryText(text)),
@@ -9161,7 +9851,7 @@ async function collectDurableMemoryHashes(root, hashes) {
     return;
   }
   for (const entry of entries) {
-    const path = (0, import_node_path5.join)(root, entry.name);
+    const path = (0, import_node_path6.join)(root, entry.name);
     if (entry.isDirectory()) {
       await collectDurableMemoryHashes(path, hashes);
       continue;
@@ -9178,7 +9868,7 @@ async function collectDurableMemoryHashes(root, hashes) {
   }
 }
 function isDurableMemoryPath(path) {
-  return path.split(import_node_path5.sep).includes("memories");
+  return path.split(import_node_path6.sep).includes("memories");
 }
 async function childDirectoryNames(path) {
   let entries;
@@ -9222,10 +9912,10 @@ function legacySourceLabel(candidate) {
   return `${candidate.sourceAccount}/${candidate.sourceSession}/${candidate.sourceArchive}`;
 }
 function localVikingDataRoot(config) {
-  return (0, import_node_path5.join)(config.agentContextHome, "data", "viking");
+  return (0, import_node_path6.join)(config.agentContextHome, "data", "viking");
 }
 function localUserMemoriesRoot(config) {
-  return (0, import_node_path5.join)(localVikingDataRoot(config), config.account, "user", uriSegment(config.user), "memories");
+  return (0, import_node_path6.join)(localVikingDataRoot(config), config.account, "user", uriSegment(config.user), "memories");
 }
 function uniqueStrings(values) {
   return [...new Set(values)].sort();
@@ -9241,14 +9931,15 @@ async function buildHandoff(options) {
   const status = await gitValue(["status", "--short"], repoRoot) ?? "";
   const diffStat = await gitValue(["diff", "--stat", "HEAD"], repoRoot) ?? "";
   const touchedFiles = await gitTouchedFiles(repoRoot);
-  const repoName = (0, import_node_path5.basename)(repoRoot);
+  const repoName = (0, import_node_path6.basename)(repoRoot);
+  const topicBranch = branch && branch !== "unknown" ? branch : "current";
   const metadata = {
     kind: "handoff",
-    project: normalizeOptionalMetadata(options.project) ?? repoName,
+    project: normalizeOptionalMetadata2(options.project) ?? repoName,
     sourceAgentClient: options.sourceAgentClient ?? "codex",
     status: "active",
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    topic: normalizeOptionalMetadata(options.topic)
+    topic: handoffTopicForBranch(topicBranch, { timestamped: options.timestamped, topic: options.topic })
   };
   const bodyText = [
     `repo: ${repoName}`,
@@ -9301,7 +9992,7 @@ function formatBlock(value, emptyValue) {
 // src/update-check.ts
 var import_node_child_process2 = require("node:child_process");
 var import_promises6 = require("node:fs/promises");
-var import_node_path6 = require("node:path");
+var import_node_path7 = require("node:path");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var NPM_LATEST_URL = "https://registry.npmjs.org/threadnote/latest";
 var FETCH_TIMEOUT_MS = 3e3;
@@ -9380,7 +10071,7 @@ async function readUpdateCache(cachePath) {
 }
 async function writeUpdateCache(cachePath, contents) {
   try {
-    await (0, import_promises6.mkdir)((0, import_node_path6.dirname)(cachePath), { recursive: true });
+    await (0, import_promises6.mkdir)((0, import_node_path7.dirname)(cachePath), { recursive: true });
     await (0, import_promises6.writeFile)(cachePath, `${JSON.stringify(contents)}
 `, { encoding: "utf8", mode: 384 });
   } catch {
@@ -9404,14 +10095,14 @@ async function fetchLatestVersion() {
 
 // src/version.ts
 var import_node_fs4 = require("node:fs");
-var import_node_path7 = require("node:path");
+var import_node_path8 = require("node:path");
 var cachedVersion;
 function getThreadnoteVersion() {
   if (cachedVersion !== void 0) {
     return cachedVersion;
   }
   try {
-    const packageJsonPath = (0, import_node_path7.join)(__dirname, "..", "package.json");
+    const packageJsonPath = (0, import_node_path8.join)(__dirname, "..", "package.json");
     const parsed = JSON.parse((0, import_node_fs4.readFileSync)(packageJsonPath, "utf8"));
     cachedVersion = typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : "unknown";
   } catch {
@@ -9470,7 +10161,7 @@ async function runClaudeHooksInstall(options) {
     console.log("\nRe-run with --apply to actually modify the file.");
     return;
   }
-  await (0, import_promises7.mkdir)((0, import_node_path8.dirname)(path), { recursive: true });
+  await (0, import_promises7.mkdir)((0, import_node_path9.dirname)(path), { recursive: true });
   const serialized = `${JSON.stringify(next, void 0, 2)}
 `;
   await (0, import_promises7.writeFile)(path, serialized, { encoding: "utf8", mode: 384 });
@@ -9570,7 +10261,7 @@ async function hasManagedClaudeHooks() {
 async function runPreCompactHook(config, options = {}) {
   try {
     const repoRoot = await gitValue(["rev-parse", "--show-toplevel"]);
-    const project = repoRoot ? (0, import_node_path8.basename)(repoRoot) : "general";
+    const project = repoRoot ? (0, import_node_path9.basename)(repoRoot) : "general";
     await runHandoff(config, {
       blockers: "- none recorded",
       dryRun: options.dryRun === true,
@@ -9594,7 +10285,7 @@ async function runSessionStartHook(config, options = {}) {
     if (!repoRoot) {
       return;
     }
-    const project = (0, import_node_path8.basename)(repoRoot);
+    const project = (0, import_node_path9.basename)(repoRoot);
     await emitUpdateBannerIfOutdated(config);
     process.stdout.write(`## Threadnote \u2014 latest context for ${project}
 
@@ -9603,7 +10294,8 @@ async function runSessionStartHook(config, options = {}) {
       dryRun: options.dryRun === true,
       inferScope: true,
       nodeLimit: "5",
-      query: `${project} latest handoff durable feature memory`
+      // Keep "current branch" here so recall enriches the query with local git/workspace terms.
+      query: `${project} current branch latest handoff durable feature memory`
     });
   } catch (err) {
     process.stderr.write(
@@ -9615,7 +10307,7 @@ async function runSessionStartHook(config, options = {}) {
 async function emitUpdateBannerIfOutdated(config) {
   try {
     const result = await checkForThreadnoteUpdate({
-      cachePath: (0, import_node_path8.join)(config.agentContextHome, ".update-state.json"),
+      cachePath: (0, import_node_path9.join)(config.agentContextHome, ".update-state.json"),
       currentVersion: getThreadnoteVersion()
     });
     if (!result || !result.outdated) {
@@ -9641,12 +10333,12 @@ async function emitUpdateBannerIfOutdated(config) {
 
 // src/seeding.ts
 var import_promises8 = require("node:fs/promises");
-var import_node_path9 = require("node:path");
+var import_node_path10 = require("node:path");
 async function runSeed(config, options) {
   const manifest = await readSeedManifest(config.manifestPath);
   const ignorePatterns = await loadIgnorePatterns();
   const ov = await openVikingCliForMode(options.dryRun === true);
-  const statePath = (0, import_node_path9.join)(config.agentContextHome, SEED_STATE_FILE);
+  const statePath = (0, import_node_path10.join)(config.agentContextHome, SEED_STATE_FILE);
   const state = options.force === true ? { files: {}, version: 1 } : await readSeedState(statePath);
   const projects = filterProjects(manifest.projects, options.only);
   let importedCount = 0;
@@ -9726,13 +10418,13 @@ async function readSeedState(path) {
   }
 }
 async function writeSeedState(path, state) {
-  await ensureDirectory((0, import_node_path9.dirname)(path), false);
+  await ensureDirectory((0, import_node_path10.dirname)(path), false);
   await (0, import_promises8.writeFile)(path, `${JSON.stringify(state, void 0, 2)}
 `, { encoding: "utf8", mode: 384 });
 }
 async function runInitManifest(config, options) {
   const manifestPath = expandPath(
-    options.path ?? process.env.THREADNOTE_MANIFEST ?? (0, import_node_path9.join)(config.agentContextHome, USER_MANIFEST_NAME)
+    options.path ?? process.env.THREADNOTE_MANIFEST ?? (0, import_node_path10.join)(config.agentContextHome, USER_MANIFEST_NAME)
   );
   const repoInputs = options.repo && options.repo.length > 0 ? options.repo : [getInvocationCwd()];
   const existingManifest = options.replace === true || !await exists(manifestPath) ? void 0 : await readSeedManifest(manifestPath);
@@ -9775,7 +10467,7 @@ async function runInitManifest(config, options) {
     console.log(output2.trimEnd());
     return;
   }
-  await ensureDirectory((0, import_node_path9.dirname)(manifestPath), false);
+  await ensureDirectory((0, import_node_path10.dirname)(manifestPath), false);
   await (0, import_promises8.writeFile)(manifestPath, output2, { encoding: "utf8", mode: 384 });
   await (0, import_promises8.chmod)(manifestPath, 384);
   console.log(`Wrote manifest: ${manifestPath}`);
@@ -9813,7 +10505,7 @@ async function projectIdentity(path) {
   }
 }
 function projectManifestForRepo(repoRoot, existingProjects) {
-  const baseName = uriSegment((0, import_node_path9.basename)(repoRoot));
+  const baseName = uriSegment((0, import_node_path10.basename)(repoRoot));
   const usedNames = new Set(existingProjects.map((project) => project.name));
   const usedUris = new Set(existingProjects.map((project) => project.uri));
   let name = baseName;
@@ -9835,7 +10527,7 @@ async function collectSeedCandidates(project, projectRoot, ignorePatterns) {
   for (const pattern of project.seed) {
     const files = await resolveProjectPattern(projectRoot, pattern);
     for (const filePath of files) {
-      const relativePath = toPosixPath((0, import_node_path9.relative)(projectRoot, filePath));
+      const relativePath = toPosixPath((0, import_node_path10.relative)(projectRoot, filePath));
       if (seen.has(relativePath) || matchesIgnore(relativePath, ignorePatterns)) {
         continue;
       }
@@ -9853,17 +10545,17 @@ async function collectSeedCandidates(project, projectRoot, ignorePatterns) {
 async function resolveProjectPattern(projectRoot, pattern) {
   const normalizedPattern = toPosixPath(pattern);
   if (!hasGlob(normalizedPattern)) {
-    const filePath = (0, import_node_path9.join)(projectRoot, normalizedPattern);
+    const filePath = (0, import_node_path10.join)(projectRoot, normalizedPattern);
     return await isFile(filePath) ? [filePath] : [];
   }
   const globBase = getGlobBase(normalizedPattern);
-  const basePath = (0, import_node_path9.join)(projectRoot, globBase);
+  const basePath = (0, import_node_path10.join)(projectRoot, globBase);
   if (!await exists(basePath)) {
     return [];
   }
   const regex = globToRegExp(normalizedPattern);
   const files = await walkFiles(basePath);
-  return files.filter((filePath) => regex.test(toPosixPath((0, import_node_path9.relative)(projectRoot, filePath))));
+  return files.filter((filePath) => regex.test(toPosixPath((0, import_node_path10.relative)(projectRoot, filePath))));
 }
 async function prepareSeedFile(config, candidate, dryRun) {
   const content = await (0, import_promises8.readFile)(candidate.filePath, "utf8");
@@ -9878,12 +10570,12 @@ async function prepareSeedFile(config, candidate, dryRun) {
   if (redactedContent === content) {
     return candidate.filePath;
   }
-  const redactedPath = (0, import_node_path9.join)(config.agentContextHome, "redacted", candidate.projectName, candidate.relativePath);
+  const redactedPath = (0, import_node_path10.join)(config.agentContextHome, "redacted", candidate.projectName, candidate.relativePath);
   if (dryRun) {
     console.log(`Would write redacted copy: ${redactedPath}`);
     return redactedPath;
   }
-  await ensureDirectory((0, import_node_path9.dirname)(redactedPath), false);
+  await ensureDirectory((0, import_node_path10.dirname)(redactedPath), false);
   await (0, import_promises8.writeFile)(redactedPath, redactedContent, { encoding: "utf8", mode: 384 });
   await (0, import_promises8.chmod)(redactedPath, 384);
   return redactedPath;
@@ -9941,10 +10633,10 @@ async function resolveAbsolutePattern(pattern) {
   return files.filter((filePath) => regex.test(toPosixPath(filePath)));
 }
 function skillResourceUri(skill) {
-  return `viking://resources/agent-skills/${uriSegment(skill.source)}/${uriSegment((0, import_node_path9.basename)((0, import_node_path9.dirname)(skill.filePath)))}-${skill.hash.slice(0, 12)}.md`;
+  return `viking://resources/agent-skills/${uriSegment(skill.source)}/${uriSegment((0, import_node_path10.basename)((0, import_node_path10.dirname)(skill.filePath)))}-${skill.hash.slice(0, 12)}.md`;
 }
 async function loadIgnorePatterns() {
-  const raw = await (0, import_promises8.readFile)((0, import_node_path9.join)(toolRoot(), ".threadnoteignore"), "utf8");
+  const raw = await (0, import_promises8.readFile)((0, import_node_path10.join)(toolRoot(), ".threadnoteignore"), "utf8");
   return raw.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
 }
 function matchesIgnore(relativePath, patterns) {
@@ -10019,7 +10711,7 @@ var import_node_child_process3 = require("node:child_process");
 var import_node_fs6 = require("node:fs");
 var import_promises11 = require("node:fs/promises");
 var import_node_os6 = require("node:os");
-var import_node_path11 = require("node:path");
+var import_node_path12 = require("node:path");
 var import_node_process2 = require("node:process");
 var import_promises12 = require("node:readline/promises");
 
@@ -10027,7 +10719,7 @@ var import_promises12 = require("node:readline/promises");
 var import_node_fs5 = require("node:fs");
 var import_promises9 = require("node:fs/promises");
 var import_node_os5 = require("node:os");
-var import_node_path10 = require("node:path");
+var import_node_path11 = require("node:path");
 var import_promises10 = require("node:readline/promises");
 var import_node_process = require("node:process");
 var NPM_PACKAGE_NAME = "threadnote";
@@ -10242,7 +10934,7 @@ async function waitForOpenVikingHealthy(config, timeoutMs) {
   return isOpenVikingHealthy(config);
 }
 function launchAgentPlistPath() {
-  return (0, import_node_path10.join)((0, import_node_os5.homedir)(), "Library", "LaunchAgents", "io.threadnote.openviking.plist");
+  return (0, import_node_path11.join)((0, import_node_os5.homedir)(), "Library", "LaunchAgents", "io.threadnote.openviking.plist");
 }
 async function isLaunchAgentInstalled() {
   if (process.platform !== "darwin") {
@@ -10278,7 +10970,7 @@ async function getUpdateInfo(config, options) {
   };
 }
 async function currentPackageVersion() {
-  const rawPackage = await (0, import_promises9.readFile)((0, import_node_path10.join)(toolRoot(), "package.json"), "utf8");
+  const rawPackage = await (0, import_promises9.readFile)((0, import_node_path11.join)(toolRoot(), "package.json"), "utf8");
   const parsed = JSON.parse(rawPackage);
   if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
     throw new Error("Could not read current threadnote package version.");
@@ -10332,7 +11024,7 @@ async function writeUpdateCache2(config, cache) {
 `, { encoding: "utf8", mode: 384 });
 }
 function updateCachePath(config) {
-  return (0, import_node_path10.join)(config.agentContextHome, "update-check.json");
+  return (0, import_node_path11.join)(config.agentContextHome, "update-check.json");
 }
 async function runApplicablePostUpdateMigrations(config, options) {
   const state = await readPostUpdateState(config);
@@ -10396,7 +11088,7 @@ async function applicablePostUpdateMigrations(config, options) {
   return applicable;
 }
 async function readPostUpdateMigrations() {
-  const raw = await readFileIfExists((0, import_node_path10.join)(toolRoot(), "config", POST_UPDATE_MIGRATIONS_FILE));
+  const raw = await readFileIfExists((0, import_node_path11.join)(toolRoot(), "config", POST_UPDATE_MIGRATIONS_FILE));
   if (!raw) {
     return [];
   }
@@ -10474,7 +11166,7 @@ async function writePostUpdateState(config, state) {
 `, { encoding: "utf8", mode: 384 });
 }
 function postUpdateStatePath(config) {
-  return (0, import_node_path10.join)(config.agentContextHome, POST_UPDATE_STATE_FILE);
+  return (0, import_node_path11.join)(config.agentContextHome, POST_UPDATE_STATE_FILE);
 }
 async function resolveUpdateRuntime(runtime) {
   if (runtime !== "auto") {
@@ -10504,22 +11196,14 @@ async function runtimeThreadnoteBin(runtime) {
   if (runtime === "npm") {
     const result = await runCommand("npm", ["prefix", "--global"], { allowFailure: true });
     const prefix = result.stdout.trim();
-    return prefix ? (0, import_node_path10.join)(prefix, "bin", NPM_PACKAGE_NAME) : void 0;
+    return prefix ? (0, import_node_path11.join)(prefix, "bin", NPM_PACKAGE_NAME) : void 0;
   }
   if (runtime === "bun") {
     const result = await runCommand("bun", ["pm", "bin", "-g"], { allowFailure: true });
     const binDir = result.stdout.trim();
-    return binDir ? (0, import_node_path10.join)(binDir, NPM_PACKAGE_NAME) : void 0;
-  }
-  return (0, import_node_path10.join)(process.env.DENO_INSTALL ?? (0, import_node_path10.join)((0, import_node_os5.homedir)(), ".deno"), "bin", NPM_PACKAGE_NAME);
-}
-async function isExecutable(path) {
-  try {
-    await (0, import_promises9.access)(path, import_node_fs5.constants.X_OK);
-    return true;
-  } catch (_err) {
-    return false;
+    return binDir ? (0, import_node_path11.join)(binDir, NPM_PACKAGE_NAME) : void 0;
   }
+  return (0, import_node_path11.join)(process.env.DENO_INSTALL ?? (0, import_node_path11.join)((0, import_node_os5.homedir)(), ".deno"), "bin", NPM_PACKAGE_NAME);
 }
 function updatePackageCommand(runtime, registry) {
   if (runtime === "npm") {
@@ -10564,7 +11248,7 @@ async function runDoctor(config, options) {
   checks.push({ name: "platform", status: (0, import_node_os6.platform)() === "darwin" ? "ok" : "warn", detail: (0, import_node_os6.platform)() });
   checks.push(await commandCheck("node", ["--version"]));
   checks.push(await commandCheck("python3", ["--version"]));
-  checks.push(await commandCheck("openviking-server", ["--help"]));
+  checks.push(await openVikingServerCheck());
   checks.push(await firstCommandCheck("openviking cli", ["ov", "openviking"], ["--help"]));
   checks.push(await localEmbeddingCheck());
   checks.push(await pythonSystemCertificatesCheck());
@@ -10574,9 +11258,9 @@ async function runDoctor(config, options) {
   checks.push(await commandShimCheck());
   checks.push(...await userAgentInstructionsChecks());
   checks.push(await manifestCheck(config.manifestPath));
-  checks.push(await fileCheck((0, import_node_path11.join)(toolRoot(), ".threadnoteignore"), "ignore file"));
-  checks.push(await fileCheck((0, import_node_path11.join)(toolRoot(), "config", "ov.conf.template.json"), "server config template"));
-  checks.push(await fileCheck((0, import_node_path11.join)(toolRoot(), "config", "ovcli.conf.template.json"), "cli config template"));
+  checks.push(await fileCheck((0, import_node_path12.join)(toolRoot(), ".threadnoteignore"), "ignore file"));
+  checks.push(await fileCheck((0, import_node_path12.join)(toolRoot(), "config", "ov.conf.template.json"), "server config template"));
+  checks.push(await fileCheck((0, import_node_path12.join)(toolRoot(), "config", "ovcli.conf.template.json"), "cli config template"));
   checks.push(await healthCheck(config));
   for (const check of checks) {
     console.log(`${formatStatus(check.status)} ${check.name}: ${check.detail}`);
@@ -10593,12 +11277,13 @@ async function runInstall(config, options) {
   const repairInvalidConfigs = options.repairInvalidConfigs === true;
   const dryRun = options.dryRun === true;
   await ensureDirectory(config.agentContextHome, dryRun);
-  await ensureDirectory((0, import_node_path11.join)(config.agentContextHome, "logs"), dryRun);
-  await ensureDirectory((0, import_node_path11.join)(config.agentContextHome, "redacted"), dryRun);
-  await ensureDirectory((0, import_node_path11.join)(config.agentContextHome, "mcp"), dryRun);
+  await ensureDirectory((0, import_node_path12.join)(config.agentContextHome, "logs"), dryRun);
+  await ensureDirectory((0, import_node_path12.join)(config.agentContextHome, "redacted"), dryRun);
+  await ensureDirectory((0, import_node_path12.join)(config.agentContextHome, "mcp"), dryRun);
   await installCommandShim(dryRun);
   await installUserAgentInstructions(dryRun);
-  const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
+  const serverPath = await findOpenVikingServer();
+  let serverInstallRan = false;
   if (serverPath) {
     console.log(`OpenViking server already installed: ${serverPath}`);
     const localEmbeddingMissing = await hasLocalEmbeddingDependency(serverPath) === false;
@@ -10606,6 +11291,7 @@ async function runInstall(config, options) {
     if (options.force === true) {
       console.log(`Reinstalling OpenViking at pinned version ${config.openVikingVersion} (--force).`);
       await runInstallCommands(config, options.packageManager, true, dryRun);
+      serverInstallRan = true;
     } else if (localEmbeddingMissing) {
       const repairReasons = [];
       repairReasons.push("local embedding extra is missing");
@@ -10614,6 +11300,7 @@ async function runInstall(config, options) {
       }
       console.log(`OpenViking install needs repair: ${repairReasons.join("; ")}.`);
       await runInstallCommands(config, options.packageManager, true, dryRun);
+      serverInstallRan = true;
     } else if (pythonSystemCertificatesMissing) {
       console.log("OpenViking install needs repair: Python system certificate bridge is missing.");
       const installCommand = await getPythonSystemCertificatesInstallCommand(serverPath);
@@ -10621,20 +11308,25 @@ async function runInstall(config, options) {
     }
   } else {
     await runInstallCommands(config, options.packageManager, false, dryRun);
+    serverInstallRan = true;
+  }
+  const resolvedServerPath = serverInstallRan ? await findOpenVikingServer() : serverPath;
+  if (resolvedServerPath && !dryRun) {
+    await maybePrintOpenVikingPathHint(resolvedServerPath);
   }
   await writeTemplateIfMissing({
     config,
-    destinationPath: (0, import_node_path11.join)(config.agentContextHome, "ov.conf"),
+    destinationPath: (0, import_node_path12.join)(config.agentContextHome, "ov.conf"),
     dryRun,
     shouldRepair: (content) => shouldRepairOpenVikingConfig(content, config) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
-    templatePath: (0, import_node_path11.join)(toolRoot(), "config", "ov.conf.template.json")
+    templatePath: (0, import_node_path12.join)(toolRoot(), "config", "ov.conf.template.json")
   });
   await writeTemplateIfMissing({
     config,
-    destinationPath: (0, import_node_path11.join)(config.agentContextHome, "ovcli.conf"),
+    destinationPath: (0, import_node_path12.join)(config.agentContextHome, "ovcli.conf"),
     dryRun,
     shouldRepair: (content) => shouldRepairLegacyOvCliConfig(content) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
-    templatePath: (0, import_node_path11.join)(toolRoot(), "config", "ovcli.conf.template.json")
+    templatePath: (0, import_node_path12.join)(toolRoot(), "config", "ovcli.conf.template.json")
   });
   if (options.start !== false) {
     const healthy = await repairServerHealth(config, dryRun);
@@ -10688,7 +11380,7 @@ async function runUninstall(config, options) {
   }
   console.log("Uninstalling local Threadnote setup.");
   await runStop(config, { dryRun });
-  await removePathIfExists((0, import_node_path11.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
+  await removePathIfExists((0, import_node_path12.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
   await removeLaunchAgent(dryRun);
   await removeMcpConfigs(options.mcp ?? "available", dryRun);
   await removeMcpSnippets(config, dryRun);
@@ -10745,7 +11437,7 @@ async function repairManifest(config, dryRun) {
     console.log(output2.trimEnd());
     return;
   }
-  await ensureDirectory((0, import_node_path11.dirname)(config.manifestPath), false);
+  await ensureDirectory((0, import_node_path12.dirname)(config.manifestPath), false);
   const currentContent = await readFileIfExists(config.manifestPath);
   if (currentContent !== void 0) {
     const backupPath = `${config.manifestPath}.legacy-${safeTimestamp()}`;
@@ -10757,6 +11449,64 @@ async function repairManifest(config, dryRun) {
   await (0, import_promises11.chmod)(config.manifestPath, 384);
   console.log(`Wrote replacement manifest: ${config.manifestPath}`);
 }
+async function findOpenVikingServer() {
+  const onPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
+  if (onPath) {
+    return onPath;
+  }
+  for (const candidateDir of await openVikingServerCandidateDirs()) {
+    const candidate = (0, import_node_path12.join)(candidateDir, OPENVIKING_SERVER_COMMAND);
+    if (await isExecutable(candidate)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+var candidateDirsPromise;
+async function openVikingServerCandidateDirs() {
+  if (!candidateDirsPromise) {
+    candidateDirsPromise = computeOpenVikingServerCandidateDirs();
+  }
+  return candidateDirsPromise;
+}
+async function computeOpenVikingServerCandidateDirs() {
+  const dirs = [];
+  const uv = await findExecutable(["uv"]);
+  if (uv) {
+    const result = await runCommand(uv, ["tool", "dir", "--bin"], { allowFailure: true });
+    if (result.exitCode === 0) {
+      const dir = result.stdout.trim();
+      if (dir) {
+        dirs.push(dir);
+      }
+    }
+  }
+  if (process.env.UV_TOOL_BIN_DIR) {
+    dirs.push(process.env.UV_TOOL_BIN_DIR);
+  }
+  dirs.push(expandPath("~/.local/bin"));
+  return Array.from(new Set(dirs));
+}
+async function requireOpenVikingServer() {
+  const resolved = await findOpenVikingServer();
+  if (!resolved) {
+    throw new Error(
+      `${OPENVIKING_SERVER_COMMAND} was not found in PATH, uv tool bin dir, $UV_TOOL_BIN_DIR, or ~/.local/bin. Run \`threadnote install\` first.`
+    );
+  }
+  return resolved;
+}
+async function maybePrintOpenVikingPathHint(serverPath) {
+  const onPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
+  if (onPath) {
+    return;
+  }
+  const binDir = (0, import_node_path12.dirname)(serverPath);
+  const rcHint = suggestedShellRc(process.env.SHELL, (0, import_node_os6.platform)());
+  console.log(
+    `Note: ${serverPath} is installed but ${binDir} is not on this shell's PATH. Add \`export PATH="${binDir}:$PATH"\` to ${rcHint} so other tools can find openviking-server.`
+  );
+}
 async function repairServerHealth(config, dryRun) {
   const existingHealth = await readOpenVikingHealthIfAvailable(config, 800);
   if (existingHealth) {
@@ -10777,7 +11527,7 @@ async function runStart(config, options) {
     await installLaunchAgent(config, options.dryRun === true);
     return;
   }
-  const server = options.dryRun === true ? await findExecutable([OPENVIKING_SERVER_COMMAND]) ?? OPENVIKING_SERVER_COMMAND : await requiredExecutable(OPENVIKING_SERVER_COMMAND);
+  const server = options.dryRun === true ? await findOpenVikingServer() ?? OPENVIKING_SERVER_COMMAND : await requireOpenVikingServer();
   const args = openVikingServerArgs(config);
   if (options.dryRun === true) {
     console.log(formatShellCommand(server, args));
@@ -10795,7 +11545,7 @@ async function runStart(config, options) {
     );
   }
   const logPath = openVikingLogPath(config);
-  await ensureDirectory((0, import_node_path11.dirname)(logPath), false);
+  await ensureDirectory((0, import_node_path12.dirname)(logPath), false);
   if (options.foreground === true) {
     const result = await runInteractive(server, args);
     process.exitCode = result;
@@ -10804,7 +11554,7 @@ async function runStart(config, options) {
   const logFd = (0, import_node_fs6.openSync)(logPath, "a");
   const child = spawnDetachedServerWithLog(server, args, logFd);
   child.unref();
-  await (0, import_promises11.writeFile)((0, import_node_path11.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
+  await (0, import_promises11.writeFile)((0, import_node_path12.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
 `, "utf8");
   const health = await waitForOpenVikingHealth(config, START_HEALTH_TIMEOUT_MS);
   if (health) {
@@ -10837,7 +11587,7 @@ async function runStop(config, options) {
       console.log(`No LaunchAgent found: ${launchAgentPath}`);
     }
   }
-  const pidPath = (0, import_node_path11.join)(config.agentContextHome, "openviking-server.pid");
+  const pidPath = (0, import_node_path12.join)(config.agentContextHome, "openviking-server.pid");
   const pidText = await readFileIfExists(pidPath);
   if (!pidText) {
     console.log("No pid file found for detached OpenViking server.");
@@ -10871,6 +11621,21 @@ async function commandCheck(name, args) {
     detail: firstLine(result.stdout || result.stderr) || executable
   };
 }
+async function openVikingServerCheck() {
+  const name = OPENVIKING_SERVER_COMMAND;
+  const executable = await findOpenVikingServer();
+  if (!executable) {
+    return { name, status: "fail", detail: "missing; install will fetch it via uv or pipx" };
+  }
+  const result = await runCommand(executable, ["--help"], { allowFailure: true });
+  const onPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
+  const detail = onPath ? executable : `${executable} (found outside PATH; add ${(0, import_node_path12.dirname)(executable)} to PATH)`;
+  return {
+    name,
+    status: result.exitCode === 0 ? "ok" : "warn",
+    detail: result.exitCode === 0 ? detail : firstLine(result.stderr || result.stdout) || detail
+  };
+}
 async function commandPresenceCheck(name, args) {
   const executable = await findExecutable([name]);
   if (!executable) {
@@ -10899,7 +11664,7 @@ async function firstCommandCheck(name, commands, args) {
   return { name, status: "fail", detail: `none found: ${commands.join(", ")}` };
 }
 async function localEmbeddingCheck() {
-  const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
+  const serverPath = await findOpenVikingServer();
   if (!serverPath) {
     return { name: "local embedding extra", status: "warn", detail: "openviking-server missing" };
   }
@@ -10918,7 +11683,7 @@ async function localEmbeddingCheck() {
   };
 }
 async function pythonSystemCertificatesCheck() {
-  const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
+  const serverPath = await findOpenVikingServer();
   if (!serverPath) {
     return { name: "python system certs", status: "warn", detail: "openviking-server missing" };
   }
@@ -10933,7 +11698,7 @@ async function pythonSystemCertificatesCheck() {
   };
 }
 async function commandShimCheck() {
-  const shimPath = (0, import_node_path11.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const shimPath = (0, import_node_path12.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
   const content = await readFileIfExists(shimPath);
   if (content === void 0) {
     return { name: "threadnote shim", status: "warn", detail: `${shimPath} missing; repair will create it` };
@@ -11003,7 +11768,7 @@ async function siblingPythonForExecutable(executablePath) {
   } catch (_err) {
     return void 0;
   }
-  const pythonPath = (0, import_node_path11.join)((0, import_node_path11.dirname)(resolvedPath), "python");
+  const pythonPath = (0, import_node_path12.join)((0, import_node_path12.dirname)(resolvedPath), "python");
   return await exists(pythonPath) ? pythonPath : void 0;
 }
 async function manifestCheck(path) {
@@ -11099,6 +11864,7 @@ async function installUv() {
         console.log(result.stdout.trim());
       }
       if (await findExecutable(["uv"])) {
+        candidateDirsPromise = void 0;
         return true;
       }
     } else {
@@ -11115,6 +11881,7 @@ async function installUv() {
         console.log(result.stdout.trim());
       }
       if (await findExecutable(["uv"])) {
+        candidateDirsPromise = void 0;
         return true;
       }
       console.warn(
@@ -11221,14 +11988,14 @@ async function writeTemplateIfMissing(options) {
     console.log(`Would write ${options.destinationPath}`);
     return;
   }
-  await ensureDirectory((0, import_node_path11.dirname)(options.destinationPath), false);
+  await ensureDirectory((0, import_node_path12.dirname)(options.destinationPath), false);
   await (0, import_promises11.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
   await (0, import_promises11.chmod)(options.destinationPath, 384);
   console.log(`Wrote ${options.destinationPath}`);
 }
 async function installCommandShim(dryRun) {
   const binDir = expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin");
-  const shimPath = (0, import_node_path11.join)(binDir, "threadnote");
+  const shimPath = (0, import_node_path12.join)(binDir, "threadnote");
   const existingContent = await readFileIfExists(shimPath);
   if (existingContent && !isManagedCommandShim(existingContent)) {
     console.log(`WARN not overwriting existing command shim: ${shimPath}`);
@@ -11249,7 +12016,7 @@ async function installCommandShim(dryRun) {
   console.log(`Wrote command shim: ${shimPath}`);
 }
 async function removeCommandShim(dryRun) {
-  const shimPath = (0, import_node_path11.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const shimPath = (0, import_node_path12.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
   const content = await readFileIfExists(shimPath);
   if (content === void 0) {
     console.log(`Already absent: ${shimPath}`);
@@ -11283,7 +12050,7 @@ async function installUserAgentInstructions(dryRun) {
       console.log(currentContent === void 0 ? `Would write ${targetPath}` : `Would update ${targetPath}`);
       continue;
     }
-    await ensureDirectory((0, import_node_path11.dirname)(targetPath), false);
+    await ensureDirectory((0, import_node_path12.dirname)(targetPath), false);
     await (0, import_promises11.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
     console.log(currentContent === void 0 ? `Wrote ${targetPath}` : `Updated ${targetPath}`);
   }
@@ -11341,7 +12108,7 @@ async function renderUserAgentInstructions(target) {
   ].join("\n");
 }
 async function renderUserAgentInstructionsBlock() {
-  const instructions = (await (0, import_promises11.readFile)((0, import_node_path11.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
+  const instructions = (await (0, import_promises11.readFile)((0, import_node_path12.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
   return `${USER_INSTRUCTIONS_START_MARKER}
 ${instructions}
 ${USER_INSTRUCTIONS_END_MARKER}`;
@@ -11419,18 +12186,28 @@ async function installLaunchAgent(config, dryRun) {
   if ((0, import_node_os6.platform)() !== "darwin") {
     throw new Error("launchd autostart is only supported on macOS.");
   }
-  const source = (0, import_node_path11.join)(toolRoot(), "config", "launchd", `${LAUNCHD_LABEL}.plist.template`);
+  const resolvedServer = await findOpenVikingServer();
+  if (!resolvedServer && !dryRun) {
+    throw new Error(
+      `Cannot install LaunchAgent: ${OPENVIKING_SERVER_COMMAND} was not found in PATH, uv tool bin dir, $UV_TOOL_BIN_DIR, or ~/.local/bin. Run \`threadnote install\` first.`
+    );
+  }
+  const source = (0, import_node_path12.join)(toolRoot(), "config", "launchd", `${LAUNCHD_LABEL}.plist.template`);
   const destination = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
-  const rendered = renderTemplate(await (0, import_promises11.readFile)(source, "utf8"), config);
+  const rendered = renderTemplate(await (0, import_promises11.readFile)(source, "utf8"), config, {
+    OPENVIKING_SERVER_PATH: resolvedServer ?? OPENVIKING_SERVER_COMMAND
+  });
   if (dryRun) {
+    const resolutionDetail = resolvedServer ?? `<not found; would use bare \`${OPENVIKING_SERVER_COMMAND}\`>`;
+    console.log(`Resolved openviking-server: ${resolutionDetail}`);
     console.log(`Would write ${destination}`);
     console.log(`Would run: launchctl unload ${destination}`);
     console.log(`Would run: launchctl load ${destination}`);
     console.log(`Would run: launchctl start ${LAUNCHD_LABEL}`);
     return;
   }
-  await ensureDirectory((0, import_node_path11.dirname)(destination), false);
-  await ensureDirectory((0, import_node_path11.dirname)(openVikingLogPath(config)), false);
+  await ensureDirectory((0, import_node_path12.dirname)(destination), false);
+  await ensureDirectory((0, import_node_path12.dirname)(openVikingLogPath(config)), false);
   await (0, import_promises11.writeFile)(destination, rendered, "utf8");
   await maybeRun(false, "launchctl", ["unload", destination], { allowFailure: true });
   await maybeRun(false, "launchctl", ["load", destination]);
@@ -11494,7 +12271,7 @@ function isGeneratedLocalPilotConfig(parsed, config) {
   if (typeof parsed.default_user !== "string") {
     return false;
   }
-  if (!isJsonObject(parsed.storage) || parsed.storage.workspace !== (0, import_node_path11.join)(config.agentContextHome, "data")) {
+  if (!isJsonObject(parsed.storage) || parsed.storage.workspace !== (0, import_node_path12.join)(config.agentContextHome, "data")) {
     return false;
   }
   return isJsonObject(parsed.server) && parsed.server.host === config.host && String(parsed.server.port) === String(config.port);
@@ -11614,16 +12391,19 @@ async function main() {
   program2.command("migrate-lifecycle").description("Move clear legacy handoff memories into lifecycle-aware archive paths").option("--apply", "Perform the migration; without this, prints a dry run").option("--dry-run", "Print migration actions without writing or removing memories").option("--limit <count>", "Maximum number of legacy handoffs to migrate").action(async (options) => {
     await runMigrateLifecycle(getRuntimeConfig(program2), options);
   });
-  program2.command("recall").description("Search shared OpenViking context").requiredOption("--query <query>", "Search query").option("--dry-run", "Print ov command without searching").option("--include-archived", "Include archived memories in exact durable-memory matches").option("-n, --node-limit <count>", "Maximum number of search results").option("--no-infer-scope", "Disable query-based scope inference").option("--uri <uri>", "Restrict search to a viking:// URI").action(async (options) => {
+  program2.command("recall").description("Search shared OpenViking context").requiredOption("--query <query>", "Search query").option("--dry-run", "Print ov command without searching").option("--include-archived", "Include archived memories in exact memory/resource matches").option("-n, --node-limit <count>", "Maximum number of search results").option("--no-infer-scope", "Disable query-based scope inference").option("--uri <uri>", "Restrict search to a viking:// URI").action(async (options) => {
     await runRecall(getRuntimeConfig(program2), options);
   });
+  program2.command("compact").description("Plan or apply scoped memory hygiene for active personal memories").requiredOption("--project <name>", "Project/repo namespace to inspect").option("--apply", "Apply the compact plan; without this, prints a dry run").option("--dry-run", "Print the compact plan without changing anything").option("--kind <kind>", "durable, handoff, or incident", parseCompactKind).option("--topic <name>", "Stable topic name to inspect").action(async (options) => {
+    await runCompact(getRuntimeConfig(program2), options);
+  });
   program2.command("read").description("Read a viking:// URI returned by recall or list").argument("<uri>", "viking:// URI to read").option("--dry-run", "Print ov command without reading").action(async (uri, options) => {
     await runRead(getRuntimeConfig(program2), uri, options);
   });
   program2.command("list").alias("ls").description("List a viking:// directory").argument("[uri]", "viking:// URI to list", "viking://").option("-a, --all", "Show hidden files such as .abstract.md and .overview.md").option("--dry-run", "Print ov command without listing").option("-n, --node-limit <count>", "Maximum number of nodes to list").option("-r, --recursive", "List subdirectories recursively").option("-s, --simple", "Print only paths").action(async (uri, options) => {
     await runList(getRuntimeConfig(program2), uri, options);
   });
-  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--project <name>", "Project/repo namespace; defaults to current repo basename").option("--replace <uri>", "Supersede an existing viking:// memory after the new handoff is stored").option("--source-agent-client <name>", "codex, claude, cursor, copilot, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").option("--topic <name>", "Stable topic name; active handoffs with the same project/topic update one file").action(async (options) => {
+  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--project <name>", "Project/repo namespace; defaults to current repo basename").option("--replace <uri>", "Supersede an existing viking:// memory after the new handoff is stored").option("--source-agent-client <name>", "codex, claude, cursor, copilot, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").option("--timestamped", "Store a historical timestamped handoff instead of updating the current branch handoff").option("--topic <name>", "Stable topic name; active handoffs with the same project/topic update one file").action(async (options) => {
     await runHandoff(getRuntimeConfig(program2), options);
   });
   program2.command("archive").description("Move a memory into the archived lifecycle tree, then remove the original after the archive is stored").argument("<uri>", "viking:// memory URI to archive").option("--dry-run", "Print archive content and ov commands without changing anything").option("--kind <kind>", "durable, handoff, incident, preference, or smoke", parseMemoryKind).option("--project <name>", "Override inferred project/repo namespace").option("--topic <name>", "Override inferred topic").action(async (uri, options) => {