@usewhisper/sdk 3.5.0 → 3.7.0

package/index.mjs

@@ -379,368 +379,83 @@ var RuntimeClient = class {
   }
 };
 
-// ../src/sdk/whisper-agent.ts
-var DEPRECATION_WARNINGS = /* @__PURE__ */ new Set();
-function warnDeprecatedOnce(key, message) {
-  if (DEPRECATION_WARNINGS.has(key)) return;
-  DEPRECATION_WARNINGS.add(key);
-  if (typeof console !== "undefined" && typeof console.warn === "function") {
-    console.warn(message);
+// ../src/sdk/core/cache.ts
+var SearchResponseCache = class {
+  ttlMs;
+  capacity;
+  byKey = /* @__PURE__ */ new Map();
+  scopeIndex = /* @__PURE__ */ new Map();
+  constructor(ttlMs = 7e3, capacity = 500) {
+    this.ttlMs = Math.max(1e3, ttlMs);
+    this.capacity = Math.max(10, capacity);
   }
-}
-var Whisper = class {
-  client;
-  options;
-  sessionId;
-  userId;
-  constructor(options) {
-    if (!options.apiKey) {
-      throw new Error("API key is required");
-    }
-    const clientConfig = {
-      apiKey: options.apiKey,
-      baseUrl: options.baseUrl,
-      project: options.project || "default"
-    };
-    if (options.timeoutMs) clientConfig.timeoutMs = options.timeoutMs;
-    if (options.retry) clientConfig.retry = options.retry;
-    this.client = new WhisperContext(clientConfig);
-    warnDeprecatedOnce(
-      "whisper_agent_wrapper",
-      "[Whisper SDK] Whisper wrapper is supported for v2 compatibility. Prefer WhisperClient for new integrations."
-    );
-    const finalRetry = options.retry || { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 2e3 };
-    this.options = {
-      apiKey: options.apiKey,
-      baseUrl: options.baseUrl || "https://context.usewhisper.dev",
-      project: options.project || "default",
-      timeoutMs: options.timeoutMs || 15e3,
-      retry: finalRetry,
-      contextLimit: options.contextLimit ?? 10,
-      memoryTypes: options.memoryTypes ?? ["factual", "preference", "event", "goal", "relationship", "opinion", "instruction"],
-      contextPrefix: options.contextPrefix ?? "Relevant context:",
-      autoExtract: options.autoExtract ?? true,
-      autoExtractMinConfidence: options.autoExtractMinConfidence ?? 0.65,
-      maxMemoriesPerCapture: options.maxMemoriesPerCapture ?? 5
-    };
+  makeScopeKey(project, userId, sessionId) {
+    return `${project}:${userId || "_"}:${sessionId || "_"}`;
   }
-  /**
-   * Set session ID for conversation tracking
-   */
-  session(sessionId) {
-    this.sessionId = sessionId;
-    return this;
+  makeKey(input) {
+    const normalized = {
+      project: input.project,
+      userId: input.userId || "",
+      sessionId: input.sessionId || "",
+      query: normalizeQuery(input.query),
+      topK: input.topK,
+      profile: input.profile,
+      includePending: input.includePending
+    };
+    return `search:${stableHash(JSON.stringify(normalized))}`;
   }
-  /**
-   * Set user ID for user-specific memories
-   */
-  user(userId) {
-    this.userId = userId;
-    return this;
+  get(key) {
+    const found = this.byKey.get(key);
+    if (!found) return null;
+    if (found.expiresAt <= Date.now()) {
+      this.deleteByKey(key);
+      return null;
+    }
+    found.touchedAt = Date.now();
+    return found.value;
   }
-  /**
-   * Get relevant context BEFORE your LLM call
-   * 
-   * @param query - What you want to know / user question
-   * @returns Context string and raw results
-   * 
-   * @example
-   * ```typescript
-   * const { context, results, count } = await whisper.getContext(
-   *   "What are user's preferences?",
-   *   { userId: "user-123" }
-   * );
-   * 
-   * // Results: [
-   * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
-   * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
-   * // ]
-   * ```
-   */
-  async getContext(query, options) {
-    const result = await this.client.query({
-      project: options?.project ?? this.options.project,
-      query,
-      top_k: options?.limit ?? this.options.contextLimit,
-      include_memories: true,
-      user_id: options?.userId ?? this.userId,
-      session_id: options?.sessionId ?? this.sessionId
+  set(key, scopeKey, value) {
+    this.byKey.set(key, {
+      value,
+      scopeKey,
+      touchedAt: Date.now(),
+      expiresAt: Date.now() + this.ttlMs
     });
-    const context = result.results.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
-    return {
-      context: context ? `${this.options.contextPrefix}
-${context}` : "",
-      results: result.results,
-      count: result.meta.total
-    };
+    if (!this.scopeIndex.has(scopeKey)) {
+      this.scopeIndex.set(scopeKey, /* @__PURE__ */ new Set());
+    }
+    this.scopeIndex.get(scopeKey).add(key);
+    this.evictIfNeeded();
   }
-  /**
-   * Remember what happened AFTER your LLM response
-   * 
-   * Fire-and-forget - doesn't block your response
-   * 
-   * @param content - What your LLM responded with
-   * @returns Promise that resolves when stored (or fails silently)
-   * 
-   * @example
-   * ```typescript
-   * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
-   * 
-   * await whisper.remember(llmResponse, { userId: "user-123" });
-   * // → Auto-extracts: "theme set to dark mode", "nut allergy"
-   * // → Stored as preferences
-   * ```
-   */
-  async remember(content, options) {
-    if (!content || content.length < 5) {
-      return { success: false };
+  invalidateScope(scopeKey) {
+    const keys = this.scopeIndex.get(scopeKey);
+    if (!keys || keys.size === 0) {
+      return 0;
     }
-    try {
-      if (this.options.autoExtract) {
-        const extraction = await this.client.extractMemories({
-          project: options?.project ?? this.options.project,
-          message: content,
-          user_id: options?.userId ?? this.userId,
-          session_id: options?.sessionId ?? this.sessionId,
-          enable_pattern: true,
-          enable_inference: true,
-          min_confidence: this.options.autoExtractMinConfidence
-        });
-        const extractedMemories = (extraction.all || []).filter((m) => (m.confidence || 0) >= this.options.autoExtractMinConfidence).slice(0, this.options.maxMemoriesPerCapture);
-        if (extractedMemories.length > 0) {
-          const bulk = await this.client.addMemoriesBulk({
-            project: options?.project ?? this.options.project,
-            write_mode: "async",
-            memories: extractedMemories.map((m) => ({
-              content: m.content,
-              memory_type: m.memoryType,
-              user_id: options?.userId ?? this.userId,
-              session_id: options?.sessionId ?? this.sessionId,
-              importance: Math.max(0.5, Math.min(1, m.confidence || 0.7)),
-              confidence: m.confidence || 0.7,
-              entity_mentions: m.entityMentions || [],
-              event_date: m.eventDate || void 0,
-              metadata: {
-                extracted: true,
-                extraction_method: extraction.extractionMethod,
-                extraction_reasoning: m.reasoning,
-                inferred: Boolean(m.inferred)
-              }
-            }))
-          });
-          const memoryIds = this.extractMemoryIdsFromBulkResponse(bulk);
-          return {
-            success: true,
-            memoryId: memoryIds[0],
-            memoryIds: memoryIds.length > 0 ? memoryIds : void 0,
-            extracted: extractedMemories.length
-          };
-        }
-      }
-      const result = await this.client.addMemory({
-        project: options?.project ?? this.options.project,
-        content,
-        user_id: options?.userId ?? this.userId,
-        session_id: options?.sessionId ?? this.sessionId
-      });
-      return {
-        success: true,
-        memoryId: result?.id
-      };
-    } catch (error) {
-      console.error("[Whisper] Remember failed:", error);
-      return { success: false };
+    const toDelete = Array.from(keys);
+    for (const key of toDelete) {
+      this.deleteByKey(key);
     }
+    this.scopeIndex.delete(scopeKey);
+    return toDelete.length;
   }
-  /**
-   * Alias for remember() - same thing
-   */
-  async capture(content, options) {
-    return this.remember(content, options);
+  evictIfNeeded() {
+    if (this.byKey.size <= this.capacity) return;
+    const ordered = Array.from(this.byKey.entries()).sort((a, b) => a[1].touchedAt - b[1].touchedAt);
+    const removeCount = this.byKey.size - this.capacity;
+    for (let i = 0; i < removeCount; i += 1) {
+      this.deleteByKey(ordered[i][0]);
+    }
   }
-  /**
-   * Capture from multiple messages (e.g., full conversation)
-   */
-  async captureSession(messages, options) {
-    try {
-      const result = await this.client.ingestSession({
-        project: options?.project ?? this.options.project,
-        session_id: options?.sessionId ?? this.sessionId ?? "default",
-        user_id: options?.userId ?? this.userId,
-        messages: messages.filter((m) => m.role !== "system").map((m) => ({
-          role: m.role,
-          content: m.content,
-          timestamp: (/* @__PURE__ */ new Date()).toISOString()
-        }))
-      });
-      return {
-        success: true,
-        extracted: result?.memories_created ?? 0
-      };
-    } catch (error) {
-      const fallback = await this.fallbackCaptureViaAddMemory(messages, options);
-      if (fallback.success) {
-        return fallback;
-      }
-      console.error("[Whisper] Session capture failed:", error);
-      return { success: false, extracted: 0 };
-    }
-  }
-  /**
-   * Run a full agent turn with automatic memory read (before) + write (after).
-   */
-  async runTurn(params) {
-    const contextResult = await this.getContext(params.userMessage, {
-      userId: params.userId,
-      sessionId: params.sessionId,
-      project: params.project,
-      limit: params.limit
-    });
-    const prompt = contextResult.context ? `${contextResult.context}
-
-User: ${params.userMessage}` : params.userMessage;
-    const response = await params.generate(prompt);
-    const captureResult = await this.captureSession(
-      [
-        { role: "user", content: params.userMessage },
-        { role: "assistant", content: response }
-      ],
-      {
-        userId: params.userId,
-        sessionId: params.sessionId,
-        project: params.project
-      }
-    );
-    return {
-      response,
-      context: contextResult.context,
-      count: contextResult.count,
-      extracted: captureResult.extracted
-    };
-  }
-  /**
-   * Direct access to WhisperContext for advanced usage
-   */
-  raw() {
-    return this.client;
-  }
-  extractMemoryIdsFromBulkResponse(bulkResponse) {
-    const ids = [];
-    if (Array.isArray(bulkResponse?.memories)) {
-      for (const memory of bulkResponse.memories) {
-        if (memory?.id) ids.push(memory.id);
-      }
-    }
-    if (bulkResponse?.memory?.id) {
-      ids.push(bulkResponse.memory.id);
-    }
-    if (bulkResponse?.id) {
-      ids.push(bulkResponse.id);
-    }
-    return Array.from(new Set(ids));
-  }
-  async fallbackCaptureViaAddMemory(messages, options) {
-    const userMessages = messages.filter((m) => m.role === "user").map((m) => (m.content || "").trim()).filter((content) => content.length >= 5).slice(-2);
-    if (userMessages.length === 0) {
-      return { success: false, extracted: 0 };
-    }
-    let extracted = 0;
-    for (const content of userMessages) {
-      try {
-        await this.client.addMemory({
-          project: options?.project ?? this.options.project,
-          content,
-          memory_type: "factual",
-          user_id: options?.userId ?? this.userId,
-          session_id: options?.sessionId ?? this.sessionId,
-          allow_legacy_fallback: true
-        });
-        extracted += 1;
-      } catch {
-      }
-    }
-    return { success: extracted > 0, extracted };
-  }
-};
-var whisper_agent_default = Whisper;
-
-// ../src/sdk/core/cache.ts
-var SearchResponseCache = class {
-  ttlMs;
-  capacity;
-  byKey = /* @__PURE__ */ new Map();
-  scopeIndex = /* @__PURE__ */ new Map();
-  constructor(ttlMs = 7e3, capacity = 500) {
-    this.ttlMs = Math.max(1e3, ttlMs);
-    this.capacity = Math.max(10, capacity);
-  }
-  makeScopeKey(project, userId, sessionId) {
-    return `${project}:${userId || "_"}:${sessionId || "_"}`;
-  }
-  makeKey(input) {
-    const normalized = {
-      project: input.project,
-      userId: input.userId || "",
-      sessionId: input.sessionId || "",
-      query: normalizeQuery(input.query),
-      topK: input.topK,
-      profile: input.profile,
-      includePending: input.includePending
-    };
-    return `search:${stableHash(JSON.stringify(normalized))}`;
-  }
-  get(key) {
-    const found = this.byKey.get(key);
-    if (!found) return null;
-    if (found.expiresAt <= Date.now()) {
-      this.deleteByKey(key);
-      return null;
-    }
-    found.touchedAt = Date.now();
-    return found.value;
-  }
-  set(key, scopeKey, value) {
-    this.byKey.set(key, {
-      value,
-      scopeKey,
-      touchedAt: Date.now(),
-      expiresAt: Date.now() + this.ttlMs
-    });
-    if (!this.scopeIndex.has(scopeKey)) {
-      this.scopeIndex.set(scopeKey, /* @__PURE__ */ new Set());
-    }
-    this.scopeIndex.get(scopeKey).add(key);
-    this.evictIfNeeded();
-  }
-  invalidateScope(scopeKey) {
-    const keys = this.scopeIndex.get(scopeKey);
-    if (!keys || keys.size === 0) {
-      return 0;
-    }
-    const toDelete = Array.from(keys);
-    for (const key of toDelete) {
-      this.deleteByKey(key);
-    }
-    this.scopeIndex.delete(scopeKey);
-    return toDelete.length;
-  }
-  evictIfNeeded() {
-    if (this.byKey.size <= this.capacity) return;
-    const ordered = Array.from(this.byKey.entries()).sort((a, b) => a[1].touchedAt - b[1].touchedAt);
-    const removeCount = this.byKey.size - this.capacity;
-    for (let i = 0; i < removeCount; i += 1) {
-      this.deleteByKey(ordered[i][0]);
-    }
-  }
-  deleteByKey(key) {
-    const found = this.byKey.get(key);
-    if (!found) return;
-    this.byKey.delete(key);
-    const scopeKeys = this.scopeIndex.get(found.scopeKey);
-    if (!scopeKeys) return;
-    scopeKeys.delete(key);
-    if (scopeKeys.size === 0) {
-      this.scopeIndex.delete(found.scopeKey);
+  deleteByKey(key) {
+    const found = this.byKey.get(key);
+    if (!found) return;
+    this.byKey.delete(key);
+    const scopeKeys = this.scopeIndex.get(found.scopeKey);
+    if (!scopeKeys) return;
+    scopeKeys.delete(key);
+    if (scopeKeys.size === 0) {
+      this.scopeIndex.delete(found.scopeKey);
     }
   }
 };
@@ -1638,6 +1353,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(() => {
@@ -1671,39 +1409,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) {
@@ -1721,6 +1496,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}`);
@@ -1797,23 +1630,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 || {},
@@ -1821,22 +1660,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;
@@ -1875,7 +1791,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,
@@ -1893,7 +1809,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 || [];
@@ -1903,10 +1819,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: {
@@ -1918,7 +1836,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
@@ -1927,100 +1852,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;
@@ -2115,7 +2135,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
       }
     };
   }
@@ -2333,165 +2360,469 @@ var WhisperClient = class _WhisperClient {
         retryable: false
       });
     }
-    return resolved;
+    return resolved;
+  }
+  async refreshProjectCache(force = false) {
+    if (!force && Date.now() < this.projectCacheExpiresAt && this.projectCache.length > 0) {
+      return this.projectCache;
+    }
+    const response = await this.runtimeClient.request({
+      endpoint: "/v1/projects",
+      method: "GET",
+      operation: "get",
+      idempotent: true
+    });
+    this.projectRefToId.clear();
+    this.projectCache = response.data?.projects || [];
+    for (const project of this.projectCache) {
+      this.projectRefToId.set(project.id, project.id);
+      this.projectRefToId.set(project.slug, project.id);
+      this.projectRefToId.set(project.name, project.id);
+    }
+    this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+    return this.projectCache;
+  }
+  async fetchResolvedProject(projectRef) {
+    try {
+      const response = await this.runtimeClient.request({
+        endpoint: `/v1/projects/resolve?project=${encodeURIComponent(projectRef)}`,
+        method: "GET",
+        operation: "get",
+        idempotent: true
+      });
+      return response.data?.resolved || null;
+    } catch (error) {
+      if (error instanceof RuntimeClientError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async resolveProject(projectRef) {
+    const resolvedRef = this.getRequiredProject(projectRef);
+    const cachedProjects = await this.refreshProjectCache(false);
+    const cachedProject = cachedProjects.find(
+      (project) => project.id === resolvedRef || project.slug === resolvedRef || project.name === resolvedRef
+    );
+    if (cachedProject) {
+      return cachedProject;
+    }
+    const resolvedProject = await this.fetchResolvedProject(resolvedRef);
+    if (resolvedProject) {
+      this.projectRefToId.set(resolvedProject.id, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.slug, resolvedProject.id);
+      this.projectRefToId.set(resolvedProject.name, resolvedProject.id);
+      this.projectCache = [
+        ...this.projectCache.filter((project) => project.id !== resolvedProject.id),
+        resolvedProject
+      ];
+      this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
+      return resolvedProject;
+    }
+    if (isLikelyProjectId(resolvedRef)) {
+      return {
+        id: resolvedRef,
+        orgId: "",
+        name: resolvedRef,
+        slug: resolvedRef,
+        createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date(0)).toISOString()
+      };
+    }
+    throw new RuntimeClientError({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project '${resolvedRef}' not found`,
+      retryable: false
+    });
+  }
+  async query(params) {
+    const project = (await this.resolveProject(params.project)).id;
+    const response = await this.runtimeClient.request({
+      endpoint: "/v1/context/query",
+      method: "POST",
+      operation: "search",
+      body: {
+        ...params,
+        project
+      },
+      idempotent: true
+    });
+    return response.data;
+  }
+  async ingestSession(params) {
+    const project = (await this.resolveProject(params.project)).id;
+    const response = await this.runtimeClient.request({
+      endpoint: "/v1/memory/ingest/session",
+      method: "POST",
+      operation: "session",
+      body: {
+        ...params,
+        project
+      }
+    });
+    return response.data;
+  }
+  createAgentRuntime(options = {}) {
+    const baseContext = {
+      workspacePath: options.workspacePath,
+      project: options.project || this.config.project,
+      userId: options.userId,
+      sessionId: options.sessionId,
+      traceId: options.traceId,
+      clientName: options.clientName
+    };
+    return new WhisperAgentRuntime({
+      baseContext,
+      options,
+      adapter: {
+        resolveProject: (project) => this.resolveProject(project),
+        query: (params) => this.query(params),
+        ingestSession: (params) => this.ingestSession(params),
+        getSessionMemories: (params) => this.memory.getSessionMemories(params),
+        getUserProfile: (params) => this.memory.getUserProfile(params),
+        searchMemories: (params) => this.memory.search(params),
+        addMemory: (params) => this.memory.add(params),
+        queueStatus: () => this.queue.status(),
+        flushQueue: () => this.queue.flush()
+      }
+    });
+  }
+  withRunContext(context) {
+    const base = this;
+    return {
+      memory: {
+        add: (params) => base.memory.add({
+          ...params,
+          project: params.project || context.project || base.config.project,
+          user_id: params.user_id || context.userId,
+          session_id: params.session_id || context.sessionId
+        }),
+        search: (params) => base.memory.search({
+          ...params,
+          project: params.project || context.project || base.config.project,
+          user_id: params.user_id || context.userId,
+          session_id: params.session_id || context.sessionId
+        })
+      },
+      session: {
+        event: (params) => base.session.event({
+          ...params,
+          sessionId: params.sessionId || context.sessionId || ""
+        })
+      },
+      queue: base.queue,
+      diagnostics: base.diagnostics
+    };
+  }
+  async shutdown() {
+    await this.writeQueue.stop();
+  }
+};
+var whisper_default = WhisperClient;
+
+// ../src/sdk/whisper-agent.ts
+var DEPRECATION_WARNINGS = /* @__PURE__ */ new Set();
+function warnDeprecatedOnce(key, message) {
+  if (DEPRECATION_WARNINGS.has(key)) return;
+  DEPRECATION_WARNINGS.add(key);
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(message);
+  }
+}
+var Whisper = class {
+  client;
+  runtimeClient;
+  options;
+  sessionId;
+  userId;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    const clientConfig = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      project: options.project || "default"
+    };
+    if (options.timeoutMs) clientConfig.timeoutMs = options.timeoutMs;
+    if (options.retry) clientConfig.retry = options.retry;
+    this.client = new WhisperContext(clientConfig);
+    this.runtimeClient = new WhisperClient({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      project: options.project || "default"
+    });
+    warnDeprecatedOnce(
+      "whisper_agent_wrapper",
+      "[Whisper SDK] Whisper wrapper is supported for v2 compatibility. Prefer WhisperClient for new integrations."
+    );
+    const finalRetry = options.retry || { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 2e3 };
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://context.usewhisper.dev",
+      project: options.project || "default",
+      timeoutMs: options.timeoutMs || 15e3,
+      retry: finalRetry,
+      contextLimit: options.contextLimit ?? 10,
+      memoryTypes: options.memoryTypes ?? ["factual", "preference", "event", "goal", "relationship", "opinion", "instruction"],
+      contextPrefix: options.contextPrefix ?? "Relevant context:",
+      autoExtract: options.autoExtract ?? true,
+      autoExtractMinConfidence: options.autoExtractMinConfidence ?? 0.65,
+      maxMemoriesPerCapture: options.maxMemoriesPerCapture ?? 5
+    };
+  }
+  /**
+   * Set session ID for conversation tracking
+   */
+  session(sessionId) {
+    this.sessionId = sessionId;
+    return this;
+  }
+  /**
+   * Set user ID for user-specific memories
+   */
+  user(userId) {
+    this.userId = userId;
+    return this;
+  }
+  /**
+   * Get relevant context BEFORE your LLM call
+   * 
+   * @param query - What you want to know / user question
+   * @returns Context string and raw results
+   * 
+   * @example
+   * ```typescript
+   * const { context, results, count } = await whisper.getContext(
+   *   "What are user's preferences?",
+   *   { userId: "user-123" }
+   * );
+   * 
+   * // Results: [
+   * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+   * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+   * // ]
+   * ```
+   */
+  async getContext(query, options) {
+    const runtime = this.runtimeClient.createAgentRuntime({
+      project: options?.project ?? this.options.project,
+      userId: options?.userId ?? this.userId,
+      sessionId: options?.sessionId ?? this.sessionId,
+      topK: options?.limit ?? this.options.contextLimit,
+      clientName: "whisper-wrapper"
+    });
+    const prepared = await runtime.beforeTurn({
+      userMessage: query
+    });
+    const results = prepared.items.map((item, index) => ({
+      id: item.id || `runtime_${index}`,
+      content: item.content,
+      score: item.score,
+      metadata: item.metadata || {},
+      source: item.type === "memory" ? "memory" : "runtime",
+      document: item.sourceQuery,
+      type: item.type,
+      retrieval_source: item.type === "memory" ? "memory" : "runtime"
+    }));
+    const context = results.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
+    return {
+      context: context ? `${this.options.contextPrefix}
+${context}` : "",
+      results,
+      count: prepared.items.length
+    };
+  }
+  /**
+   * Remember what happened AFTER your LLM response
+   * 
+   * Fire-and-forget - doesn't block your response
+   * 
+   * @param content - What your LLM responded with
+   * @returns Promise that resolves when stored (or fails silently)
+   * 
+   * @example
+   * ```typescript
+   * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+   * 
+   * await whisper.remember(llmResponse, { userId: "user-123" });
+   * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+   * // → Stored as preferences
+   * ```
+   */
+  async remember(content, options) {
+    if (!content || content.length < 5) {
+      return { success: false };
+    }
+    try {
+      if (this.options.autoExtract) {
+        const extraction = await this.client.extractMemories({
+          project: options?.project ?? this.options.project,
+          message: content,
+          user_id: options?.userId ?? this.userId,
+          session_id: options?.sessionId ?? this.sessionId,
+          enable_pattern: true,
+          enable_inference: true,
+          min_confidence: this.options.autoExtractMinConfidence
+        });
+        const extractedMemories = (extraction.all || []).filter((m) => (m.confidence || 0) >= this.options.autoExtractMinConfidence).slice(0, this.options.maxMemoriesPerCapture);
+        if (extractedMemories.length > 0) {
+          const bulk = await this.client.addMemoriesBulk({
+            project: options?.project ?? this.options.project,
+            write_mode: "async",
+            memories: extractedMemories.map((m) => ({
+              content: m.content,
+              memory_type: m.memoryType,
+              user_id: options?.userId ?? this.userId,
+              session_id: options?.sessionId ?? this.sessionId,
+              importance: Math.max(0.5, Math.min(1, m.confidence || 0.7)),
+              confidence: m.confidence || 0.7,
+              entity_mentions: m.entityMentions || [],
+              event_date: m.eventDate || void 0,
+              metadata: {
+                extracted: true,
+                extraction_method: extraction.extractionMethod,
+                extraction_reasoning: m.reasoning,
+                inferred: Boolean(m.inferred)
+              }
+            }))
+          });
+          const memoryIds = this.extractMemoryIdsFromBulkResponse(bulk);
+          return {
+            success: true,
+            memoryId: memoryIds[0],
+            memoryIds: memoryIds.length > 0 ? memoryIds : void 0,
+            extracted: extractedMemories.length
+          };
+        }
+      }
+      const result = await this.client.addMemory({
+        project: options?.project ?? this.options.project,
+        content,
+        user_id: options?.userId ?? this.userId,
+        session_id: options?.sessionId ?? this.sessionId
+      });
+      return {
+        success: true,
+        memoryId: result?.id
+      };
+    } catch (error) {
+      console.error("[Whisper] Remember failed:", error);
+      return { success: false };
+    }
   }
-  async refreshProjectCache(force = false) {
-    if (!force && Date.now() < this.projectCacheExpiresAt && this.projectCache.length > 0) {
-      return this.projectCache;
-    }
-    const response = await this.runtimeClient.request({
-      endpoint: "/v1/projects",
-      method: "GET",
-      operation: "get",
-      idempotent: true
-    });
-    this.projectRefToId.clear();
-    this.projectCache = response.data?.projects || [];
-    for (const project of this.projectCache) {
-      this.projectRefToId.set(project.id, project.id);
-      this.projectRefToId.set(project.slug, project.id);
-      this.projectRefToId.set(project.name, project.id);
-    }
-    this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
-    return this.projectCache;
+  /**
+   * Alias for remember() - same thing
+   */
+  async capture(content, options) {
+    return this.remember(content, options);
   }
-  async fetchResolvedProject(projectRef) {
+  /**
+   * Capture from multiple messages (e.g., full conversation)
+   */
+  async captureSession(messages, options) {
     try {
-      const response = await this.runtimeClient.request({
-        endpoint: `/v1/projects/resolve?project=${encodeURIComponent(projectRef)}`,
-        method: "GET",
-        operation: "get",
-        idempotent: true
+      const filteredMessages = messages.filter((m) => m.role !== "system");
+      const runtime = this.runtimeClient.createAgentRuntime({
+        project: options?.project ?? this.options.project,
+        userId: options?.userId ?? this.userId,
+        sessionId: options?.sessionId ?? this.sessionId ?? "default",
+        clientName: "whisper-wrapper"
       });
-      return response.data?.resolved || null;
+      const result = await runtime.afterTurn({
+        userMessage: [...filteredMessages].reverse().find((m) => m.role === "user")?.content || "",
+        assistantMessage: [...filteredMessages].reverse().find((m) => m.role === "assistant")?.content || ""
+      });
+      return {
+        success: true,
+        extracted: result.memoriesCreated ?? 0
+      };
     } catch (error) {
-      if (error instanceof RuntimeClientError && error.status === 404) {
-        return null;
+      const fallback = await this.fallbackCaptureViaAddMemory(messages, options);
+      if (fallback.success) {
+        return fallback;
       }
-      throw error;
+      console.error("[Whisper] Session capture failed:", error);
+      return { success: false, extracted: 0 };
     }
   }
-  async resolveProject(projectRef) {
-    const resolvedRef = this.getRequiredProject(projectRef);
-    const cachedProjects = await this.refreshProjectCache(false);
-    const cachedProject = cachedProjects.find(
-      (project) => project.id === resolvedRef || project.slug === resolvedRef || project.name === resolvedRef
-    );
-    if (cachedProject) {
-      return cachedProject;
-    }
-    const resolvedProject = await this.fetchResolvedProject(resolvedRef);
-    if (resolvedProject) {
-      this.projectRefToId.set(resolvedProject.id, resolvedProject.id);
-      this.projectRefToId.set(resolvedProject.slug, resolvedProject.id);
-      this.projectRefToId.set(resolvedProject.name, resolvedProject.id);
-      this.projectCache = [
-        ...this.projectCache.filter((project) => project.id !== resolvedProject.id),
-        resolvedProject
-      ];
-      this.projectCacheExpiresAt = Date.now() + PROJECT_CACHE_TTL_MS;
-      return resolvedProject;
-    }
-    if (isLikelyProjectId(resolvedRef)) {
-      return {
-        id: resolvedRef,
-        orgId: "",
-        name: resolvedRef,
-        slug: resolvedRef,
-        createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
-        updatedAt: (/* @__PURE__ */ new Date(0)).toISOString()
-      };
-    }
-    throw new RuntimeClientError({
-      code: "PROJECT_NOT_FOUND",
-      message: `Project '${resolvedRef}' not found`,
-      retryable: false
+  /**
+   * Run a full agent turn with automatic memory read (before) + write (after).
+   */
+  async runTurn(params) {
+    const contextResult = await this.getContext(params.userMessage, {
+      userId: params.userId,
+      sessionId: params.sessionId,
+      project: params.project,
+      limit: params.limit
     });
+    const prompt = contextResult.context ? `${contextResult.context}
+
+User: ${params.userMessage}` : params.userMessage;
+    const response = await params.generate(prompt);
+    const captureResult = await this.captureSession(
+      [
+        { role: "user", content: params.userMessage },
+        { role: "assistant", content: response }
+      ],
+      {
+        userId: params.userId,
+        sessionId: params.sessionId,
+        project: params.project
+      }
+    );
+    return {
+      response,
+      context: contextResult.context,
+      count: contextResult.count,
+      extracted: captureResult.extracted
+    };
   }
-  async query(params) {
-    const project = (await this.resolveProject(params.project)).id;
-    const response = await this.runtimeClient.request({
-      endpoint: "/v1/context/query",
-      method: "POST",
-      operation: "search",
-      body: {
-        ...params,
-        project
-      },
-      idempotent: true
-    });
-    return response.data;
+  /**
+   * Direct access to WhisperContext for advanced usage
+   */
+  raw() {
+    return this.client;
   }
-  async ingestSession(params) {
-    const project = (await this.resolveProject(params.project)).id;
-    const response = await this.runtimeClient.request({
-      endpoint: "/v1/memory/ingest/session",
-      method: "POST",
-      operation: "session",
-      body: {
-        ...params,
-        project
+  extractMemoryIdsFromBulkResponse(bulkResponse) {
+    const ids = [];
+    if (Array.isArray(bulkResponse?.memories)) {
+      for (const memory of bulkResponse.memories) {
+        if (memory?.id) ids.push(memory.id);
       }
-    });
-    return response.data;
+    }
+    if (bulkResponse?.memory?.id) {
+      ids.push(bulkResponse.memory.id);
+    }
+    if (bulkResponse?.id) {
+      ids.push(bulkResponse.id);
+    }
+    return Array.from(new Set(ids));
   }
-  createAgentRuntime(options = {}) {
-    const baseContext = {
-      workspacePath: options.workspacePath,
-      project: options.project || this.config.project,
-      userId: options.userId,
-      sessionId: options.sessionId,
-      traceId: options.traceId,
-      clientName: options.clientName
-    };
-    return new WhisperAgentRuntime({
-      baseContext,
-      options,
-      adapter: {
-        resolveProject: (project) => this.resolveProject(project),
-        query: (params) => this.query(params),
-        ingestSession: (params) => this.ingestSession(params),
-        getSessionMemories: (params) => this.memory.getSessionMemories(params),
-        getUserProfile: (params) => this.memory.getUserProfile(params),
-        searchMemories: (params) => this.memory.search(params),
-        addMemory: (params) => this.memory.add(params),
-        queueStatus: () => this.queue.status(),
-        flushQueue: () => this.queue.flush()
+  async fallbackCaptureViaAddMemory(messages, options) {
+    const userMessages = messages.filter((m) => m.role === "user").map((m) => (m.content || "").trim()).filter((content) => content.length >= 5).slice(-2);
+    if (userMessages.length === 0) {
+      return { success: false, extracted: 0 };
+    }
+    let extracted = 0;
+    for (const content of userMessages) {
+      try {
+        await this.client.addMemory({
+          project: options?.project ?? this.options.project,
+          content,
+          memory_type: "factual",
+          user_id: options?.userId ?? this.userId,
+          session_id: options?.sessionId ?? this.sessionId,
+          allow_legacy_fallback: true
+        });
+        extracted += 1;
+      } catch {
       }
-    });
-  }
-  withRunContext(context) {
-    const base = this;
-    return {
-      memory: {
-        add: (params) => base.memory.add({
-          ...params,
-          project: params.project || context.project || base.config.project,
-          user_id: params.user_id || context.userId,
-          session_id: params.session_id || context.sessionId
-        }),
-        search: (params) => base.memory.search({
-          ...params,
-          project: params.project || context.project || base.config.project,
-          user_id: params.user_id || context.userId,
-          session_id: params.session_id || context.sessionId
-        })
-      },
-      session: {
-        event: (params) => base.session.event({
-          ...params,
-          sessionId: params.sessionId || context.sessionId || ""
-        })
-      },
-      queue: base.queue,
-      diagnostics: base.diagnostics
-    };
-  }
-  async shutdown() {
-    await this.writeQueue.stop();
+    }
+    return { success: extracted > 0, extracted };
   }
 };
-var whisper_default = WhisperClient;
+var whisper_agent_default = Whisper;
 
 // ../src/sdk/middleware.ts
 var WhisperAgentMiddleware = class {