@usewhisper/mcp-server 2.5.0 → 2.8.0

package/README.md

@@ -12,6 +12,13 @@ Whisper MCP is the universal context bridge for coding agents. It connects Claud
 - Scoped MCP config generator: `whisper-context-mcp scope ...`
 - Tool migration helper: `whisper-context-mcp --print-tool-map`
 
+## What's New in v2.6
+
+- Automatic project, user, and session scope defaults for MCP retrieval and memory operations.
+- `context.query` can use the automatic agent runtime by default when the caller has not requested manual-only filters.
+- URL and domain-style retrieval requests now isolate matching sources better in shared projects.
+- MCP memory operations now default to pending/session-aware reads and writes when compatible.
+
 ## Install
 
 ```text
@@ -132,6 +139,16 @@ All valid `search` calls return the same top-level payload shape:
 }
 ```
 
+### Automatic Defaults
+
+When compatible with the caller’s requested options, Whisper MCP now behaves like an implicit context layer instead of a raw tool database:
+
+- `context.query` auto-attaches default project, user, and session scope
+- compatible retrieval calls use automatic runtime-backed pre-retrieval
+- memory writes and session ingest calls attach stable default scope automatically
+
+If the caller explicitly requests manual query controls such as `chunk_types`, explicit graph traversal, or other narrow filters, MCP preserves those manual semantics instead of forcing automatic mode.
+
 ## Source Contract (`context.add_source`)
 
 Input:

package/dist/server.js

@@ -1365,6 +1365,29 @@ ${lines.join("\n")}`;
 function compactWhitespace(value) {
   return value.replace(/\s+/g, " ").trim();
 }
+function normalizeSummary(value) {
+  return compactWhitespace(String(value || "").toLowerCase());
+}
+function tokenize(value) {
+  return normalizeSummary(value).split(/[^a-z0-9_./-]+/i).map((token) => token.trim()).filter(Boolean);
+}
+function jaccardOverlap(left, right) {
+  const leftTokens = new Set(tokenize(left));
+  const rightTokens = new Set(tokenize(right));
+  if (leftTokens.size === 0 || rightTokens.size === 0) return 0;
+  let intersection = 0;
+  for (const token of leftTokens) {
+    if (rightTokens.has(token)) intersection += 1;
+  }
+  const union = (/* @__PURE__ */ new Set([...leftTokens, ...rightTokens])).size;
+  return union > 0 ? intersection / union : 0;
+}
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
 function withTimeout(promise, timeoutMs) {
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
@@ -1398,39 +1421,76 @@ function extractTimestamp(metadata) {
   }
   return 0;
 }
-function salienceBoost(metadata) {
-  const value = metadata?.salience;
-  if (value === "high") return 0.12;
-  if (value === "medium") return 0.06;
-  return 0;
-}
+var DEFAULT_RANK_WEIGHTS = {
+  focusedPassBonus: 0.2,
+  sourceMatchBonus: 0.18,
+  touchedFileBonus: 0.12,
+  clientMatchBonus: 0.1,
+  highSalienceBonus: 0.12,
+  mediumSalienceBonus: 0.06,
+  staleBroadPenalty: -0.1,
+  unrelatedClientPenalty: -0.18,
+  lowSaliencePenalty: -0.12
+};
+var DEFAULT_SOURCE_ACTIVITY = {
+  maxTurns: 10,
+  maxIdleMs: 30 * 60 * 1e3,
+  decayAfterTurns: 5,
+  decayAfterIdleMs: 15 * 60 * 1e3,
+  evictOnTaskSwitch: true
+};
 var WhisperAgentRuntime = class {
   constructor(args) {
     this.args = args;
     this.bindingStore = createBindingStore(args.options.bindingStorePath);
-    this.topK = args.options.topK ?? 6;
+    const retrieval = args.options.retrieval || {};
+    this.focusedTopK = retrieval.focusedTopK ?? args.options.topK ?? 6;
+    this.broadTopK = retrieval.broadTopK ?? Math.max(args.options.topK ?? 6, 10);
     this.maxTokens = args.options.maxTokens ?? 4e3;
     this.targetRetrievalMs = args.options.targetRetrievalMs ?? 2500;
     this.hardRetrievalTimeoutMs = args.options.hardRetrievalTimeoutMs ?? 4e3;
     this.recentWorkLimit = args.options.recentWorkLimit ?? 40;
     this.baseContext = args.baseContext;
     this.clientName = args.baseContext.clientName || "whisper-agent-runtime";
+    this.minFocusedResults = retrieval.minFocusedResults ?? 3;
+    this.minFocusedTopScore = retrieval.minFocusedTopScore ?? 0.55;
+    this.minProjectScore = retrieval.minProjectScore ?? 0.5;
+    this.minMemoryScore = retrieval.minMemoryScore ?? 0.6;
+    this.rankWeights = { ...DEFAULT_RANK_WEIGHTS, ...retrieval.rankWeights || {} };
+    this.sourceActivityOptions = { ...DEFAULT_SOURCE_ACTIVITY, ...retrieval.sourceActivity || {} };
   }
   bindingStore;
-  topK;
+  focusedTopK;
+  broadTopK;
   maxTokens;
   targetRetrievalMs;
   hardRetrievalTimeoutMs;
   recentWorkLimit;
   baseContext;
   clientName;
+  minFocusedResults;
+  minFocusedTopScore;
+  minProjectScore;
+  minMemoryScore;
+  rankWeights;
+  sourceActivityOptions;
   bindings = null;
   touchedFiles = [];
   recentWork = [];
+  recentSourceActivity = [];
   bufferedLowSalience = [];
   lastPreparedTurn = null;
   mergedCount = 0;
   droppedCount = 0;
+  focusedPassHits = 0;
+  fallbackTriggers = 0;
+  floorDroppedCount = 0;
+  injectedItemCount = 0;
+  sourceScopedTurns = 0;
+  broadScopedTurns = 0;
+  totalTurns = 0;
+  currentTurn = 0;
+  lastTaskSummary = "";
   lastScope = {};
   async getBindings() {
     if (!this.bindings) {
@@ -1448,6 +1508,64 @@ var WhisperAgentRuntime = class {
   pushWorkEvent(event) {
     this.recentWork = [...this.recentWork, event].slice(-this.recentWorkLimit);
   }
+  noteSourceActivity(sourceIds) {
+    const now = Date.now();
+    for (const sourceId of [...new Set((sourceIds || []).map((value) => String(value || "").trim()).filter(Boolean))]) {
+      this.recentSourceActivity = [
+        ...this.recentSourceActivity.filter((entry) => entry.sourceId !== sourceId),
+        { sourceId, turn: this.currentTurn, at: now }
+      ].slice(-24);
+    }
+  }
+  refreshTaskSummary(taskSummary) {
+    const next = normalizeSummary(taskSummary);
+    if (!next) return;
+    if (this.sourceActivityOptions.evictOnTaskSwitch && this.lastTaskSummary && this.lastTaskSummary !== next && jaccardOverlap(this.lastTaskSummary, next) < 0.6) {
+      this.recentSourceActivity = [];
+    }
+    this.lastTaskSummary = next;
+  }
+  activeSourceIds() {
+    const now = Date.now();
+    const active = /* @__PURE__ */ new Map();
+    const maxTurns = this.sourceActivityOptions.maxTurns;
+    const maxIdleMs = this.sourceActivityOptions.maxIdleMs;
+    const decayAfterTurns = this.sourceActivityOptions.decayAfterTurns;
+    const decayAfterIdleMs = this.sourceActivityOptions.decayAfterIdleMs;
+    const fresh = [];
+    for (const entry of this.recentSourceActivity) {
+      const turnDelta = this.currentTurn - entry.turn;
+      const idleDelta = now - entry.at;
+      if (turnDelta > maxTurns || idleDelta > maxIdleMs) continue;
+      fresh.push(entry);
+      let weight = 1;
+      if (turnDelta > decayAfterTurns || idleDelta > decayAfterIdleMs) {
+        weight = 0.5;
+      }
+      const current = active.get(entry.sourceId) || 0;
+      active.set(entry.sourceId, Math.max(current, weight));
+    }
+    this.recentSourceActivity = fresh.slice(-24);
+    return [...active.entries()].sort((left, right) => right[1] - left[1]).map(([sourceId]) => sourceId).slice(0, 4);
+  }
+  focusedScope(input) {
+    const sourceIds = this.activeSourceIds();
+    const fileHints = [...new Set([
+      ...input.touchedFiles || [],
+      ...this.touchedFiles,
+      ...this.recentWork.flatMap((event) => event.filePaths || [])
+    ].map((value) => String(value || "").trim()).filter(Boolean))].slice(-4);
+    return {
+      sourceIds,
+      fileHints,
+      clientName: this.clientName || void 0
+    };
+  }
+  exactFileMetadataFilter(fileHints) {
+    const exact = fileHints.find((value) => /[\\/]/.test(value));
+    if (!exact) return void 0;
+    return { filePath: exact };
+  }
   makeTaskFrameQuery(input) {
     const task = compactWhitespace(input.taskSummary || "");
     const salient = this.recentWork.filter((event) => event.salience === "high").slice(-3).map((event) => `${event.kind}: ${event.summary}`);
@@ -1524,23 +1642,29 @@ var WhisperAgentRuntime = class {
       };
     }
   }
-  contextItems(result, sourceQuery) {
+  contextItems(result, sourceQuery, pass) {
+    const sourceScope = result.meta?.source_scope;
+    if (sourceScope?.mode === "auto" || sourceScope?.mode === "explicit") {
+      this.noteSourceActivity(sourceScope.source_ids || []);
+    }
     return (result.results || []).map((item) => ({
       id: item.id,
       content: item.content,
       type: "project",
       score: item.score ?? 0,
       sourceQuery,
+      pass,
       metadata: item.metadata || {}
     }));
   }
-  memoryItems(result, sourceQuery) {
+  memoryItems(result, sourceQuery, pass) {
     return (result.results || []).map((item, index) => ({
       id: item.memory?.id || item.chunk?.id || `${sourceQuery}_memory_${index}`,
       content: item.chunk?.content || item.memory?.content || "",
       type: "memory",
       score: item.similarity ?? 0,
       sourceQuery,
+      pass,
       metadata: {
         ...item.chunk?.metadata || {},
         ...item.memory?.temporal || {},
@@ -1548,22 +1672,99 @@ var WhisperAgentRuntime = class {
       }
     })).filter((item) => item.content);
   }
-  rerank(items) {
+  stableItemKey(item) {
+    const metadata = item.metadata || {};
+    const sourceId = String(metadata.source_id || "");
+    const documentId = String(metadata.document_id || metadata.documentId || "");
+    const chunkId = String(metadata.chunk_id || metadata.chunkId || item.id || "");
+    return stableHash(`${sourceId}|${documentId}|${chunkId}|${item.content.slice(0, 256)}`);
+  }
+  metadataStrings(item) {
+    const metadata = item.metadata || {};
+    return [
+      metadata.filePath,
+      metadata.file_path,
+      metadata.path,
+      metadata.section_path,
+      metadata.parent_section_path,
+      metadata.web_url,
+      metadata.url
+    ].map((value) => String(value || "").toLowerCase()).filter(Boolean);
+  }
+  hasSourceMatch(item, scope) {
+    const sourceId = String(item.metadata?.source_id || "");
+    return Boolean(sourceId && scope.sourceIds.includes(sourceId));
+  }
+  hasFileMatch(item, scope) {
+    if (scope.fileHints.length === 0) return false;
+    const metadata = this.metadataStrings(item);
+    const lowerHints = scope.fileHints.map((hint) => hint.toLowerCase());
+    return lowerHints.some((hint) => {
+      const base = pathBase(hint).toLowerCase();
+      return metadata.some((value) => value.includes(hint) || value.endsWith(base));
+    });
+  }
+  hasClientMatch(item, scope) {
+    const itemClient = String(item.metadata?.client_name || "");
+    return Boolean(scope.clientName && itemClient && itemClient === scope.clientName);
+  }
+  salienceAdjustment(item) {
+    const salience = item.metadata?.salience;
+    if (salience === "high") return this.rankWeights.highSalienceBonus;
+    if (salience === "medium") return this.rankWeights.mediumSalienceBonus;
+    if (salience === "low") return this.rankWeights.lowSaliencePenalty;
+    return 0;
+  }
+  narrowFocusedMemories(items, scope) {
+    const hasSignals = scope.sourceIds.length > 0 || scope.fileHints.length > 0 || Boolean(scope.clientName);
+    if (!hasSignals) return items;
+    const narrowed = items.filter((item) => {
+      const matchesClient = this.hasClientMatch(item, scope);
+      const matchesFile = this.hasFileMatch(item, scope);
+      const matchesSource = this.hasSourceMatch(item, scope);
+      const salience = item.metadata?.salience;
+      if (scope.clientName && item.metadata?.client_name && !matchesClient) {
+        return false;
+      }
+      if (salience === "low" && !matchesFile && !matchesSource) {
+        return false;
+      }
+      return matchesClient || matchesFile || matchesSource || !scope.clientName;
+    });
+    return narrowed.length > 0 ? narrowed : items;
+  }
+  applyRelevanceFloor(items) {
+    const filtered = items.filter(
+      (item) => item.type === "project" ? item.score >= this.minProjectScore : item.score >= this.minMemoryScore
+    );
+    return { items: filtered, dropped: Math.max(0, items.length - filtered.length) };
+  }
+  rerank(items, scope) {
     const deduped = /* @__PURE__ */ new Map();
     for (const item of items) {
-      const key = `${item.id}:${item.content.toLowerCase()}`;
+      const key = this.stableItemKey(item);
       const recency = extractTimestamp(item.metadata) > 0 ? 0.04 : 0;
       const queryBonus = item.sourceQuery === "primary" ? 0.08 : item.sourceQuery === "task_frame" ? 0.04 : 0.03;
+      const sourceMatch = this.hasSourceMatch(item, scope);
+      const fileMatch = this.hasFileMatch(item, scope);
+      const clientMatch = this.hasClientMatch(item, scope);
+      const broadPenalty = item.pass === "broad" && !sourceMatch && !fileMatch && !clientMatch ? this.rankWeights.staleBroadPenalty : 0;
+      const clientPenalty = scope.clientName && item.metadata?.client_name && !clientMatch ? this.rankWeights.unrelatedClientPenalty : 0;
       const next = {
         ...item,
-        score: item.score + queryBonus + salienceBoost(item.metadata) + recency
+        score: clamp01(
+          item.score + queryBonus + recency + (item.pass === "focused" ? this.rankWeights.focusedPassBonus : 0) + (sourceMatch ? this.rankWeights.sourceMatchBonus : 0) + (fileMatch ? this.rankWeights.touchedFileBonus : 0) + (clientMatch ? this.rankWeights.clientMatchBonus : 0) + this.salienceAdjustment(item) + broadPenalty + clientPenalty
+        )
       };
       const existing = deduped.get(key);
       if (!existing || next.score > existing.score) {
         deduped.set(key, next);
       }
     }
-    return [...deduped.values()].sort((left, right) => right.score - left.score);
+    return {
+      items: [...deduped.values()].sort((left, right) => right.score - left.score),
+      dedupedCount: Math.max(0, items.length - deduped.size)
+    };
   }
   buildContext(items) {
     const maxChars = this.maxTokens * 4;
@@ -1602,7 +1803,7 @@ ${lines.join("\n")}`;
       this.runBranch("project_rules", () => this.args.adapter.query({
         project: scope.project,
         query: "project rules instructions constraints conventions open threads",
-        top_k: this.topK,
+        top_k: this.focusedTopK,
         include_memories: false,
         user_id: scope.userId,
         session_id: scope.sessionId,
@@ -1620,7 +1821,7 @@ ${lines.join("\n")}`;
         continue;
       }
       if (branch.name === "project_rules") {
-        items.push(...this.contextItems(branch.value, "bootstrap"));
+        items.push(...this.contextItems(branch.value, "bootstrap", "bootstrap"));
         continue;
       }
       const records = branch.value.memories || [];
@@ -1630,10 +1831,12 @@ ${lines.join("\n")}`;
         type: "memory",
         score: 0.4,
         sourceQuery: "bootstrap",
+        pass: "bootstrap",
         metadata: memory
       })).filter((item) => item.content));
     }
-    const ranked = this.rerank(items).slice(0, this.topK * 2);
+    const reranked = this.rerank(items, { sourceIds: [], fileHints: [], clientName: this.clientName });
+    const ranked = reranked.items.slice(0, this.broadTopK * 2);
     const prepared = {
       scope,
       retrieval: {
@@ -1645,7 +1848,14 @@ ${lines.join("\n")}`;
         durationMs: Date.now() - startedAt,
         targetBudgetMs: this.targetRetrievalMs,
         hardTimeoutMs: this.hardRetrievalTimeoutMs,
-        branchStatus
+        branchStatus,
+        focusedScopeApplied: false,
+        focusedSourceIds: [],
+        focusedFileHints: [],
+        clientScoped: false,
+        fallbackUsed: false,
+        droppedBelowFloor: 0,
+        dedupedCount: reranked.dedupedCount
       },
       context: this.buildContext(ranked),
       items: ranked
@@ -1654,100 +1864,195 @@ ${lines.join("\n")}`;
     return prepared;
   }
   async beforeTurn(input, context = {}) {
+    this.currentTurn += 1;
     this.pushTouchedFiles(input.touchedFiles);
+    this.refreshTaskSummary(input.taskSummary);
     const { scope, warning } = await this.resolveScope(context);
     const primaryQuery = compactWhitespace(input.userMessage);
     const taskFrameQuery = this.makeTaskFrameQuery(input);
+    const focusedScope = this.focusedScope(input);
+    const focusedMetadataFilter = this.exactFileMetadataFilter(focusedScope.fileHints);
+    const focusedScopeApplied = focusedScope.sourceIds.length > 0 || focusedScope.fileHints.length > 0 || Boolean(focusedScope.clientName);
     const warnings = warning ? [warning] : [];
     const startedAt = Date.now();
-    const branches = await Promise.all([
-      this.runBranch("context_primary", () => this.args.adapter.query({
+    const branchStatus = {};
+    const collectFromBranches = (branches, pass) => {
+      const collected = [];
+      let okCount = 0;
+      for (const branch of branches) {
+        branchStatus[branch.name] = branch.status;
+        if (branch.status !== "ok") {
+          if (branch.status !== "skipped" && branch.reason) warnings.push(`${branch.name}:${branch.reason}`);
+          continue;
+        }
+        okCount += 1;
+        if (branch.name.startsWith("context")) {
+          collected.push(...this.contextItems(
+            branch.value,
+            branch.name.includes("task_frame") ? "task_frame" : "primary",
+            pass
+          ));
+        } else {
+          const memoryItems = this.memoryItems(
+            branch.value,
+            branch.name.includes("task_frame") ? "task_frame" : "primary",
+            pass
+          );
+          collected.push(...pass === "focused" ? this.narrowFocusedMemories(memoryItems, focusedScope) : memoryItems);
+        }
+      }
+      return { collected, okCount };
+    };
+    const focusedBranches = await Promise.all([
+      this.runBranch("context_primary_focused", () => this.args.adapter.query({
         project: scope.project,
         query: primaryQuery,
-        top_k: this.topK,
+        top_k: this.focusedTopK,
         include_memories: false,
         user_id: scope.userId,
         session_id: scope.sessionId,
+        source_ids: focusedScope.sourceIds.length > 0 ? focusedScope.sourceIds : void 0,
+        metadata_filter: focusedMetadataFilter,
         max_tokens: this.maxTokens,
         compress: true,
         compression_strategy: "adaptive"
       })),
-      this.runBranch("memory_primary", () => this.args.adapter.searchMemories({
+      this.runBranch("memory_primary_focused", () => this.args.adapter.searchMemories({
         project: scope.project,
         query: primaryQuery,
         user_id: scope.userId,
         session_id: scope.sessionId,
-        top_k: this.topK,
+        top_k: this.focusedTopK,
         include_pending: true,
         profile: "balanced"
       })),
-      taskFrameQuery ? this.runBranch("context_task_frame", () => this.args.adapter.query({
+      taskFrameQuery ? this.runBranch("context_task_frame_focused", () => this.args.adapter.query({
         project: scope.project,
         query: taskFrameQuery,
-        top_k: this.topK,
+        top_k: this.focusedTopK,
         include_memories: false,
         user_id: scope.userId,
         session_id: scope.sessionId,
+        source_ids: focusedScope.sourceIds.length > 0 ? focusedScope.sourceIds : void 0,
+        metadata_filter: focusedMetadataFilter,
         max_tokens: this.maxTokens,
         compress: true,
         compression_strategy: "adaptive"
-      })) : Promise.resolve({
-        name: "context_task_frame",
-        status: "skipped",
-        durationMs: 0
-      }),
-      taskFrameQuery ? this.runBranch("memory_task_frame", () => this.args.adapter.searchMemories({
+      })) : Promise.resolve({ name: "context_task_frame_focused", status: "skipped", durationMs: 0 }),
+      taskFrameQuery ? this.runBranch("memory_task_frame_focused", () => this.args.adapter.searchMemories({
         project: scope.project,
         query: taskFrameQuery,
         user_id: scope.userId,
         session_id: scope.sessionId,
-        top_k: this.topK,
+        top_k: this.focusedTopK,
         include_pending: true,
         profile: "balanced"
-      })) : Promise.resolve({
-        name: "memory_task_frame",
-        status: "skipped",
-        durationMs: 0
-      })
+      })) : Promise.resolve({ name: "memory_task_frame_focused", status: "skipped", durationMs: 0 })
     ]);
-    const branchStatus = {};
-    const collected = [];
-    let okCount = 0;
-    for (const branch of branches) {
+    const focusedCollected = collectFromBranches(focusedBranches, "focused");
+    const focusedRanked = this.rerank(focusedCollected.collected, focusedScope);
+    const focusedFloored = this.applyRelevanceFloor(focusedRanked.items);
+    let allCollected = [...focusedFloored.items];
+    let totalOkCount = focusedCollected.okCount;
+    let dedupedCount = focusedRanked.dedupedCount;
+    let droppedBelowFloor = focusedFloored.dropped;
+    const focusedTopScore = focusedFloored.items[0]?.score ?? 0;
+    const fallbackUsed = focusedFloored.items.length < this.minFocusedResults || focusedTopScore < this.minFocusedTopScore;
+    if (focusedScopeApplied) {
+      this.sourceScopedTurns += 1;
+    }
+    if (!fallbackUsed) {
+      this.focusedPassHits += 1;
+    }
+    const broadBranches = fallbackUsed ? await Promise.all([
+      this.runBranch("context_primary_broad", () => this.args.adapter.query({
+        project: scope.project,
+        query: primaryQuery,
+        top_k: this.broadTopK,
+        include_memories: false,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        max_tokens: this.maxTokens,
+        compress: true,
+        compression_strategy: "adaptive"
+      })),
+      this.runBranch("memory_primary_broad", () => this.args.adapter.searchMemories({
+        project: scope.project,
+        query: primaryQuery,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        top_k: this.broadTopK,
+        include_pending: true,
+        profile: "balanced"
+      })),
+      taskFrameQuery ? this.runBranch("context_task_frame_broad", () => this.args.adapter.query({
+        project: scope.project,
+        query: taskFrameQuery,
+        top_k: this.broadTopK,
+        include_memories: false,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        max_tokens: this.maxTokens,
+        compress: true,
+        compression_strategy: "adaptive"
+      })) : Promise.resolve({ name: "context_task_frame_broad", status: "skipped", durationMs: 0 }),
+      taskFrameQuery ? this.runBranch("memory_task_frame_broad", () => this.args.adapter.searchMemories({
+        project: scope.project,
+        query: taskFrameQuery,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        top_k: this.broadTopK,
+        include_pending: true,
+        profile: "balanced"
+      })) : Promise.resolve({ name: "memory_task_frame_broad", status: "skipped", durationMs: 0 })
+    ]) : [
+      { name: "context_primary_broad", status: "skipped", durationMs: 0 },
+      { name: "memory_primary_broad", status: "skipped", durationMs: 0 },
+      { name: "context_task_frame_broad", status: "skipped", durationMs: 0 },
+      { name: "memory_task_frame_broad", status: "skipped", durationMs: 0 }
+    ];
+    const broadCollected = collectFromBranches(broadBranches, "broad");
+    totalOkCount += broadCollected.okCount;
+    if (fallbackUsed) {
+      this.fallbackTriggers += 1;
+      this.broadScopedTurns += 1;
+      allCollected = [...allCollected, ...broadCollected.collected];
+    }
+    const ranked = this.rerank(allCollected, focusedScope);
+    dedupedCount += ranked.dedupedCount;
+    const floored = this.applyRelevanceFloor(ranked.items);
+    droppedBelowFloor += floored.dropped;
+    this.floorDroppedCount += droppedBelowFloor;
+    this.droppedCount += droppedBelowFloor;
+    const finalItems = floored.items.slice(0, this.broadTopK);
+    this.injectedItemCount += finalItems.length;
+    this.totalTurns += 1;
+    const executedBranches = [...focusedBranches, ...broadBranches].filter((branch) => branch.status !== "skipped");
+    for (const branch of [...focusedBranches, ...broadBranches]) {
       branchStatus[branch.name] = branch.status;
-      if (branch.status !== "ok") {
-        if (branch.status !== "skipped" && branch.reason) warnings.push(`${branch.name}:${branch.reason}`);
-        continue;
-      }
-      okCount += 1;
-      if (branch.name.startsWith("context")) {
-        collected.push(...this.contextItems(
-          branch.value,
-          branch.name.includes("task_frame") ? "task_frame" : "primary"
-        ));
-      } else {
-        collected.push(...this.memoryItems(
-          branch.value,
-          branch.name.includes("task_frame") ? "task_frame" : "primary"
-        ));
-      }
     }
-    const ranked = this.rerank(collected).slice(0, this.topK * 2);
     const prepared = {
       scope,
       retrieval: {
         primaryQuery,
         taskFrameQuery,
         warnings,
-        degraded: okCount < branches.filter((branch) => branch.status !== "skipped").length,
-        degradedReason: okCount === 0 ? "all_retrieval_failed" : warnings.length > 0 ? "partial_retrieval_failed" : void 0,
+        degraded: totalOkCount < executedBranches.length,
+        degradedReason: totalOkCount === 0 ? "all_retrieval_failed" : warnings.length > 0 ? "partial_retrieval_failed" : void 0,
         durationMs: Date.now() - startedAt,
         targetBudgetMs: this.targetRetrievalMs,
         hardTimeoutMs: this.hardRetrievalTimeoutMs,
-        branchStatus
+        branchStatus,
+        focusedScopeApplied,
+        focusedSourceIds: focusedScope.sourceIds,
+        focusedFileHints: focusedScope.fileHints.map((value) => pathBase(value)),
+        clientScoped: Boolean(focusedScope.clientName),
+        fallbackUsed,
+        droppedBelowFloor,
+        dedupedCount
       },
-      context: this.buildContext(ranked),
-      items: ranked
+      context: this.buildContext(finalItems),
+      items: finalItems
     };
     this.lastPreparedTurn = prepared.retrieval;
     return prepared;
@@ -1842,7 +2147,14 @@ ${lines.join("\n")}`;
       counters: {
         mergedCount: this.mergedCount,
         droppedCount: this.droppedCount,
-        bufferedLowSalience: this.bufferedLowSalience.length
+        bufferedLowSalience: this.bufferedLowSalience.length,
+        focusedPassHits: this.focusedPassHits,
+        fallbackTriggers: this.fallbackTriggers,
+        floorDroppedCount: this.floorDroppedCount,
+        injectedItemCount: this.injectedItemCount,
+        sourceScopedTurns: this.sourceScopedTurns,
+        broadScopedTurns: this.broadScopedTurns,
+        totalTurns: this.totalTurns
       }
     };
   }
@@ -2757,6 +3069,19 @@ var WhisperContext = class _WhisperContext {
       }
     ]);
   }
+  async listMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.user_id ? { user_id: params.user_id } : {},
+        ...params.session_id ? { session_id: params.session_id } : {},
+        ...params.agent_id ? { agent_id: params.agent_id } : {},
+        limit: String(Math.min(Math.max(params.limit ?? 200, 1), 200))
+      });
+      return this.request(`/v1/memories?${query.toString()}`, { method: "GET" });
+    });
+  }
   async addMemory(params) {
     const projectRef = this.getRequiredProject(params.project);
     return this.withProjectRefFallback(projectRef, async (project) => {
@@ -3421,9 +3746,10 @@ function createWhisperMcpRuntimeClient(options) {
 }
 var whisper = createWhisperMcpClient();
 var runtimeClient = createWhisperMcpRuntimeClient();
+var runtimeSessions = /* @__PURE__ */ new Map();
 var server = new McpServer({
   name: "whisper-context",
-  version: "0.2.8"
+  version: "0.3.0"
 });
 function createMcpServer() {
   return server;
@@ -3485,7 +3811,7 @@ function getWorkspaceIdForPath(path, workspaceId) {
   const seed = `${path}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12)}`;
   return createHash("sha256").update(seed).digest("hex").slice(0, 20);
 }
-function clamp01(value) {
+function clamp012(value) {
   if (Number.isNaN(value)) return 0;
   if (value < 0) return 0;
   if (value > 1) return 1;
@@ -3531,7 +3857,7 @@ function toEvidenceRef(source, workspaceId, methodFallback) {
     line_start: lineStart,
     ...lineEnd ? { line_end: lineEnd } : {},
     snippet: String(source.content || metadata.snippet || "").slice(0, 500),
-    score: clamp01(Number(source.score ?? metadata.score ?? 0)),
+    score: clamp012(Number(source.score ?? metadata.score ?? 0)),
     retrieval_method: retrievalMethod,
     indexed_at: String(metadata.indexed_at || (/* @__PURE__ */ new Date()).toISOString()),
     ...metadata.commit ? { commit: String(metadata.commit) } : {},
@@ -3606,6 +3932,21 @@ async function resolveProjectRef(explicit) {
     return void 0;
   }
 }
+async function ingestSessionWithSyncFallback(params) {
+  try {
+    return await whisper.ingestSession({
+      ...params,
+      async: false,
+      write_mode: "sync"
+    });
+  } catch (error) {
+    const message = String(error?.message || error || "").toLowerCase();
+    if (!message.includes("sync_write_restricted")) {
+      throw error;
+    }
+    return whisper.ingestSession(params);
+  }
+}
 function defaultMcpUserId() {
   const explicit = process.env.WHISPER_USER_ID?.trim();
   if (explicit) return explicit;
@@ -3625,18 +3966,55 @@ async function prepareAutomaticQuery(params) {
     throw new Error("Whisper runtime client unavailable.");
   }
   const scope = resolveMcpScope(params);
-  const runtime = runtimeClient.createAgentRuntime({
-    project: params.project,
-    userId: scope.userId,
-    sessionId: scope.sessionId,
-    workspacePath: scope.workspacePath,
-    topK: params.top_k,
-    clientName: "whisper-mcp"
-  });
+  const key = [
+    params.project || DEFAULT_PROJECT || "",
+    scope.userId,
+    scope.sessionId,
+    scope.workspacePath || process.cwd(),
+    String(params.top_k || 10)
+  ].join("|");
+  let runtime = runtimeSessions.get(key);
+  if (!runtime) {
+    runtime = runtimeClient.createAgentRuntime({
+      project: params.project,
+      userId: scope.userId,
+      sessionId: scope.sessionId,
+      workspacePath: scope.workspacePath,
+      topK: params.top_k,
+      clientName: "whisper-mcp"
+    });
+    runtimeSessions.set(key, runtime);
+  }
   return runtime.beforeTurn({
     userMessage: params.query
   });
 }
+function noteAutomaticSourceActivity(params) {
+  if (!runtimeClient) return;
+  const sourceIds = [...new Set((params.sourceIds || []).map((value) => String(value || "").trim()).filter(Boolean))];
+  if (sourceIds.length === 0) return;
+  const scope = resolveMcpScope(params);
+  const key = [
+    params.project || DEFAULT_PROJECT || "",
+    scope.userId,
+    scope.sessionId,
+    scope.workspacePath || process.cwd(),
+    String(params.top_k || 10)
+  ].join("|");
+  let runtime = runtimeSessions.get(key);
+  if (!runtime) {
+    runtime = runtimeClient.createAgentRuntime({
+      project: params.project,
+      userId: scope.userId,
+      sessionId: scope.sessionId,
+      workspacePath: scope.workspacePath,
+      topK: params.top_k,
+      clientName: "whisper-mcp"
+    });
+    runtimeSessions.set(key, runtime);
+  }
+  runtime.noteSourceActivity(sourceIds);
+}
 function buildAbstain(args) {
   return {
     status: "abstained",
@@ -4476,29 +4854,67 @@ server.tool(
       }
       const automaticMode = include_memories !== false && include_graph !== true && !(chunk_types && chunk_types.length > 0) && max_tokens === void 0 && runtimeClient;
       if (automaticMode) {
-        const prepared = await prepareAutomaticQuery({
-          project: resolvedProject,
-          query,
-          top_k,
-          user_id,
-          session_id
-        });
-        if (!prepared.items.length) {
-          return { content: [{ type: "text", text: "No relevant context found." }] };
-        }
-        const warnings = prepared.retrieval.warnings.length ? `
+        try {
+          const prepared = await prepareAutomaticQuery({
+            project: resolvedProject,
+            query,
+            top_k,
+            user_id,
+            session_id
+          });
+          if (!prepared.items.length) {
+            return { content: [{ type: "text", text: "No relevant context found." }] };
+          }
+          const warnings = prepared.retrieval.warnings.length ? `
 
 [automatic_runtime]
 ${prepared.retrieval.warnings.join("\n")}` : "";
-        const scope2 = `project=${prepared.scope.project} user=${prepared.scope.userId} session=${prepared.scope.sessionId}`;
-        return {
-          content: [{
-            type: "text",
-            text: `Found ${prepared.items.length} runtime-ranked items (${prepared.retrieval.durationMs}ms, ${scope2}):
+          const diagnostics = [
+            `focused_scope=${prepared.retrieval.focusedScopeApplied}`,
+            `fallback_used=${prepared.retrieval.fallbackUsed}`,
+            `deduped=${prepared.retrieval.dedupedCount}`,
+            `dropped_below_floor=${prepared.retrieval.droppedBelowFloor}`
+          ].join(" ");
+          const scope2 = `project=${prepared.scope.project} user=${prepared.scope.userId} session=${prepared.scope.sessionId}`;
+          return {
+            content: [{
+              type: "text",
+              text: `Found ${prepared.items.length} runtime-ranked items (${prepared.retrieval.durationMs}ms, ${scope2}, ${diagnostics}):
 
 ${prepared.context}${warnings}`
-          }]
-        };
+            }]
+          };
+        } catch (error) {
+          const automaticWarning = `Automatic runtime unavailable: ${error.message}. Falling back to broad/manual query path.`;
+          const queryResult2 = await queryWithDegradedFallback({
+            project: resolvedProject,
+            query,
+            top_k,
+            include_memories: include_memories === true,
+            include_graph,
+            user_id: user_id || resolveMcpScope({ user_id }).userId,
+            session_id: session_id || resolveMcpScope({ session_id }).sessionId
+          });
+          const response2 = queryResult2.response;
+          if (response2.results.length === 0) {
+            return { content: [{ type: "text", text: `No relevant context found.
+
+[automatic_runtime]
+${automaticWarning}` }] };
+          }
+          const scope2 = resolveMcpScope({ user_id, session_id });
+          const header2 = `Found ${response2.meta.total} results (${response2.meta.latency_ms}ms${response2.meta.cache_hit ? ", cached" : ""}, project=${resolvedProject}, user=${scope2.userId}, session=${scope2.sessionId}):
+
+`;
+          const suffix2 = queryResult2.degraded_mode ? `
+
+[degraded_mode=true] ${queryResult2.degraded_reason}
+Recommendation: ${queryResult2.recommendation}` : "";
+          return { content: [{ type: "text", text: `${header2}${response2.context}
+
+[automatic_runtime]
+${automaticWarning}${suffix2}` }] };
+        }
       }
       const queryResult = await queryWithDegradedFallback({
         project: resolvedProject,
@@ -4722,6 +5138,10 @@ server.tool(
         max_duration_minutes: input.max_duration_minutes,
         max_chunks: input.max_chunks
       });
+      noteAutomaticSourceActivity({
+        project: resolvedProject,
+        sourceIds: [result.source_id]
+      });
       return toTextResult(result);
     } catch (error) {
       return { content: [{ type: "text", text: `Error: ${error.message}` }] };
@@ -4756,8 +5176,12 @@ server.tool(
   },
   async ({ project, title, content, ingestion_profile, strategy_override, profile_config }) => {
     try {
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or provide project." }] };
+      }
       await whisper.addContext({
-        project,
+        project: resolvedProject,
         title,
         content,
         metadata: {
@@ -4810,6 +5234,11 @@ server.tool(
           strategy_override,
           profile_config
         });
+        const sourceId = result?.source_id || result?.id;
+        noteAutomaticSourceActivity({
+          project: resolvedProject,
+          sourceIds: sourceId ? [String(sourceId)] : []
+        });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
       if (!content?.trim()) {
@@ -4893,7 +5322,7 @@ server.tool(
         content: message.content,
         timestamp: message.timestamp
       }));
-      const result = await whisper.ingestSession({
+      const result = await ingestSessionWithSyncFallback({
         project: scope.project,
         session_id: scope.sessionId,
         user_id: scope.userId,
@@ -5007,8 +5436,12 @@ server.tool(
   },
   async ({ project, session_id, title, expiry_days }) => {
     try {
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or provide project." }] };
+      }
       const result = await whisper.createSharedContext({
-        project,
+        project: resolvedProject,
         session_id,
         title,
         expiry_days
@@ -5263,13 +5696,11 @@ server.tool(
       let memories = [];
       if (resolvedProject) {
         try {
-          const m = await whisper.searchMemoriesSOTA({
+          const listed = await whisper.listMemories({
             project: resolvedProject,
-            query: "memory",
-            top_k: 100,
-            include_relations: true
+            limit: 200
           });
-          memories = (m.results || []).map((r) => r.memory || r);
+          memories = Array.isArray(listed?.memories) ? listed.memories : [];
         } catch {
           memories = [];
         }
@@ -5360,7 +5791,7 @@ server.tool(
         session_summaries: 0,
         documents: 0
       };
-      const resolvedProject = await resolveProjectRef(bundle.project);
+      const resolvedProject = await resolveProjectRef(bundle.project || cachedProjectRef || DEFAULT_PROJECT || void 0);
       async function shouldSkipImportedMemory(memory) {
         if (dedupe_strategy === "none" || !resolvedProject) return false;
         const exactId = normalizeString2(memory?.id);
@@ -6244,6 +6675,10 @@ server.tool(
         max_chunks: input.max_chunks,
         auto_index: true
       });
+      noteAutomaticSourceActivity({
+        project: resolvedProject,
+        sourceIds: [result.source_id]
+      });
       return toTextResult(result);
     } catch (error) {
       return { content: [{ type: "text", text: `Error: ${error.message}` }] };
@@ -6310,7 +6745,13 @@ server.tool(
         content,
         timestamp
       });
-      const result = await whisper.ingestSession({ project, session_id, user_id, messages: normalizedMessages });
+      const resolvedProject = await resolveProjectRef(project);
+      const result = await ingestSessionWithSyncFallback({
+        project: resolvedProject,
+        session_id,
+        user_id,
+        messages: normalizedMessages
+      });
       return primaryToolSuccess({
         tool: "record",
         session_id,
@@ -6368,7 +6809,11 @@ server.tool(
   },
   async ({ project, session_id, title, expiry_days }) => {
     try {
-      const result = await whisper.createSharedContext({ project, session_id, title, expiry_days });
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        return primaryToolError("No project resolved. Set WHISPER_PROJECT or provide project.");
+      }
+      const result = await whisper.createSharedContext({ project: resolvedProject, session_id, title, expiry_days });
       return primaryToolSuccess({
         tool: "share_context",
         share_id: result.share_id,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@usewhisper/mcp-server",
-  "version": "2.5.0",
-  "whisperContractVersion": "2026.03.09",
+  "version": "2.8.0",
+  "whisperContractVersion": "2026.03.10",
   "scripts": {
     "build": "tsup ../src/mcp/server.ts --format esm --out-dir dist",
     "prepublishOnly": "npm run build"