@usewhisper/mcp-server 0.4.0 → 0.5.0

package/dist/server.js

@@ -5,8 +5,374 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { execSync, spawnSync } from "child_process";
-import { readdirSync, readFileSync, statSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from "fs";
 import { join, relative, extname } from "path";
+import { homedir } from "os";
+import { createHash, randomUUID } from "crypto";
+
+// ../src/sdk/core/telemetry.ts
+var DiagnosticsStore = class {
+  maxEntries;
+  records = [];
+  subscribers = /* @__PURE__ */ new Set();
+  constructor(maxEntries = 1e3) {
+    this.maxEntries = Math.max(1, maxEntries);
+  }
+  add(record) {
+    this.records.push(record);
+    if (this.records.length > this.maxEntries) {
+      this.records.splice(0, this.records.length - this.maxEntries);
+    }
+    for (const fn of this.subscribers) {
+      try {
+        fn(record);
+      } catch {
+      }
+    }
+  }
+  getLast(limit = 25) {
+    const count = Math.max(1, limit);
+    return this.records.slice(-count);
+  }
+  snapshot() {
+    const total = this.records.length;
+    const success = this.records.filter((r) => r.success).length;
+    const failure = total - success;
+    const duration = this.records.reduce((acc, item) => acc + item.durationMs, 0);
+    return {
+      total,
+      success,
+      failure,
+      avgDurationMs: total > 0 ? duration / total : 0,
+      lastTraceId: this.records[this.records.length - 1]?.traceId
+    };
+  }
+  subscribe(fn) {
+    this.subscribers.add(fn);
+    return () => {
+      this.subscribers.delete(fn);
+    };
+  }
+};
+
+// ../src/sdk/core/utils.ts
+function normalizeBaseUrl(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  normalized = normalized.replace(/\/api\/v1$/i, "");
+  normalized = normalized.replace(/\/v1$/i, "");
+  normalized = normalized.replace(/\/api$/i, "");
+  return normalized;
+}
+function normalizeEndpoint(endpoint) {
+  const withLeadingSlash = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  if (/^\/api\/v1(\/|$)/i.test(withLeadingSlash)) {
+    return withLeadingSlash.replace(/^\/api/i, "");
+  }
+  return withLeadingSlash;
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function stableHash(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function randomId(prefix = "id") {
+  return `${prefix}_${stableHash(`${Date.now()}_${Math.random()}`)}`;
+}
+
+// ../src/sdk/core/client.ts
+var DEFAULT_TIMEOUTS = {
+  searchMs: 3e3,
+  writeAckMs: 2e3,
+  bulkMs: 1e4,
+  profileMs: 2500,
+  sessionMs: 2500
+};
+var DEFAULT_RETRYABLE_STATUS = [408, 429, 500, 502, 503, 504];
+var DEFAULT_RETRY_ATTEMPTS = {
+  search: 3,
+  writeAck: 2,
+  bulk: 2,
+  profile: 2,
+  session: 2,
+  query: 3,
+  get: 2
+};
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function toMessage(payload, status, statusText) {
+  if (typeof payload === "string" && payload.trim()) return payload;
+  if (isObject(payload)) {
+    const maybeError = payload.error;
+    const maybeMessage = payload.message;
+    if (typeof maybeError === "string" && maybeError.trim()) return maybeError;
+    if (typeof maybeMessage === "string" && maybeMessage.trim()) return maybeMessage;
+    if (isObject(maybeError) && typeof maybeError.message === "string") return maybeError.message;
+  }
+  return `HTTP ${status}: ${statusText}`;
+}
+var RuntimeClientError = class extends Error {
+  status;
+  retryable;
+  code;
+  details;
+  traceId;
+  constructor(args) {
+    super(args.message);
+    this.name = "RuntimeClientError";
+    this.status = args.status;
+    this.retryable = args.retryable;
+    this.code = args.code;
+    this.details = args.details;
+    this.traceId = args.traceId;
+  }
+};
+var RuntimeClient = class {
+  apiKey;
+  baseUrl;
+  sdkVersion;
+  compatMode;
+  retryPolicy;
+  timeouts;
+  diagnostics;
+  inFlight = /* @__PURE__ */ new Map();
+  sendApiKeyHeader;
+  constructor(options, diagnostics) {
+    if (!options.apiKey) {
+      throw new RuntimeClientError({
+        code: "INVALID_API_KEY",
+        message: "API key is required",
+        retryable: false
+      });
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl || "https://context.usewhisper.dev");
+    this.sdkVersion = options.sdkVersion || "2.x-runtime";
+    this.compatMode = options.compatMode || "fallback";
+    this.retryPolicy = {
+      retryableStatusCodes: options.retryPolicy?.retryableStatusCodes || DEFAULT_RETRYABLE_STATUS,
+      retryOnNetworkError: options.retryPolicy?.retryOnNetworkError ?? true,
+      maxBackoffMs: options.retryPolicy?.maxBackoffMs ?? 1200,
+      baseBackoffMs: options.retryPolicy?.baseBackoffMs ?? 250,
+      maxAttemptsByOperation: options.retryPolicy?.maxAttemptsByOperation || {}
+    };
+    this.timeouts = {
+      ...DEFAULT_TIMEOUTS,
+      ...options.timeouts || {}
+    };
+    this.sendApiKeyHeader = process.env.WHISPER_SEND_X_API_KEY === "1";
+    this.diagnostics = diagnostics || new DiagnosticsStore(1e3);
+  }
+  getDiagnosticsStore() {
+    return this.diagnostics;
+  }
+  getCompatMode() {
+    return this.compatMode;
+  }
+  timeoutFor(operation) {
+    switch (operation) {
+      case "search":
+        return this.timeouts.searchMs;
+      case "writeAck":
+        return this.timeouts.writeAckMs;
+      case "bulk":
+        return this.timeouts.bulkMs;
+      case "profile":
+        return this.timeouts.profileMs;
+      case "session":
+        return this.timeouts.sessionMs;
+      case "query":
+      case "get":
+      default:
+        return this.timeouts.searchMs;
+    }
+  }
+  maxAttemptsFor(operation) {
+    const override = this.retryPolicy.maxAttemptsByOperation?.[operation];
+    return Math.max(1, override ?? DEFAULT_RETRY_ATTEMPTS[operation]);
+  }
+  shouldRetryStatus(status) {
+    return status !== void 0 && this.retryPolicy.retryableStatusCodes?.includes(status) === true;
+  }
+  backoff(attempt) {
+    const base = this.retryPolicy.baseBackoffMs ?? 250;
+    const max = this.retryPolicy.maxBackoffMs ?? 1200;
+    const jitter = 0.8 + Math.random() * 0.4;
+    return Math.min(max, Math.floor(base * Math.pow(2, attempt) * jitter));
+  }
+  runtimeName() {
+    const maybeWindow = globalThis.window;
+    return maybeWindow && typeof maybeWindow === "object" ? "browser" : "node";
+  }
+  createRequestFingerprint(options) {
+    const normalizedEndpoint = normalizeEndpoint(options.endpoint);
+    const authFingerprint = stableHash(this.apiKey.replace(/^Bearer\s+/i, ""));
+    const payload = JSON.stringify({
+      method: options.method || "GET",
+      endpoint: normalizedEndpoint,
+      body: options.body || null,
+      extra: options.dedupeKeyExtra || "",
+      authFingerprint
+    });
+    return stableHash(payload);
+  }
+  async request(options) {
+    const dedupeKey = options.idempotent ? this.createRequestFingerprint(options) : null;
+    if (dedupeKey) {
+      const inFlight = this.inFlight.get(dedupeKey);
+      if (inFlight) {
+        const data = await inFlight;
+        this.diagnostics.add({
+          id: randomId("diag"),
+          startedAt: nowIso(),
+          endedAt: nowIso(),
+          traceId: data.traceId,
+          spanId: randomId("span"),
+          operation: options.operation,
+          method: options.method || "GET",
+          endpoint: normalizeEndpoint(options.endpoint),
+          status: data.status,
+          durationMs: 0,
+          success: true,
+          deduped: true
+        });
+        const cloned = {
+          data: data.data,
+          status: data.status,
+          traceId: data.traceId
+        };
+        return cloned;
+      }
+    }
+    const runner = this.performRequest(options).then((data) => {
+      if (dedupeKey) this.inFlight.delete(dedupeKey);
+      return data;
+    }).catch((error) => {
+      if (dedupeKey) this.inFlight.delete(dedupeKey);
+      throw error;
+    });
+    if (dedupeKey) {
+      this.inFlight.set(dedupeKey, runner);
+    }
+    return runner;
+  }
+  async performRequest(options) {
+    const method = options.method || "GET";
+    const normalizedEndpoint = normalizeEndpoint(options.endpoint);
+    const operation = options.operation;
+    const maxAttempts = this.maxAttemptsFor(operation);
+    const timeoutMs = this.timeoutFor(operation);
+    const traceId = options.traceId || randomId("trace");
+    let lastError = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const spanId = randomId("span");
+      const startedAt = Date.now();
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
+          method,
+          signal: controller.signal,
+          keepalive: method !== "GET",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`,
+            ...this.sendApiKeyHeader ? { "X-API-Key": this.apiKey.replace(/^Bearer\s+/i, "") } : {},
+            "x-trace-id": traceId,
+            "x-span-id": spanId,
+            "x-sdk-version": this.sdkVersion,
+            "x-sdk-runtime": this.runtimeName(),
+            ...options.headers || {}
+          },
+          body: method === "GET" || method === "DELETE" ? void 0 : JSON.stringify(options.body || {})
+        });
+        clearTimeout(timeout);
+        let payload = null;
+        try {
+          payload = await response.json();
+        } catch {
+          payload = await response.text().catch(() => "");
+        }
+        const durationMs = Date.now() - startedAt;
+        const record = {
+          id: randomId("diag"),
+          startedAt: new Date(startedAt).toISOString(),
+          endedAt: nowIso(),
+          traceId,
+          spanId,
+          operation,
+          method,
+          endpoint: normalizedEndpoint,
+          status: response.status,
+          durationMs,
+          success: response.ok
+        };
+        this.diagnostics.add(record);
+        if (response.ok) {
+          return {
+            data: payload,
+            status: response.status,
+            traceId
+          };
+        }
+        const message = toMessage(payload, response.status, response.statusText);
+        const retryable = this.shouldRetryStatus(response.status);
+        const error = new RuntimeClientError({
+          message,
+          status: response.status,
+          retryable,
+          code: response.status === 404 ? "NOT_FOUND" : "REQUEST_FAILED",
+          details: payload,
+          traceId
+        });
+        lastError = error;
+        if (!retryable || attempt === maxAttempts - 1) {
+          throw error;
+        }
+      } catch (error) {
+        clearTimeout(timeout);
+        const durationMs = Date.now() - startedAt;
+        const isAbort = isObject(error) && error.name === "AbortError";
+        const mapped = error instanceof RuntimeClientError ? error : new RuntimeClientError({
+          message: isAbort ? "Request timed out" : error instanceof Error ? error.message : "Network error",
+          retryable: this.retryPolicy.retryOnNetworkError ?? true,
+          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
+          traceId
+        });
+        lastError = mapped;
+        this.diagnostics.add({
+          id: randomId("diag"),
+          startedAt: new Date(startedAt).toISOString(),
+          endedAt: nowIso(),
+          traceId,
+          spanId,
+          operation,
+          method,
+          endpoint: normalizedEndpoint,
+          durationMs,
+          success: false,
+          errorCode: mapped.code,
+          errorMessage: mapped.message
+        });
+        if (!mapped.retryable || attempt === maxAttempts - 1) {
+          throw mapped;
+        }
+      }
+      await new Promise((resolve) => setTimeout(resolve, this.backoff(attempt)));
+    }
+    throw lastError || new RuntimeClientError({
+      message: "Request failed",
+      retryable: false,
+      code: "REQUEST_FAILED"
+    });
+  }
+};
 
 // ../src/sdk/index.ts
 var WhisperError = class extends Error {
@@ -28,23 +394,42 @@ var DEFAULT_BASE_DELAY_MS = 250;
 var DEFAULT_MAX_DELAY_MS = 2e3;
 var DEFAULT_TIMEOUT_MS = 15e3;
 var PROJECT_CACHE_TTL_MS = 3e4;
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function getBackoffDelay(attempt, base, max) {
-  const jitter = 0.8 + Math.random() * 0.4;
-  return Math.min(max, Math.floor(base * Math.pow(2, attempt) * jitter));
+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);
+  }
 }
 function isLikelyProjectId(projectRef) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(projectRef);
 }
+function normalizeBaseUrl2(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  normalized = normalized.replace(/\/api\/v1$/i, "");
+  normalized = normalized.replace(/\/v1$/i, "");
+  normalized = normalized.replace(/\/api$/i, "");
+  return normalized;
+}
+function normalizeEndpoint2(endpoint) {
+  const withLeadingSlash = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  if (/^\/api\/v1(\/|$)/i.test(withLeadingSlash)) {
+    return withLeadingSlash.replace(/^\/api/i, "");
+  }
+  return withLeadingSlash;
+}
+function isProjectNotFoundMessage(message) {
+  const normalized = message.toLowerCase();
+  return normalized.includes("project not found") || normalized.includes("no project found") || normalized.includes("project does not exist");
+}
 var WhisperContext = class _WhisperContext {
   apiKey;
   baseUrl;
   defaultProject;
-  orgId;
   timeoutMs;
   retryConfig;
+  runtimeClient;
   projectRefToId = /* @__PURE__ */ new Map();
   projectCache = [];
   projectCacheExpiresAt = 0;
@@ -56,22 +441,49 @@ var WhisperContext = class _WhisperContext {
       });
     }
     this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl || "https://context.usewhisper.dev";
+    this.baseUrl = normalizeBaseUrl2(config.baseUrl || "https://context.usewhisper.dev");
     this.defaultProject = config.project;
-    this.orgId = config.orgId;
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.retryConfig = {
       maxAttempts: config.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
       baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
       maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS
     };
+    this.runtimeClient = new RuntimeClient({
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      compatMode: "fallback",
+      timeouts: {
+        searchMs: this.timeoutMs,
+        writeAckMs: this.timeoutMs,
+        bulkMs: Math.max(this.timeoutMs, 1e4),
+        profileMs: this.timeoutMs,
+        sessionMs: this.timeoutMs
+      },
+      retryPolicy: {
+        baseBackoffMs: this.retryConfig.baseDelayMs,
+        maxBackoffMs: this.retryConfig.maxDelayMs,
+        maxAttemptsByOperation: {
+          search: this.retryConfig.maxAttempts,
+          writeAck: this.retryConfig.maxAttempts,
+          bulk: this.retryConfig.maxAttempts,
+          profile: this.retryConfig.maxAttempts,
+          session: this.retryConfig.maxAttempts,
+          query: this.retryConfig.maxAttempts,
+          get: this.retryConfig.maxAttempts
+        }
+      }
+    });
+    warnDeprecatedOnce(
+      "whisper_context_class",
+      "[Whisper SDK] WhisperContext remains supported in v2 but is legacy. Prefer WhisperClient for runtime features (queue/cache/session/diagnostics)."
+    );
   }
   withProject(project) {
     return new _WhisperContext({
       apiKey: this.apiKey,
       baseUrl: this.baseUrl,
       project,
-      orgId: this.orgId,
       timeoutMs: this.timeoutMs,
       retry: this.retryConfig
     });
@@ -147,9 +559,17 @@ var WhisperContext = class _WhisperContext {
     return Array.from(candidates).filter(Boolean);
   }
   async withProjectRefFallback(projectRef, execute) {
+    try {
+      return await execute(projectRef);
+    } catch (error) {
+      if (!(error instanceof WhisperError) || error.code !== "PROJECT_NOT_FOUND") {
+        throw error;
+      }
+    }
     const refs = await this.getProjectRefCandidates(projectRef);
     let lastError;
     for (const ref of refs) {
+      if (ref === projectRef) continue;
       try {
         return await execute(ref);
       } catch (error) {
@@ -172,7 +592,7 @@ var WhisperContext = class _WhisperContext {
     if (status === 401 || /api key|unauthorized|forbidden/i.test(message)) {
       return { code: "INVALID_API_KEY", retryable: false };
     }
-    if (status === 404 || /project not found/i.test(message)) {
+    if (status === 404 && isProjectNotFoundMessage(message)) {
       return { code: "PROJECT_NOT_FOUND", retryable: false };
     }
     if (status === 408) {
@@ -186,64 +606,68 @@ var WhisperContext = class _WhisperContext {
     }
     return { code: "REQUEST_FAILED", retryable: false };
   }
+  isEndpointNotFoundError(error) {
+    if (!(error instanceof WhisperError)) {
+      return false;
+    }
+    if (error.status !== 404) {
+      return false;
+    }
+    const message = (error.message || "").toLowerCase();
+    return !isProjectNotFoundMessage(message);
+  }
+  inferOperation(endpoint, method) {
+    const normalized = normalizeEndpoint2(endpoint).toLowerCase();
+    if (normalized.includes("/memory/search")) return "search";
+    if (normalized.includes("/memory/bulk")) return "bulk";
+    if (normalized.includes("/memory/profile") || normalized.includes("/memory/session")) return "profile";
+    if (normalized.includes("/memory/ingest/session")) return "session";
+    if (normalized.includes("/context/query")) return "query";
+    if (method === "GET") return "get";
+    return "writeAck";
+  }
   async request(endpoint, options = {}) {
-    const maxAttempts = Math.max(1, this.retryConfig.maxAttempts);
-    let lastError;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    const method = String(options.method || "GET").toUpperCase();
+    const normalizedEndpoint = normalizeEndpoint2(endpoint);
+    const operation = this.inferOperation(normalizedEndpoint, method);
+    let body;
+    if (typeof options.body === "string") {
       try {
-        const response = await fetch(`${this.baseUrl}${endpoint}`, {
-          ...options,
-          signal: controller.signal,
-          headers: {
-            Authorization: `Bearer ${this.apiKey}`,
-            "Content-Type": "application/json",
-            ...this.orgId ? { "X-Whisper-Org-Id": this.orgId } : {},
-            ...options.headers
-          }
-        });
-        clearTimeout(timeout);
-        if (!response.ok) {
-          let payload = null;
-          try {
-            payload = await response.json();
-          } catch {
-            payload = await response.text().catch(() => "");
-          }
-          const message = typeof payload === "string" ? payload : payload?.error || payload?.message || `HTTP ${response.status}: ${response.statusText}`;
-          const { code, retryable } = this.classifyError(response.status, message);
-          const err = new WhisperError({
-            code,
-            message,
-            status: response.status,
-            retryable,
-            details: payload
-          });
-          if (!retryable || attempt === maxAttempts - 1) {
-            throw err;
-          }
-          await sleep(getBackoffDelay(attempt, this.retryConfig.baseDelayMs, this.retryConfig.maxDelayMs));
-          continue;
-        }
-        return response.json();
-      } catch (error) {
-        clearTimeout(timeout);
-        const isAbort = error?.name === "AbortError";
-        const mapped = error instanceof WhisperError ? error : new WhisperError({
-          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
-          message: isAbort ? "Request timed out" : error?.message || "Network request failed",
-          retryable: true,
-          details: error
-        });
-        lastError = mapped;
-        if (!mapped.retryable || attempt === maxAttempts - 1) {
-          throw mapped;
-        }
-        await sleep(getBackoffDelay(attempt, this.retryConfig.baseDelayMs, this.retryConfig.maxDelayMs));
+        body = JSON.parse(options.body);
+      } catch {
+        body = void 0;
+      }
+    } else if (options.body && typeof options.body === "object" && !ArrayBuffer.isView(options.body) && !(options.body instanceof ArrayBuffer) && !(options.body instanceof FormData) && !(options.body instanceof URLSearchParams) && !(options.body instanceof Blob) && !(options.body instanceof ReadableStream)) {
+      body = options.body;
+    }
+    try {
+      const response = await this.runtimeClient.request({
+        endpoint: normalizedEndpoint,
+        method,
+        operation,
+        idempotent: method === "GET" || method === "POST" && (operation === "search" || operation === "query" || operation === "profile"),
+        body,
+        headers: options.headers || {}
+      });
+      return response.data;
+    } catch (error) {
+      if (!(error instanceof RuntimeClientError)) {
+        throw error;
       }
+      let message = error.message;
+      if (error.status === 404 && !isProjectNotFoundMessage(message)) {
+        const endpointHint = `${this.baseUrl}${normalizedEndpoint}`;
+        message = `Endpoint not found at ${endpointHint}. This deployment may not support this API route.`;
+      }
+      const { code, retryable } = this.classifyError(error.status, message);
+      throw new WhisperError({
+        code,
+        message,
+        status: error.status,
+        retryable,
+        details: error.details
+      });
     }
-    throw lastError instanceof Error ? lastError : new WhisperError({ code: "REQUEST_FAILED", message: "Request failed" });
   }
   async query(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -354,13 +778,18 @@ var WhisperContext = class _WhisperContext {
             session_id: params.session_id,
             agent_id: params.agent_id,
             importance: params.importance,
-            metadata: params.metadata
+            metadata: params.metadata,
+            async: params.async,
+            write_mode: params.write_mode
           })
         });
-        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id;
+        const id2 = direct?.memory?.id || direct?.id || direct?.memory_id || direct?.job_id;
         if (id2) {
           return { id: id2, success: true, path: "sota", fallback_used: false };
         }
+        if (direct?.success === true) {
+          return { id: "", success: true, path: "sota", fallback_used: false };
+        }
       } catch (error) {
         if (params.allow_legacy_fallback === false) {
           throw error;
@@ -390,20 +819,109 @@ var WhisperContext = class _WhisperContext {
       return { id, success: true, path: "legacy", fallback_used: true };
     });
   }
-  async searchMemories(params) {
+  async addMemoriesBulk(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/bulk", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const created = await Promise.all(
+          params.memories.map(
+            (memory) => this.addMemory({
+              project,
+              content: memory.content,
+              memory_type: memory.memory_type,
+              user_id: memory.user_id,
+              session_id: memory.session_id,
+              agent_id: memory.agent_id,
+              importance: memory.importance,
+              metadata: memory.metadata,
+              allow_legacy_fallback: true
+            })
+          )
+        );
+        return {
+          success: true,
+          created: created.length,
+          memories: created,
+          path: "legacy",
+          fallback_used: true
+        };
+      }
+    });
+  }
+  async extractMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async extractSessionMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract/session", {
       method: "POST",
       body: JSON.stringify({
-        query: params.query,
+        ...params,
         project,
-        user_id: params.user_id,
-        session_id: params.session_id,
-        memory_types: params.memory_type ? [params.memory_type] : void 0,
-        top_k: params.top_k || 10
+        messages: params.messages.map((m) => ({
+          ...m,
+          timestamp: m.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+        }))
       })
     }));
   }
+  async searchMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            memory_types: params.memory_type ? [params.memory_type] : void 0,
+            top_k: params.top_k || 10,
+            profile: params.profile,
+            include_pending: params.include_pending
+          })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyTypeMap = {
+          factual: "factual",
+          preference: "semantic",
+          event: "episodic",
+          relationship: "semantic",
+          opinion: "semantic",
+          goal: "semantic",
+          instruction: "procedural"
+        };
+        return this.request("/v1/memories/search", {
+          method: "POST",
+          body: JSON.stringify({
+            query: params.query,
+            project,
+            user_id: params.user_id,
+            session_id: params.session_id,
+            agent_id: params.agent_id,
+            memory_type: params.memory_type ? legacyTypeMap[params.memory_type] : void 0,
+            top_k: params.top_k || 10
+          })
+        });
+      }
+    });
+  }
   async createApiKey(params) {
     return this.request("/v1/keys", {
       method: "POST",
@@ -418,10 +936,29 @@ var WhisperContext = class _WhisperContext {
   }
   async searchMemoriesSOTA(params) {
     const projectRef = this.getRequiredProject(params.project);
-    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
-      method: "POST",
-      body: JSON.stringify({ ...params, project })
-    }));
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      try {
+        return await this.request("/v1/memory/search", {
+          method: "POST",
+          body: JSON.stringify({ ...params, project })
+        });
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const firstType = params.memory_types?.[0];
+        return this.searchMemories({
+          project,
+          query: params.query,
+          user_id: params.user_id,
+          session_id: params.session_id,
+          memory_type: firstType,
+          top_k: params.top_k,
+          profile: params.profile,
+          include_pending: params.include_pending
+        });
+      }
+    });
   }
   async ingestSession(params) {
     const projectRef = this.getRequiredProject(params.project);
@@ -431,37 +968,116 @@ var WhisperContext = class _WhisperContext {
     }));
   }
   async getSessionMemories(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.limit && { limit: params.limit.toString() },
-      ...params.since_date && { since_date: params.since_date }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.limit && { limit: params.limit.toString() },
+        ...params.since_date && { since_date: params.since_date },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/session/${params.session_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        return { memories: [], count: 0 };
+      }
     });
-    return this.request(`/v1/memory/session/${params.session_id}?${query}`);
   }
   async getUserProfile(params) {
-    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
-    const query = new URLSearchParams({
-      project,
-      ...params.memory_types && { memory_types: params.memory_types }
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, async (project) => {
+      const query = new URLSearchParams({
+        project,
+        ...params.memory_types && { memory_types: params.memory_types },
+        ...params.include_pending !== void 0 && { include_pending: String(params.include_pending) }
+      });
+      try {
+        return await this.request(`/v1/memory/profile/${params.user_id}?${query}`);
+      } catch (error) {
+        if (!this.isEndpointNotFoundError(error)) {
+          throw error;
+        }
+        const legacyQuery = new URLSearchParams({
+          project,
+          user_id: params.user_id,
+          limit: "200"
+        });
+        const legacy = await this.request(`/v1/memories?${legacyQuery}`);
+        const memories = Array.isArray(legacy?.memories) ? legacy.memories : [];
+        return {
+          user_id: params.user_id,
+          memories,
+          count: memories.length
+        };
+      }
     });
-    return this.request(`/v1/memory/profile/${params.user_id}?${query}`);
   }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
   async updateMemory(memoryId, params) {
-    return this.request(`/v1/memory/${memoryId}`, {
-      method: "PUT",
-      body: JSON.stringify(params)
-    });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify(params)
+      });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      const legacy = await this.request(`/v1/memories/${memoryId}`, {
+        method: "PUT",
+        body: JSON.stringify({
+          content: params.content
+        })
+      });
+      return {
+        success: true,
+        new_memory_id: legacy?.id || memoryId,
+        old_memory_id: memoryId
+      };
+    }
   }
   async deleteMemory(memoryId) {
-    return this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    try {
+      return await this.request(`/v1/memory/${memoryId}`, { method: "DELETE" });
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      await this.request(`/v1/memories/${memoryId}`, { method: "DELETE" });
+      return {
+        success: true,
+        deleted: memoryId
+      };
+    }
   }
   async getMemoryRelations(memoryId) {
     return this.request(`/v1/memory/${memoryId}/relations`);
   }
+  async getMemoryGraph(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const query = new URLSearchParams({
+      project,
+      ...params.user_id && { user_id: params.user_id },
+      ...params.session_id && { session_id: params.session_id },
+      ...params.include_inactive !== void 0 && { include_inactive: String(params.include_inactive) },
+      ...params.limit !== void 0 && { limit: String(params.limit) }
+    });
+    return this.request(`/v1/memory/graph?${query}`);
+  }
+  async getConversationGraph(params) {
+    const project = await this.resolveProjectId(this.getRequiredProject(params.project));
+    const query = new URLSearchParams({
+      project,
+      ...params.include_inactive !== void 0 && { include_inactive: String(params.include_inactive) },
+      ...params.limit !== void 0 && { limit: String(params.limit) }
+    });
+    return this.request(`/v1/memory/graph/conversation/${params.session_id}?${query}`);
+  }
   async oracleSearch(params) {
     const project = await this.resolveProjectId(this.getRequiredProject(params.project));
     return this.request("/v1/oracle/search", {
@@ -586,6 +1202,9 @@ var WhisperContext = class _WhisperContext {
   };
   memory = {
     add: (params) => this.addMemory(params),
+    addBulk: (params) => this.addMemoriesBulk(params),
+    extract: (params) => this.extractMemories(params),
+    extractSession: (params) => this.extractSessionMemories(params),
     search: (params) => this.searchMemories(params),
     searchSOTA: (params) => this.searchMemoriesSOTA(params),
     ingestSession: (params) => this.ingestSession(params),
@@ -595,6 +1214,8 @@ var WhisperContext = class _WhisperContext {
     update: (memoryId, params) => this.updateMemory(memoryId, params),
     delete: (memoryId) => this.deleteMemory(memoryId),
     getRelations: (memoryId) => this.getMemoryRelations(memoryId),
+    getGraph: (params) => this.getMemoryGraph(params),
+    getConversationGraph: (params) => this.getConversationGraph(params),
     consolidate: (params) => this.consolidateMemories(params),
     updateDecay: (params) => this.updateImportanceDecay(params),
     getImportanceStats: (project) => this.getImportanceStats(project)
@@ -639,6 +1260,512 @@ var server = new McpServer({
   name: "whisper-context",
   version: "0.2.8"
 });
+var STATE_DIR = join(homedir(), ".whisper-mcp");
+var STATE_PATH = join(STATE_DIR, "state.json");
+var AUDIT_LOG_PATH = join(STATE_DIR, "forget-audit.log");
+function ensureStateDir() {
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true });
+  }
+}
+function getWorkspaceId(workspaceId) {
+  if (workspaceId?.trim()) return workspaceId.trim();
+  const seed = `${process.cwd()}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12)}`;
+  return createHash("sha256").update(seed).digest("hex").slice(0, 20);
+}
+function getWorkspaceIdForPath(path, workspaceId) {
+  if (workspaceId?.trim()) return workspaceId.trim();
+  if (!path) return getWorkspaceId(void 0);
+  const seed = `${path}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12)}`;
+  return createHash("sha256").update(seed).digest("hex").slice(0, 20);
+}
+function clamp01(value) {
+  if (Number.isNaN(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function renderCitation(ev) {
+  return ev.line_end && ev.line_end !== ev.line_start ? `${ev.path}:${ev.line_start}-${ev.line_end}` : `${ev.path}:${ev.line_start}`;
+}
+function extractLineStart(metadata) {
+  const raw = metadata.line_start ?? metadata.line ?? metadata.start_line ?? metadata.startLine ?? 1;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 1;
+}
+function extractLineEnd(metadata, start) {
+  const raw = metadata.line_end ?? metadata.end_line ?? metadata.endLine;
+  if (raw === void 0 || raw === null) return void 0;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < start) return void 0;
+  return Math.floor(parsed);
+}
+function toEvidenceRef(source, workspaceId, methodFallback) {
+  const metadata = source.metadata || {};
+  const lineStart = extractLineStart(metadata);
+  const lineEnd = extractLineEnd(metadata, lineStart);
+  const path = String(
+    metadata.file_path ?? metadata.path ?? source.source ?? source.document ?? source.id ?? "unknown"
+  );
+  const rawMethod = String(source.retrieval_source || methodFallback).toLowerCase();
+  const retrievalMethod = rawMethod.includes("graph") ? "graph" : rawMethod.includes("memory") ? "memory" : rawMethod.includes("lex") ? "lexical" : rawMethod.includes("symbol") ? "symbol" : "semantic";
+  return {
+    evidence_id: randomUUID(),
+    source_id: String(source.id || source.document || source.source || randomUUID()),
+    path,
+    line_start: lineStart,
+    ...lineEnd ? { line_end: lineEnd } : {},
+    snippet: String(source.content || metadata.snippet || "").slice(0, 500),
+    score: clamp01(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) } : {},
+    workspace_id: workspaceId,
+    metadata: {
+      source: String(source.source || ""),
+      document: String(source.document || "")
+    }
+  };
+}
+function loadState() {
+  ensureStateDir();
+  if (!existsSync(STATE_PATH)) {
+    return { workspaces: {} };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(STATE_PATH, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return { workspaces: {} };
+    return parsed;
+  } catch {
+    return { workspaces: {} };
+  }
+}
+function saveState(state) {
+  ensureStateDir();
+  writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), "utf-8");
+}
+function getWorkspaceState(state, workspaceId) {
+  if (!state.workspaces[workspaceId]) {
+    state.workspaces[workspaceId] = {
+      decisions: [],
+      failures: [],
+      entities: [],
+      documents: [],
+      annotations: [],
+      session_summaries: [],
+      events: [],
+      index_metadata: {}
+    };
+  }
+  return state.workspaces[workspaceId];
+}
+function computeChecksum(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+var cachedProjectRef = DEFAULT_PROJECT || void 0;
+async function resolveProjectRef(explicit) {
+  if (explicit?.trim()) return explicit.trim();
+  if (cachedProjectRef) return cachedProjectRef;
+  try {
+    const { projects } = await whisper.listProjects();
+    const first = projects?.[0];
+    if (!first) return void 0;
+    cachedProjectRef = first.slug || first.name || first.id;
+    return cachedProjectRef;
+  } catch {
+    return void 0;
+  }
+}
+function buildAbstain(args) {
+  return {
+    status: "abstained",
+    answer: null,
+    reason: args.reason,
+    message: args.message,
+    closest_evidence: args.closest_evidence,
+    recommended_next_calls: ["repo_index_status", "index_workspace", "symbol_search", "get_relevant_context"],
+    diagnostics: {
+      claims_evaluated: args.claims_evaluated,
+      evidence_items_found: args.evidence_items_found,
+      min_required: args.min_required,
+      index_fresh: args.index_fresh
+    }
+  };
+}
+function getGitHead(searchPath) {
+  const root = searchPath || process.cwd();
+  const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf-8" });
+  if (result.status !== 0) return void 0;
+  const out = String(result.stdout || "").trim();
+  return out || void 0;
+}
+function getGitPendingCount(searchPath) {
+  const root = searchPath || process.cwd();
+  const result = spawnSync("git", ["-C", root, "status", "--porcelain"], { encoding: "utf-8" });
+  if (result.status !== 0) return void 0;
+  const out = String(result.stdout || "").trim();
+  if (!out) return 0;
+  return out.split("\n").filter(Boolean).length;
+}
+function countCodeFiles(searchPath, maxFiles = 5e3) {
+  const skip = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".next", "build", "__pycache__", ".turbo", "coverage", ".cache"]);
+  const exts = /* @__PURE__ */ new Set(["ts", "tsx", "js", "jsx", "py", "go", "rs", "java", "cpp", "c", "cs", "rb", "php", "swift", "kt", "sql", "prisma", "graphql", "json", "yaml", "yml", "toml", "env"]);
+  let total = 0;
+  let skipped = 0;
+  function walk(dir) {
+    if (total >= maxFiles) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (total >= maxFiles) return;
+      if (skip.has(e.name)) {
+        skipped += 1;
+        continue;
+      }
+      const full = join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile()) {
+        const ext = extname(e.name).replace(".", "");
+        if (exts.has(ext)) total += 1;
+      }
+    }
+  }
+  walk(searchPath);
+  return { total, skipped };
+}
+server.tool(
+  "resolve_workspace",
+  "Resolve workspace identity from path + API key and map to a project without mandatory dashboard setup.",
+  {
+    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
+    workspace_id: z.string().optional(),
+    project: z.string().optional()
+  },
+  async ({ path, workspace_id, project }) => {
+    try {
+      const workspaceId = getWorkspaceIdForPath(path, workspace_id);
+      const state = loadState();
+      const existed = Boolean(state.workspaces[workspaceId]);
+      const workspace = getWorkspaceState(state, workspaceId);
+      const resolvedProject = await resolveProjectRef(project);
+      const resolvedBy = project?.trim() ? "explicit_project" : DEFAULT_PROJECT ? "env_default" : resolvedProject ? "auto_first_project" : "unresolved";
+      saveState(state);
+      const payload = {
+        workspace_id: workspaceId,
+        project_id: resolvedProject || null,
+        created: !existed,
+        resolved_by: resolvedBy,
+        index_state: {
+          last_indexed_at: workspace.index_metadata?.last_indexed_at || null,
+          last_indexed_commit: workspace.index_metadata?.last_indexed_commit || null,
+          coverage: workspace.index_metadata?.coverage ?? 0
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "repo_index_status",
+  "Check index freshness, coverage, commit, and pending changes before retrieval/edits.",
+  {
+    workspace_id: z.string().optional(),
+    path: z.string().optional()
+  },
+  async ({ workspace_id, path }) => {
+    try {
+      const rootPath = path || process.cwd();
+      const workspaceId = getWorkspaceIdForPath(rootPath, workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const lastIndexedAt = workspace.index_metadata?.last_indexed_at;
+      const ageHours = lastIndexedAt ? (Date.now() - new Date(lastIndexedAt).getTime()) / (60 * 60 * 1e3) : null;
+      const stale = ageHours === null ? true : ageHours > 168;
+      const payload = {
+        workspace_id: workspaceId,
+        freshness: {
+          stale,
+          age_hours: ageHours,
+          last_indexed_at: lastIndexedAt || null
+        },
+        coverage: workspace.index_metadata?.coverage ?? 0,
+        last_indexed_commit: workspace.index_metadata?.last_indexed_commit || null,
+        current_commit: getGitHead(rootPath) || null,
+        pending_changes: getGitPendingCount(rootPath)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "index_workspace",
+  "Index workspace in full or incremental mode and update index metadata for freshness checks.",
+  {
+    workspace_id: z.string().optional(),
+    path: z.string().optional(),
+    mode: z.enum(["full", "incremental"]).optional().default("incremental"),
+    max_files: z.number().optional().default(1500)
+  },
+  async ({ workspace_id, path, mode, max_files }) => {
+    try {
+      const rootPath = path || process.cwd();
+      const workspaceId = getWorkspaceIdForPath(rootPath, workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const fileStats = countCodeFiles(rootPath, max_files);
+      const coverage = Math.max(0, Math.min(1, fileStats.total / Math.max(1, max_files)));
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      workspace.index_metadata = {
+        last_indexed_at: now,
+        last_indexed_commit: getGitHead(rootPath),
+        coverage: mode === "full" ? 1 : coverage
+      };
+      saveState(state);
+      const payload = {
+        workspace_id: workspaceId,
+        mode,
+        indexed_files: fileStats.total,
+        skipped_files: fileStats.skipped,
+        duration_ms: 0,
+        warnings: fileStats.total === 0 ? ["No code files discovered for indexing."] : [],
+        index_metadata: workspace.index_metadata
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "get_relevant_context",
+  "Core retrieval. Task goes in, ranked context chunks come out with structured evidence (file:line ready).",
+  {
+    question: z.string().describe("Task/question to retrieve context for"),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    top_k: z.number().optional().default(12),
+    include_memories: z.boolean().optional().default(true),
+    include_graph: z.boolean().optional().default(true),
+    session_id: z.string().optional(),
+    user_id: z.string().optional()
+  },
+  async ({ question, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        const payload2 = {
+          question,
+          workspace_id: workspaceId,
+          total_results: 0,
+          context: "",
+          evidence: [],
+          used_context_ids: [],
+          latency_ms: 0,
+          warning: "No project resolved. Set WHISPER_PROJECT or create one in your account."
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+      }
+      const response = await whisper.query({
+        project: resolvedProject,
+        query: question,
+        top_k,
+        include_memories,
+        include_graph,
+        session_id,
+        user_id
+      });
+      const evidence = (response.results || []).map((r) => toEvidenceRef(r, workspaceId, "semantic"));
+      const payload = {
+        question,
+        workspace_id: workspaceId,
+        total_results: response.meta?.total || evidence.length,
+        context: response.context || "",
+        evidence,
+        used_context_ids: (response.results || []).map((r) => String(r.id)),
+        latency_ms: response.meta?.latency_ms || 0
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "claim_verifier",
+  "Verify whether a claim is supported by retrieved context. Returns supported/partial/unsupported with evidence.",
+  {
+    claim: z.string().describe("Claim to verify"),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    context_ids: z.array(z.string()).optional(),
+    strict: z.boolean().optional().default(true)
+  },
+  async ({ claim, workspace_id, project, context_ids, strict }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        const payload2 = {
+          verdict: "unsupported",
+          confidence: 0,
+          evidence: [],
+          missing_requirements: ["No project resolved. Set WHISPER_PROJECT or create one in your account."],
+          explanation: "Verifier could not run because no project is configured."
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+      }
+      const response = await whisper.query({
+        project: resolvedProject,
+        query: claim,
+        top_k: strict ? 8 : 12,
+        include_memories: true,
+        include_graph: true
+      });
+      const filtered = (response.results || []).filter(
+        (r) => !context_ids || context_ids.length === 0 || context_ids.includes(String(r.id))
+      );
+      const evidence = filtered.map((r) => toEvidenceRef(r, workspaceId, "semantic"));
+      const directEvidence = evidence.filter((e) => e.score >= (strict ? 0.7 : 0.6));
+      const weakEvidence = evidence.filter((e) => e.score >= (strict ? 0.45 : 0.35));
+      let verdict = "unsupported";
+      if (directEvidence.length > 0) verdict = "supported";
+      else if (weakEvidence.length > 0) verdict = "partial";
+      const payload = {
+        verdict,
+        confidence: evidence.length ? Math.max(...evidence.map((e) => e.score)) : 0,
+        evidence: verdict === "supported" ? directEvidence : weakEvidence,
+        missing_requirements: verdict === "supported" ? [] : verdict === "partial" ? ["No direct evidence spans met strict threshold."] : ["No sufficient supporting evidence found for the claim."],
+        explanation: verdict === "supported" ? "At least one direct evidence span supports the claim." : verdict === "partial" ? "Some related evidence exists, but direct support is incomplete." : "Retrieved context did not contain sufficient support."
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "evidence_locked_answer",
+  "Answer a question only when evidence requirements are met. Fails closed with an abstain payload when not verifiable.",
+  {
+    question: z.string(),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    constraints: z.object({
+      require_citations: z.boolean().optional().default(true),
+      min_evidence_items: z.number().optional().default(2),
+      min_confidence: z.number().optional().default(0.65),
+      max_staleness_hours: z.number().optional().default(168)
+    }).optional(),
+    retrieval: z.object({
+      top_k: z.number().optional().default(12),
+      include_symbols: z.boolean().optional().default(true),
+      include_recent_decisions: z.boolean().optional().default(true)
+    }).optional()
+  },
+  async ({ question, workspace_id, project, constraints, retrieval }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const requireCitations = constraints?.require_citations ?? true;
+      const minEvidenceItems = constraints?.min_evidence_items ?? 2;
+      const minConfidence = constraints?.min_confidence ?? 0.65;
+      const maxStalenessHours = constraints?.max_staleness_hours ?? 168;
+      const topK = retrieval?.top_k ?? 12;
+      const resolvedProject = await resolveProjectRef(project);
+      if (!resolvedProject) {
+        const abstain = buildAbstain({
+          reason: "no_retrieval_hits",
+          message: "No project resolved. Set WHISPER_PROJECT or create one in your account.",
+          closest_evidence: [],
+          claims_evaluated: 1,
+          evidence_items_found: 0,
+          min_required: minEvidenceItems,
+          index_fresh: true
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      const response = await whisper.query({
+        project: resolvedProject,
+        query: question,
+        top_k: topK,
+        include_memories: true,
+        include_graph: true
+      });
+      const evidence = (response.results || []).map((r) => toEvidenceRef(r, workspaceId, "semantic"));
+      const sorted = evidence.sort((a, b) => b.score - a.score);
+      const confidence = sorted.length ? sorted[0].score : 0;
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const lastIndexedAt = workspace.index_metadata?.last_indexed_at;
+      const indexFresh = !lastIndexedAt || Date.now() - new Date(lastIndexedAt).getTime() <= maxStalenessHours * 60 * 60 * 1e3;
+      if (sorted.length === 0) {
+        const abstain = buildAbstain({
+          reason: "no_retrieval_hits",
+          message: "No retrieval hits were found for this question.",
+          closest_evidence: [],
+          claims_evaluated: 1,
+          evidence_items_found: 0,
+          min_required: minEvidenceItems,
+          index_fresh: indexFresh
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      const supportedEvidence = sorted.filter((e) => e.score >= minConfidence);
+      const verdict = supportedEvidence.length >= 1 ? "supported" : "partial";
+      if (!indexFresh) {
+        const abstain = buildAbstain({
+          reason: "stale_index",
+          message: "Index freshness requirement not met. Re-index before answering.",
+          closest_evidence: sorted.slice(0, 3),
+          claims_evaluated: 1,
+          evidence_items_found: supportedEvidence.length,
+          min_required: minEvidenceItems,
+          index_fresh: false
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      if (requireCitations && (verdict !== "supported" || supportedEvidence.length < minEvidenceItems)) {
+        const abstain = buildAbstain({
+          reason: "insufficient_evidence",
+          message: "Citation or verification thresholds were not met.",
+          closest_evidence: sorted.slice(0, 3),
+          claims_evaluated: 1,
+          evidence_items_found: supportedEvidence.length,
+          min_required: minEvidenceItems,
+          index_fresh: true
+        });
+        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
+      }
+      const citations = supportedEvidence.slice(0, Math.max(minEvidenceItems, 3));
+      const answerLines = citations.map(
+        (ev, idx) => `${idx + 1}. [${renderCitation(ev)}] ${ev.snippet || "Relevant context found."}`
+      );
+      const answered = {
+        status: "answered",
+        answer: answerLines.join("\n"),
+        citations,
+        confidence,
+        verification: {
+          verdict,
+          supported_claims: verdict === "supported" ? 1 : 0,
+          total_claims: 1
+        },
+        used_context_ids: citations.map((c) => c.source_id)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(answered, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
 server.tool(
   "query_context",
   "Search your knowledge base for relevant context. Returns packed context ready for LLM consumption. Supports hybrid vector+keyword search, memory inclusion, and knowledge graph traversal.",
@@ -1071,6 +2198,334 @@ server.tool(
     }
   }
 );
+server.tool(
+  "forget",
+  "Delete or invalidate memories with immutable audit logging.",
+  {
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    target: z.object({
+      memory_id: z.string().optional(),
+      query: z.string().optional()
+    }),
+    mode: z.enum(["delete", "invalidate"]).optional().default("invalidate"),
+    reason: z.string().optional()
+  },
+  async ({ workspace_id, project, target, mode, reason }) => {
+    try {
+      if (!target.memory_id && !target.query) {
+        return { content: [{ type: "text", text: "Error: target.memory_id or target.query is required." }] };
+      }
+      const affectedIds = [];
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const actor = process.env.WHISPER_AGENT_ID || process.env.USERNAME || "api_key_principal";
+      const resolvedProject = await resolveProjectRef(project);
+      async function applyToMemory(memoryId) {
+        if (mode === "delete") {
+          await whisper.deleteMemory(memoryId);
+        } else {
+          try {
+            await whisper.updateMemory(memoryId, {
+              content: `[INVALIDATED at ${now}] ${reason || "Invalidated by forget tool."}`,
+              reasoning: reason || "No reason provided"
+            });
+          } catch {
+            if (resolvedProject) {
+              await whisper.addMemory({
+                project: resolvedProject,
+                content: `Invalidated memory ${memoryId} at ${now}. Reason: ${reason || "No reason provided"}`,
+                memory_type: "instruction",
+                importance: 1
+              });
+            }
+          }
+        }
+        affectedIds.push(memoryId);
+      }
+      if (target.memory_id) {
+        await applyToMemory(target.memory_id);
+      } else {
+        if (!resolvedProject) {
+          ensureStateDir();
+          const audit2 = {
+            audit_id: randomUUID(),
+            actor,
+            called_at: now,
+            mode,
+            ...reason ? { reason } : {},
+            affected_ids: affectedIds
+          };
+          appendFileSync(AUDIT_LOG_PATH, `${JSON.stringify(audit2)}
+`, "utf-8");
+          const payload2 = {
+            status: "completed",
+            affected_ids: affectedIds,
+            audit: {
+              audit_id: audit2.audit_id,
+              actor: audit2.actor,
+              called_at: audit2.called_at,
+              mode: audit2.mode,
+              ...audit2.reason ? { reason: audit2.reason } : {}
+            },
+            warning: "No project resolved for query-based forget. Nothing was changed."
+          };
+          return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+        }
+        const search = await whisper.searchMemoriesSOTA({
+          project: resolvedProject,
+          query: target.query || "",
+          top_k: 25,
+          include_relations: false
+        });
+        const memoryIds = (search.results || []).map((r) => String(r?.memory?.id || "")).filter(Boolean);
+        for (const id of memoryIds) {
+          await applyToMemory(id);
+        }
+      }
+      ensureStateDir();
+      const audit = {
+        audit_id: randomUUID(),
+        actor,
+        called_at: now,
+        mode,
+        ...reason ? { reason } : {},
+        affected_ids: affectedIds
+      };
+      appendFileSync(AUDIT_LOG_PATH, `${JSON.stringify(audit)}
+`, "utf-8");
+      const payload = {
+        status: "completed",
+        affected_ids: affectedIds,
+        audit: {
+          audit_id: audit.audit_id,
+          actor: audit.actor,
+          called_at: audit.called_at,
+          mode: audit.mode,
+          ...audit.reason ? { reason: audit.reason } : {}
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "export_context_bundle",
+  "Export project/workspace memory and context to a portable bundle with checksum.",
+  {
+    workspace_id: z.string().optional(),
+    project: z.string().optional()
+  },
+  async ({ workspace_id, project }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const resolvedProject = await resolveProjectRef(project);
+      let memories = [];
+      if (resolvedProject) {
+        try {
+          const m = await whisper.searchMemoriesSOTA({
+            project: resolvedProject,
+            query: "memory",
+            top_k: 100,
+            include_relations: true
+          });
+          memories = (m.results || []).map((r) => r.memory || r);
+        } catch {
+          memories = [];
+        }
+      }
+      const contents = {
+        memories,
+        entities: workspace.entities,
+        decisions: workspace.decisions,
+        failures: workspace.failures,
+        annotations: workspace.annotations,
+        session_summaries: workspace.session_summaries,
+        documents: workspace.documents,
+        index_metadata: workspace.index_metadata || {}
+      };
+      const bundleWithoutChecksum = {
+        bundle_version: "1.0",
+        workspace_id: workspaceId,
+        exported_at: now,
+        contents
+      };
+      const checksum = computeChecksum(bundleWithoutChecksum);
+      const bundle = { ...bundleWithoutChecksum, checksum };
+      return { content: [{ type: "text", text: JSON.stringify(bundle, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "import_context_bundle",
+  "Import a portable context bundle with merge/replace modes and checksum verification.",
+  {
+    workspace_id: z.string().optional(),
+    bundle: z.object({
+      bundle_version: z.string(),
+      workspace_id: z.string(),
+      exported_at: z.string(),
+      contents: z.object({
+        memories: z.array(z.any()).default([]),
+        entities: z.array(z.any()).default([]),
+        decisions: z.array(z.any()).default([]),
+        failures: z.array(z.any()).default([]),
+        annotations: z.array(z.any()).default([]),
+        session_summaries: z.array(z.any()).default([]),
+        documents: z.array(z.any()).default([]),
+        index_metadata: z.record(z.any()).default({})
+      }),
+      checksum: z.string()
+    }),
+    mode: z.enum(["merge", "replace"]).optional().default("merge"),
+    dedupe_strategy: z.enum(["semantic", "id", "none"]).optional().default("semantic")
+  },
+  async ({ workspace_id, bundle, mode, dedupe_strategy }) => {
+    try {
+      let dedupe2 = function(existing, incoming) {
+        if (dedupe_strategy === "none") return false;
+        if (dedupe_strategy === "id") return existing.some((e) => e.id === incoming.id);
+        const norm = incoming.content.toLowerCase().trim();
+        return existing.some((e) => e.content.toLowerCase().trim() === norm);
+      };
+      var dedupe = dedupe2;
+      const workspaceId = getWorkspaceId(workspace_id || bundle.workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const { checksum, ...unsignedBundle } = bundle;
+      const checksumVerified = checksum === computeChecksum(unsignedBundle);
+      const conflicts = [];
+      if (!checksumVerified) conflicts.push("checksum_mismatch");
+      const importedCounts = {
+        memories: 0,
+        entities: 0,
+        decisions: 0,
+        failures: 0,
+        annotations: 0,
+        session_summaries: 0,
+        documents: 0
+      };
+      const skippedCounts = {
+        memories: 0,
+        entities: 0,
+        decisions: 0,
+        failures: 0,
+        annotations: 0,
+        session_summaries: 0,
+        documents: 0
+      };
+      if (mode === "replace") {
+        workspace.entities = [];
+        workspace.decisions = [];
+        workspace.failures = [];
+        workspace.annotations = [];
+        workspace.session_summaries = [];
+        workspace.documents = [];
+        workspace.events = [];
+      }
+      const keys = ["entities", "decisions", "failures", "annotations", "session_summaries", "documents"];
+      for (const key of keys) {
+        const sourceItems = bundle.contents[key];
+        for (const incoming of sourceItems || []) {
+          const normalized = {
+            id: incoming.id || randomUUID(),
+            content: incoming.content || "",
+            created_at: incoming.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+            ...incoming.session_id ? { session_id: incoming.session_id } : {},
+            ...incoming.commit ? { commit: incoming.commit } : {},
+            ...incoming.metadata ? { metadata: incoming.metadata } : {}
+          };
+          const targetArray = workspace[key];
+          if (dedupe2(targetArray, normalized)) {
+            skippedCounts[key] += 1;
+            continue;
+          }
+          targetArray.push(normalized);
+          importedCounts[key] += 1;
+        }
+      }
+      workspace.index_metadata = bundle.contents.index_metadata || workspace.index_metadata || {};
+      saveState(state);
+      const payload = {
+        imported_counts: importedCounts,
+        skipped_counts: skippedCounts,
+        conflicts,
+        checksum_verified: checksumVerified
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
+server.tool(
+  "diff_context",
+  "Return deterministic context changes from an explicit anchor (session_id, timestamp, or commit).",
+  {
+    workspace_id: z.string().optional(),
+    anchor: z.object({
+      type: z.enum(["session_id", "timestamp", "commit"]),
+      value: z.string()
+    }).optional(),
+    scope: z.object({
+      include: z.array(z.enum(["decisions", "failures", "entities", "documents", "summaries"])).optional().default(["decisions", "failures", "entities", "documents", "summaries"])
+    }).optional()
+  },
+  async ({ workspace_id, anchor, scope }) => {
+    try {
+      const workspaceId = getWorkspaceId(workspace_id);
+      const state = loadState();
+      const workspace = getWorkspaceState(state, workspaceId);
+      const include = new Set(scope?.include || ["decisions", "failures", "entities", "documents", "summaries"]);
+      let anchorTimestamp = null;
+      let fromAnchor = anchor || null;
+      if (anchor?.type === "timestamp") {
+        anchorTimestamp = new Date(anchor.value).toISOString();
+      } else if (anchor?.type === "session_id") {
+        const summary = workspace.session_summaries.filter((s) => s.session_id === anchor.value).sort((a, b) => a.created_at.localeCompare(b.created_at)).at(-1);
+        anchorTimestamp = summary?.created_at || null;
+      } else if (anchor?.type === "commit") {
+        const hit = workspace.events.filter((e) => e.commit === anchor.value).sort((a, b) => a.at.localeCompare(b.at)).at(-1);
+        anchorTimestamp = hit?.at || null;
+      } else {
+        const lastSummary = workspace.session_summaries.slice().sort((a, b) => a.created_at.localeCompare(b.created_at)).at(-1);
+        if (lastSummary) {
+          anchorTimestamp = lastSummary.created_at;
+          fromAnchor = { type: "session_id", value: lastSummary.session_id || lastSummary.id };
+        }
+      }
+      const after = (items) => !anchorTimestamp ? items : items.filter((i) => i.created_at > anchorTimestamp);
+      const changes = {
+        decisions: include.has("decisions") ? after(workspace.decisions) : [],
+        failures: include.has("failures") ? after(workspace.failures) : [],
+        entities: include.has("entities") ? after(workspace.entities) : [],
+        documents: include.has("documents") ? after(workspace.documents) : [],
+        summaries: include.has("summaries") ? after(workspace.session_summaries) : []
+      };
+      const payload = {
+        changes,
+        from_anchor: fromAnchor,
+        to_anchor: { type: "timestamp", value: (/* @__PURE__ */ new Date()).toISOString() },
+        counts: {
+          decisions: changes.decisions.length,
+          failures: changes.failures.length,
+          entities: changes.entities.length,
+          documents: changes.documents.length,
+          summaries: changes.summaries.length
+        }
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".next", "build", "__pycache__", ".turbo", "coverage", ".cache"]);
 var CODE_EXTENSIONS = /* @__PURE__ */ new Set(["ts", "tsx", "js", "jsx", "py", "go", "rs", "java", "cpp", "c", "cs", "rb", "php", "swift", "kt", "sql", "prisma", "graphql", "json", "yaml", "yml", "toml", "env"]);
 function extractSignature(filePath, content) {
@@ -1109,7 +2564,7 @@ server.tool(
     file_types: z.array(z.string()).optional().describe("Limit to specific extensions e.g. ['ts', 'py']. Defaults to all common code files."),
     top_k: z.number().optional().default(10).describe("Number of most relevant files to return"),
     threshold: z.number().optional().default(0.2).describe("Minimum similarity score 0-1. Lower = more results but less precise."),
-    max_files: z.number().optional().default(300).describe("Max files to scan. For large codebases, increase this or narrow with file_types.")
+    max_files: z.number().optional().default(150).describe("Max files to scan. For large codebases, narrow with file_types instead of raising this.")
   },
   async ({ query, path: searchPath, file_types, top_k, threshold, max_files }) => {
     const rootPath = searchPath || process.cwd();
@@ -1356,6 +2811,50 @@ server.tool(
     return { content: [{ type: "text", text: lines.join("\n") }] };
   }
 );
+server.tool(
+  "semantic_search",
+  "Semantic vector search over provided documents. Uses embeddings to find semantically similar content. Perfect for AI code search, finding similar functions, or searching by meaning rather than keywords.",
+  {
+    query: z.string().describe("What to search for semantically (e.g. 'authentication logic', 'database connection')"),
+    documents: z.array(z.object({
+      id: z.string().describe("Unique identifier (file path, URL, or any ID)"),
+      content: z.string().describe("The text content to search in")
+    })).describe("Documents to search over"),
+    top_k: z.number().optional().default(5).describe("Number of results to return"),
+    threshold: z.number().optional().default(0.3).describe("Minimum similarity score 0-1")
+  },
+  async ({ query, documents, top_k, threshold }) => {
+    try {
+      const API_KEY2 = process.env.WHISPER_API_KEY;
+      const BASE_URL2 = process.env.WHISPER_API_BASE_URL || "https://context.usewhisper.dev";
+      const res = await fetch(`${BASE_URL2}/v1/search/semantic`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${API_KEY2}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ query, documents, top_k, threshold })
+      });
+      const data = await res.json();
+      if (data.error) {
+        return { content: [{ type: "text", text: `Error: ${data.error}` }] };
+      }
+      if (!data.results || data.results.length === 0) {
+        return { content: [{ type: "text", text: "No semantically similar results found." }] };
+      }
+      const lines = [`Found ${data.results.length} semantically similar results:
+`];
+      for (const r of data.results) {
+        lines.push(`\u{1F4C4} ${r.id} (score: ${r.score.toFixed(3)})`);
+        lines.push(`   ${r.content.slice(0, 200)}${r.content.length > 200 ? "..." : ""}`);
+        lines.push("");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    }
+  }
+);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);