@usewhisper/mcp-server 2.14.0 → 2.16.0

package/dist/server.js

@@ -3,11 +3,11 @@
 // ../src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
+import { z as z2 } from "zod";
 import { execSync, spawnSync } from "child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from "fs";
 import { join, relative, extname, normalize as normalizePath, resolve as resolvePath } from "path";
-import { homedir } from "os";
+import { homedir, userInfo } from "os";
 import { createHash, randomUUID } from "crypto";
 
 // ../src/sdk/core/telemetry.ts
@@ -127,6 +127,8 @@ var RuntimeClientError = class extends Error {
   code;
   details;
   traceId;
+  hint;
+  requestId;
   constructor(args) {
     super(args.message);
     this.name = "RuntimeClientError";
@@ -135,6 +137,8 @@ var RuntimeClientError = class extends Error {
     this.code = args.code;
     this.details = args.details;
     this.traceId = args.traceId;
+    this.hint = args.hint;
+    this.requestId = args.requestId;
   }
 };
 var RuntimeClient = class {
@@ -339,14 +343,22 @@ var RuntimeClient = class {
           };
         }
         const message = toMessage(payload, response.status, response.statusText);
-        const retryable = this.shouldRetryStatus(response.status);
+        const payloadObject = isObject(payload) ? payload : {};
+        const payloadCode = typeof payloadObject.code === "string" ? payloadObject.code : void 0;
+        const payloadHint = typeof payloadObject.hint === "string" ? payloadObject.hint : void 0;
+        const payloadRequestId = typeof payloadObject.requestId === "string" ? payloadObject.requestId : typeof payloadObject.request_id === "string" ? payloadObject.request_id : void 0;
+        const payloadRetryable = typeof payloadObject.retryable === "boolean" ? payloadObject.retryable : void 0;
+        const statusRetryable = this.shouldRetryStatus(response.status);
+        const retryable = payloadRetryable ?? statusRetryable;
         const error = new RuntimeClientError({
           message,
           status: response.status,
           retryable,
-          code: response.status === 404 ? "NOT_FOUND" : "REQUEST_FAILED",
+          code: payloadCode || (response.status === 404 ? "NOT_FOUND" : "REQUEST_FAILED"),
           details: payload,
-          traceId
+          traceId: payloadRequestId || traceId,
+          requestId: payloadRequestId || traceId,
+          hint: payloadHint
         });
         lastError = error;
         if (!retryable || attempt === maxAttempts - 1) {
@@ -360,7 +372,8 @@ var RuntimeClient = class {
           message: isAbort ? "Request timed out" : error instanceof Error ? error.message : "Network error",
           retryable: this.retryPolicy.retryOnNetworkError ?? true,
           code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
-          traceId
+          traceId,
+          requestId: traceId
         });
         lastError = mapped;
         this.diagnostics.add({
@@ -391,6 +404,26 @@ var RuntimeClient = class {
   }
 };
 
+// ../src/sdk/errors.ts
+var WhisperError = class extends Error {
+  code;
+  status;
+  retryable;
+  hint;
+  requestId;
+  details;
+  constructor(args) {
+    super(args.message, args.cause ? { cause: args.cause } : void 0);
+    this.name = "WhisperError";
+    this.code = args.code;
+    this.status = args.status;
+    this.retryable = args.retryable ?? false;
+    this.hint = args.hint;
+    this.requestId = args.requestId;
+    this.details = args.details;
+  }
+};
+
 // ../src/sdk/core/cache.ts
 var SearchResponseCache = class {
   ttlMs;
@@ -2186,12 +2219,44 @@ ${lines.join("\n")}`;
 
 // ../src/sdk/whisper.ts
 var PROJECT_CACHE_TTL_MS = 3e4;
+var IDENTITY_WARNINGS = /* @__PURE__ */ new Set();
 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 randomRequestId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `req_${Math.random().toString(36).slice(2, 11)}`;
+}
+function parseIdentityMode(value) {
+  return value === "app-identity" ? "app-identity" : "demo-local";
+}
+function parseEnvironment(value) {
+  if (value === "staging" || value === "production") return value;
+  return "local";
+}
+function classifyRuntimeErrorCode(error) {
+  if (error.code === "MISSING_PROJECT") return "MISSING_PROJECT";
+  if (error.code === "TIMEOUT") return "TIMEOUT";
+  if (error.code === "NETWORK_ERROR") return "NETWORK_ERROR";
+  if (error.code === "VALIDATION_ERROR") return "VALIDATION_ERROR";
+  if (error.status === 401 || error.status === 403) return "INVALID_API_KEY";
+  if (error.status === 408) return "TIMEOUT";
+  if (error.status === 429) return "RATE_LIMITED";
+  if (error.status && error.status >= 500) return "TEMPORARY_UNAVAILABLE";
+  if (error.code === "PROJECT_NOT_FOUND" || error.code === "NOT_FOUND") return "PROJECT_NOT_FOUND";
+  return "REQUEST_FAILED";
+}
 var WhisperClient = class _WhisperClient {
   constructor(config) {
     this.config = config;
+    const env = typeof process !== "undefined" ? process.env : {};
+    this.identityMode = parseIdentityMode(config.identityMode || env.WHISPER_IDENTITY_MODE);
+    this.environment = parseEnvironment(config.environment || env.WHISPER_ENV || (env.NODE_ENV === "production" ? "production" : "local"));
+    this.strictIdentityMode = config.strictIdentityMode ?? env.WHISPER_DEMO_LOCAL_STRICT === "true";
+    this.getIdentity = config.getIdentity;
+    this.enforceIdentityModeGuardrail();
     this.diagnosticsStore = new DiagnosticsStore(config.telemetry?.maxEntries || 1e3);
     this.runtimeClient = new RuntimeClient(
       {
@@ -2301,26 +2366,29 @@ var WhisperClient = class _WhisperClient {
       status: () => this.writeQueue.status()
     };
     this.memory = {
-      add: (params) => this.memoryModule.add(params),
-      addBulk: (params) => this.memoryModule.addBulk(params),
-      search: (params) => this.memoryModule.search(params),
-      get: (memoryId) => this.memoryModule.get(memoryId),
-      getUserProfile: (params) => this.memoryModule.getUserProfile(params),
-      getSessionMemories: (params) => this.memoryModule.getSessionMemories(params),
-      update: (memoryId, params) => this.memoryModule.update(memoryId, params),
-      delete: (memoryId) => this.memoryModule.delete(memoryId),
-      flag: (params) => this.memoryModule.flag(params)
+      add: (params) => this.runOrThrow(async () => this.memoryModule.add(await this.withIdentity(params))),
+      addBulk: (params) => this.runOrThrow(async () => this.memoryModule.addBulk({
+        ...params,
+        memories: await Promise.all(params.memories.map((memory) => this.withIdentity(memory)))
+      })),
+      search: (params) => this.runOrThrow(async () => this.memoryModule.search(await this.withIdentity(params))),
+      get: (memoryId) => this.runOrThrow(async () => this.memoryModule.get(memoryId)),
+      getUserProfile: (params) => this.runOrThrow(async () => this.profileModule.getUserProfile(await this.withIdentity(params, true))),
+      getSessionMemories: (params) => this.runOrThrow(async () => this.profileModule.getSessionMemories(await this.withIdentity(params))),
+      update: (memoryId, params) => this.runOrThrow(async () => this.memoryModule.update(memoryId, params)),
+      delete: (memoryId) => this.runOrThrow(async () => this.memoryModule.delete(memoryId)),
+      flag: (params) => this.runOrThrow(async () => this.memoryModule.flag(params))
     };
     this.session = {
-      start: (params) => this.sessionModule.start(params),
-      event: (params) => this.sessionModule.event(params),
-      suspend: (params) => this.sessionModule.suspend(params),
-      resume: (params) => this.sessionModule.resume(params),
-      end: (params) => this.sessionModule.end(params)
+      start: (params) => this.runOrThrow(async () => this.sessionModule.start(await this.withSessionIdentity(params))),
+      event: (params) => this.runOrThrow(async () => this.sessionModule.event(params)),
+      suspend: (params) => this.runOrThrow(async () => this.sessionModule.suspend(params)),
+      resume: (params) => this.runOrThrow(async () => this.sessionModule.resume(params)),
+      end: (params) => this.runOrThrow(async () => this.sessionModule.end(params))
     };
     this.profile = {
-      getUserProfile: (params) => this.profileModule.getUserProfile(params),
-      getSessionMemories: (params) => this.profileModule.getSessionMemories(params)
+      getUserProfile: (params) => this.runOrThrow(async () => this.profileModule.getUserProfile(await this.withIdentity(params, true))),
+      getSessionMemories: (params) => this.runOrThrow(async () => this.profileModule.getSessionMemories(await this.withIdentity(params)))
     };
     this.analytics = {
       diagnosticsSnapshot: () => this.analyticsModule.diagnosticsSnapshot(),
@@ -2342,18 +2410,158 @@ var WhisperClient = class _WhisperClient {
   profileModule;
   analyticsModule;
   projectRefToId = /* @__PURE__ */ new Map();
+  identityMode;
+  environment;
+  strictIdentityMode;
+  getIdentity;
   projectCache = [];
   projectCacheExpiresAt = 0;
+  enforceIdentityModeGuardrail(requestId = randomRequestId()) {
+    if (this.identityMode !== "demo-local") return;
+    if (this.environment === "local") return;
+    const message = "[Whisper SDK] WHISPER_IDENTITY_MODE=demo-local is intended only for local development. Switch to app-identity and provide getIdentity() or per-call user_id/session_id.";
+    if (this.strictIdentityMode || this.environment === "production") {
+      throw new WhisperError({
+        code: "MISCONFIGURED_IDENTITY_MODE",
+        message,
+        retryable: false,
+        hint: "Set identityMode: 'app-identity' and provide a getIdentity() function that returns { userId, sessionId? }. To override for testing, set environment: 'local' explicitly."
+      });
+    }
+    const warningKey = `${this.environment}:${this.identityMode}`;
+    if (!IDENTITY_WARNINGS.has(warningKey)) {
+      IDENTITY_WARNINGS.add(warningKey);
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(`${message} requestId=${requestId}`);
+      }
+    }
+  }
+  toWhisperError(error, hint) {
+    if (error instanceof WhisperError) return error;
+    if (error instanceof RuntimeClientError) {
+      return new WhisperError({
+        code: classifyRuntimeErrorCode(error),
+        message: error.message,
+        status: error.status,
+        retryable: error.retryable,
+        hint: error.hint || hint,
+        requestId: error.requestId || error.traceId,
+        details: error.details,
+        cause: error
+      });
+    }
+    if (error instanceof Error) {
+      return new WhisperError({
+        code: "REQUEST_FAILED",
+        message: error.message,
+        retryable: false,
+        hint,
+        cause: error
+      });
+    }
+    return new WhisperError({
+      code: "REQUEST_FAILED",
+      message: "Unknown SDK error",
+      retryable: false,
+      hint,
+      details: error
+    });
+  }
+  async runOrThrow(work, hint) {
+    try {
+      return await work();
+    } catch (error) {
+      throw this.toWhisperError(error, hint);
+    }
+  }
+  async resolveIdentityOverride() {
+    if (!this.getIdentity) return null;
+    const resolved = await this.getIdentity();
+    const userId = String(resolved?.userId || "").trim();
+    const sessionId = resolved?.sessionId ? String(resolved.sessionId).trim() : void 0;
+    if (!userId) {
+      throw new WhisperError({
+        code: "AUTH_IDENTITY_INVALID",
+        message: "getIdentity() returned an invalid identity payload.",
+        retryable: false,
+        hint: "Return { userId, sessionId? } from getIdentity()."
+      });
+    }
+    return {
+      userId,
+      sessionId: sessionId || void 0
+    };
+  }
+  async withIdentity(params, requireUser = false) {
+    const currentUser = params.user_id ? String(params.user_id).trim() : "";
+    const currentSession = params.session_id ? String(params.session_id).trim() : "";
+    if (currentUser) {
+      return {
+        ...params,
+        user_id: currentUser,
+        session_id: currentSession || params.session_id
+      };
+    }
+    const resolved = await this.resolveIdentityOverride();
+    if (resolved) {
+      return {
+        ...params,
+        user_id: resolved.userId,
+        session_id: currentSession || resolved.sessionId
+      };
+    }
+    if (requireUser || this.identityMode === "app-identity") {
+      throw new WhisperError({
+        code: "AUTH_IDENTITY_REQUIRED",
+        message: "A user identity is required in app-identity mode.",
+        retryable: false,
+        hint: "Provide user_id/session_id per call or configure getIdentity() in WhisperClient."
+      });
+    }
+    return params;
+  }
+  async withSessionIdentity(params) {
+    const userId = params.userId ? String(params.userId).trim() : "";
+    const sessionId = params.sessionId ? String(params.sessionId).trim() : "";
+    if (userId) {
+      return {
+        ...params,
+        userId,
+        sessionId: sessionId || params.sessionId
+      };
+    }
+    const resolved = await this.resolveIdentityOverride();
+    if (resolved?.userId) {
+      return {
+        ...params,
+        userId: resolved.userId,
+        sessionId: sessionId || resolved.sessionId
+      };
+    }
+    throw new WhisperError({
+      code: "AUTH_IDENTITY_REQUIRED",
+      message: "Session operations require a user identity.",
+      retryable: false,
+      hint: "Pass userId explicitly or configure getIdentity() in WhisperClient."
+    });
+  }
   static fromEnv(overrides = {}) {
     const env = typeof process !== "undefined" ? process.env : {};
     const apiKey = overrides.apiKey || env.WHISPER_API_KEY || env.USEWHISPER_API_KEY || env.API_KEY;
     if (!apiKey) {
-      throw new Error("Missing API key. Set WHISPER_API_KEY / USEWHISPER_API_KEY / API_KEY.");
+      throw new WhisperError({
+        code: "INVALID_API_KEY",
+        message: "Missing API key. Set WHISPER_API_KEY / USEWHISPER_API_KEY / API_KEY.",
+        retryable: false
+      });
     }
     return new _WhisperClient({
       apiKey,
       baseUrl: overrides.baseUrl || env.WHISPER_BASE_URL || env.API_BASE_URL || "https://context.usewhisper.dev",
       project: overrides.project || env.WHISPER_PROJECT || env.PROJECT,
+      identityMode: overrides.identityMode || parseIdentityMode(env.WHISPER_IDENTITY_MODE),
+      environment: overrides.environment || parseEnvironment(env.WHISPER_ENV || (env.NODE_ENV === "production" ? "production" : "local")),
+      strictIdentityMode: overrides.strictIdentityMode ?? env.WHISPER_DEMO_LOCAL_STRICT === "true",
       ...overrides
     });
   }
@@ -2390,10 +2598,11 @@ var WhisperClient = class _WhisperClient {
   getRequiredProject(project) {
     const resolved = project || this.config.project;
     if (!resolved) {
-      throw new RuntimeClientError({
+      throw new WhisperError({
         code: "MISSING_PROJECT",
         message: "Project is required",
-        retryable: false
+        retryable: false,
+        hint: "Pass project in the call or configure a default project in WhisperClient."
       });
     }
     return resolved;
@@ -2435,81 +2644,182 @@ var WhisperClient = class _WhisperClient {
     }
   }
   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;
+    return this.runOrThrow(async () => {
+      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 WhisperError({
+        code: "PROJECT_NOT_FOUND",
+        message: `Project '${resolvedRef}' not found`,
+        retryable: false
+      });
+    });
+  }
+  async preflight(options) {
+    const requestId = randomRequestId();
+    const checks = [];
+    try {
+      this.enforceIdentityModeGuardrail(requestId);
+    } catch (error) {
+      throw this.toWhisperError(error, "Update identity mode before running preflight.");
+    }
+    const apiKeyOk = typeof this.config.apiKey === "string" && this.config.apiKey.trim().length > 0;
+    checks.push({
+      check: "api_key",
+      ok: apiKeyOk,
+      message: apiKeyOk ? "API key is configured." : "Missing API key.",
+      hint: apiKeyOk ? void 0 : "Set WHISPER_API_KEY or pass apiKey to WhisperClient."
+    });
+    try {
+      await this.runtimeClient.request({
+        endpoint: "/v1/projects",
+        method: "GET",
+        operation: "get",
+        idempotent: true,
+        traceId: requestId
+      });
+      checks.push({
+        check: "api_connectivity",
+        ok: true,
+        message: "Connected to Whisper API."
+      });
+    } catch (error) {
+      const mapped = this.toWhisperError(error, "Confirm WHISPER_BASE_URL and API key permissions.");
+      checks.push({
+        check: "api_connectivity",
+        ok: false,
+        message: mapped.message,
+        hint: mapped.hint
+      });
     }
-    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;
+    const projectRef = options?.project || this.config.project;
+    if (projectRef) {
+      try {
+        await this.resolveProject(projectRef);
+        checks.push({
+          check: "project_access",
+          ok: true,
+          message: `Project '${projectRef}' is reachable.`
+        });
+      } catch (error) {
+        const mapped = this.toWhisperError(error, "Create or grant access to the configured project.");
+        checks.push({
+          check: "project_access",
+          ok: false,
+          message: mapped.message,
+          hint: mapped.hint
+        });
+      }
+    } else {
+      checks.push({
+        check: "project_access",
+        ok: true,
+        message: "No default project configured (project will be required per call)."
+      });
     }
-    if (isLikelyProjectId(resolvedRef)) {
-      return {
-        id: resolvedRef,
-        orgId: "",
-        name: resolvedRef,
-        slug: resolvedRef,
-        createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
-        updatedAt: (/* @__PURE__ */ new Date(0)).toISOString()
-      };
+    if (options?.requireIdentity || this.identityMode === "app-identity") {
+      try {
+        const identity = await this.resolveIdentityOverride();
+        const ok = Boolean(identity?.userId);
+        checks.push({
+          check: "identity_resolution",
+          ok,
+          message: ok ? "Identity resolver is configured." : "Identity resolver is missing.",
+          hint: ok ? void 0 : "Provide getIdentity() or pass user_id/session_id per call."
+        });
+      } catch (error) {
+        const mapped = this.toWhisperError(error, "Fix identity resolver output before production usage.");
+        checks.push({
+          check: "identity_resolution",
+          ok: false,
+          message: mapped.message,
+          hint: mapped.hint
+        });
+      }
     }
-    throw new RuntimeClientError({
-      code: "PROJECT_NOT_FOUND",
-      message: `Project '${resolvedRef}' not found`,
-      retryable: false
-    });
+    return {
+      ok: checks.every((check) => check.ok),
+      checks,
+      requestId,
+      identityMode: this.identityMode,
+      environment: this.environment
+    };
   }
   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 this.runOrThrow(async () => {
+      const identityParams = await this.withIdentity(params);
+      const project = (await this.resolveProject(identityParams.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/context/query",
+        method: "POST",
+        operation: "search",
+        body: {
+          ...identityParams,
+          project
+        },
+        idempotent: true
+      });
+      return response.data;
     });
-    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 this.runOrThrow(async () => {
+      const identityParams = await this.withIdentity(params);
+      const project = (await this.resolveProject(identityParams.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/memory/ingest/session",
+        method: "POST",
+        operation: "session",
+        body: {
+          ...identityParams,
+          project
+        }
+      });
+      return response.data;
     });
-    return response.data;
   }
   async learn(params) {
-    const project = (await this.resolveProject(params.project)).id;
-    const response = await this.runtimeClient.request({
-      endpoint: "/v1/learn",
-      method: "POST",
-      operation: params.mode === "conversation" ? "session" : "bulk",
-      body: {
-        ...params,
-        project
-      }
+    return this.runOrThrow(async () => {
+      const identityParams = params.mode === "conversation" ? await this.withIdentity(params) : params;
+      const project = (await this.resolveProject(identityParams.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/learn",
+        method: "POST",
+        operation: params.mode === "conversation" ? "session" : "bulk",
+        body: {
+          ...identityParams,
+          project
+        }
+      });
+      return response.data;
     });
-    return response.data;
   }
   createAgentRuntime(options = {}) {
     const baseContext = {
@@ -2571,26 +2881,60 @@ var WhisperClient = class _WhisperClient {
       diagnostics: base.diagnostics
     };
   }
+  async deleteSource(sourceId) {
+    return this.runOrThrow(async () => {
+      const response = await this.runtimeClient.request({
+        endpoint: `/v1/sources/${sourceId}`,
+        method: "DELETE",
+        operation: "writeAck"
+      });
+      return response.data;
+    });
+  }
+  async extractMemories(params) {
+    return this.runOrThrow(async () => {
+      const project = (await this.resolveProject(params.project)).id;
+      const response = await this.runtimeClient.request({
+        endpoint: "/v1/memory/extract",
+        method: "POST",
+        operation: "writeAck",
+        body: { project, message: params.message }
+      });
+      return response.data;
+    });
+  }
   async shutdown() {
     await this.writeQueue.stop();
   }
 };
 
+// ../src/sdk/adapters/tools.ts
+import { z } from "zod";
+var searchInputSchema = z.object({
+  q: z.string().min(1),
+  project: z.string().optional(),
+  topK: z.number().int().positive().max(50).optional(),
+  userId: z.string().optional(),
+  sessionId: z.string().optional()
+});
+var rememberInputSchema = z.object({
+  content: z.string().min(1),
+  project: z.string().optional(),
+  memoryType: z.enum([
+    "factual",
+    "preference",
+    "event",
+    "relationship",
+    "opinion",
+    "goal",
+    "instruction"
+  ]).optional(),
+  userId: z.string().optional(),
+  sessionId: z.string().optional(),
+  metadata: z.record(z.unknown()).optional()
+});
+
 // ../src/sdk/index.ts
-var WhisperError = class extends Error {
-  code;
-  status;
-  retryable;
-  details;
-  constructor(args) {
-    super(args.message);
-    this.name = "WhisperError";
-    this.code = args.code;
-    this.status = args.status;
-    this.retryable = args.retryable ?? false;
-    this.details = args.details;
-  }
-};
 var DEFAULT_MAX_ATTEMPTS = 3;
 var DEFAULT_BASE_DELAY_MS = 250;
 var DEFAULT_MAX_DELAY_MS = 2e3;
@@ -2961,7 +3305,10 @@ var WhisperContext = class _WhisperContext {
         message,
         status: error.status,
         retryable,
-        details: error.details
+        hint: error.hint,
+        requestId: error.requestId || error.traceId,
+        details: error.details,
+        cause: error
       });
     }
   }
@@ -4711,12 +5058,28 @@ async function ingestSessionWithSyncFallback(params) {
     return whisper.ingestSession(params);
   }
 }
+function apiKeyFingerprint(apiKey) {
+  const value = String(apiKey || "").trim();
+  if (!value) return "anon";
+  return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
 function defaultMcpUserId(params) {
   const explicit = process.env.WHISPER_USER_ID?.trim();
   if (explicit) return explicit;
+  let osUsername = process.env.USER?.trim() || process.env.USERNAME?.trim();
+  if (!osUsername) {
+    try {
+      osUsername = userInfo().username?.trim();
+    } catch {
+      osUsername = "";
+    }
+  }
+  if (!osUsername) {
+    throw new Error("Unable to derive user identity. Set WHISPER_USER_ID or pass user_id.");
+  }
   const workspacePath = params?.workspacePath || canonicalizeWorkspacePath(process.cwd());
   const projectRef = params?.project || DEFAULT_PROJECT || "default";
-  const seed = `${workspacePath}|${projectRef}|${API_KEY.slice(0, 12) || "anon"}`;
+  const seed = `${workspacePath}|${projectRef}|${apiKeyFingerprint(API_KEY)}|${osUsername.toLowerCase()}`;
   return `mcp-user-${createHash("sha256").update(seed).digest("hex").slice(0, 12)}`;
 }
 function resolveMcpScope(params, options) {
@@ -4732,6 +5095,68 @@ function resolveMcpScope(params, options) {
     workspacePath
   };
 }
+function resolveMemoryScope(params) {
+  const base = resolveMcpScope({
+    project: params?.project,
+    user_id: params?.user_id,
+    session_id: params?.session_id,
+    path: params?.path
+  });
+  const scopeMode = params?.scope === "shared_project" ? "shared_project" : "personal";
+  if (scopeMode === "shared_project") {
+    if (!base.project && !DEFAULT_PROJECT) {
+      throw new Error("shared_project scope requires a project. Set WHISPER_PROJECT or pass project.");
+    }
+    const projectRef = base.project || DEFAULT_PROJECT || "default";
+    return {
+      ...base,
+      userId: `shared-project:${projectRef}`,
+      sessionId: void 0,
+      actorUserId: base.userId,
+      actorSessionId: base.sessionId,
+      scopeMode,
+      sharedProjectRef: projectRef
+    };
+  }
+  return {
+    ...base,
+    actorUserId: base.userId,
+    actorSessionId: base.sessionId,
+    scopeMode,
+    sharedProjectRef: null
+  };
+}
+function sharedProjectMemoryUserId(projectRef) {
+  return `shared-project:${projectRef}`;
+}
+function buildMemoryScopeMetadata(args) {
+  const { memoryScope } = args;
+  const metadata = {
+    scope: memoryScope.scopeMode,
+    ...memoryScope.sharedProjectRef ? { shared_project_ref: memoryScope.sharedProjectRef } : {}
+  };
+  if (memoryScope.scopeMode === "shared_project") {
+    metadata.provenance = {
+      writer_user_id: memoryScope.actorUserId,
+      writer_session_id: memoryScope.actorSessionId || null,
+      writer_agent_id: args.agent_id || process.env.WHISPER_AGENT_ID || null,
+      written_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  return metadata;
+}
+function isMemoryInScope(args) {
+  const memory = args.memory;
+  if (!memory || typeof memory !== "object") return false;
+  const memoryUserId = String(memory.userId || memory.user_id || "").trim();
+  if (args.memoryScope.scopeMode === "shared_project") {
+    const metadata = memory.metadata && typeof memory.metadata === "object" ? memory.metadata : {};
+    const metaScope = String(metadata.scope || "").trim();
+    const metaProjectRef = String(metadata.shared_project_ref || "").trim();
+    return memoryUserId === args.memoryScope.userId || metaScope === "shared_project" && metaProjectRef === (args.memoryScope.sharedProjectRef || "");
+  }
+  return memoryUserId === args.memoryScope.userId;
+}
 function noteAutomaticSourceActivity(params) {
   if (!runtimeClient) return;
   const sourceIds = [...new Set((params.sourceIds || []).map((value) => String(value || "").trim()).filter(Boolean))];
@@ -5298,6 +5723,82 @@ function resolveForgetQueryCandidates(rawResults, query) {
   }
   return { memory_ids: [], resolved_by: "none", warning: "Query did not resolve to a reliable memory match. No memories were changed." };
 }
+async function searchMemoriesForContextQuery(args) {
+  return whisper.searchMemoriesSOTA({
+    project: args.project,
+    query: args.query,
+    user_id: args.user_id,
+    session_id: args.session_id,
+    top_k: args.top_k ?? 5,
+    include_relations: false,
+    include_pending: true
+  });
+}
+async function runContextQueryMemoryRescue(args) {
+  const scoped = await searchMemoriesForContextQuery(args);
+  const personalResults = formatCanonicalMemoryResults(scoped);
+  const sharedUserId = sharedProjectMemoryUserId(args.project);
+  const shared = args.user_id === sharedUserId ? { results: [] } : await searchMemoriesForContextQuery({
+    project: args.project,
+    query: args.query,
+    user_id: sharedUserId,
+    top_k: args.top_k
+  });
+  const sharedResults = formatCanonicalMemoryResults(shared);
+  const deduped = /* @__PURE__ */ new Set();
+  const combined = [
+    ...personalResults.map((result) => ({
+      ...result,
+      memory_scope: "personal",
+      ranking_score: clamp012(Number(result.similarity ?? 0.5) + 0.08)
+    })),
+    ...sharedResults.map((result) => ({
+      ...result,
+      memory_scope: "shared_project",
+      ranking_score: clamp012(Number(result.similarity ?? 0.5))
+    }))
+  ].filter((result) => {
+    if (!result.id) return false;
+    if (deduped.has(result.id)) return false;
+    deduped.add(result.id);
+    return true;
+  }).sort((a, b) => b.ranking_score - a.ranking_score);
+  const rescueMode = combined.length === 0 ? null : sharedResults.length > 0 ? "scoped_plus_shared" : "scoped_only";
+  return {
+    personal_results: personalResults,
+    shared_results: sharedResults,
+    combined_results: combined,
+    rescue_mode: rescueMode
+  };
+}
+function renderContextQueryMemoryRescue(args) {
+  const lines = args.combined_results.map(
+    (result, index) => `${index + 1}. [${result.memory_scope}, ${result.memory_type || "memory"}, score: ${result.ranking_score.toFixed(2)}] ${result.content}`
+  );
+  return `Found ${args.combined_results.length} memory result(s) (project=${args.project}, user=${args.scope.userId}, session=${args.scope.sessionId}, personal=${args.personal_results.length}, shared=${args.shared_results.length}, ordering=personal_then_shared_bias):
+
+${lines.join("\n\n")}`;
+}
+function memoryRescueResultsToEvidence(args) {
+  return args.hits.map(
+    (hit) => toEvidenceRef({
+      id: `memory:${hit.id || randomUUID()}`,
+      source: "memory",
+      document: "memory",
+      content: hit.content,
+      score: hit.ranking_score,
+      retrieval_source: "memory",
+      metadata: {
+        path: `memory://${hit.memory_scope}/${hit.id || "unknown"}`,
+        line_start: 1,
+        line_end: 1,
+        score: hit.ranking_score,
+        memory_scope: hit.memory_scope,
+        memory_type: hit.memory_type || "factual"
+      }
+    }, args.workspaceId, "memory")
+  );
+}
 function likelyEmbeddingFailure(error) {
   const message = String(error?.message || error || "").toLowerCase();
   return message.includes("embedding") || message.includes("vector") || message.includes("timeout") || message.includes("timed out") || message.includes("temporarily unavailable");
@@ -5974,9 +6475,9 @@ server.tool(
   "index.workspace_resolve",
   "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()
+    path: z2.string().optional().describe("Workspace path. Defaults to current working directory."),
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional()
   },
   async ({ path, workspace_id, project }) => {
     try {
@@ -6013,8 +6514,8 @@ server.tool(
   "index.workspace_status",
   "Check index freshness, coverage, commit, and pending changes before retrieval/edits.",
   {
-    workspace_id: z.string().optional(),
-    path: z.string().optional()
+    workspace_id: z2.string().optional(),
+    path: z2.string().optional()
   },
   async ({ workspace_id, path }) => {
     try {
@@ -6051,10 +6552,10 @@ server.tool(
   "index.workspace_run",
   "Refresh local workspace index metadata (coverage, commit, freshness) for trust checks. This does not upload files or create backend embeddings.",
   {
-    workspace_id: z.string().optional(),
-    path: z.string().optional(),
-    mode: z.enum(["full", "incremental"]).optional().default("incremental"),
-    max_files: z.number().optional().default(1500)
+    workspace_id: z2.string().optional(),
+    path: z2.string().optional(),
+    mode: z2.enum(["full", "incremental"]).optional().default("incremental"),
+    max_files: z2.number().optional().default(1500)
   },
   async ({ workspace_id, path, mode, max_files }) => {
     try {
@@ -6100,11 +6601,11 @@ server.tool(
   "index.local_scan_ingest",
   "Ingest local files into Whisper backend (chunk/embed/index) and persist incremental manifest. Requires WHISPER_MCP_MODE=auto or local.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    path: z.string().optional().describe("Local path to ingest. Defaults to current working directory."),
-    glob: z.string().optional().describe("Optional include glob"),
-    max_files: z.number().optional().default(200),
-    chunk_chars: z.number().optional().default(2e4)
+    project: z2.string().optional().describe("Project name or slug"),
+    path: z2.string().optional().describe("Local path to ingest. Defaults to current working directory."),
+    glob: z2.string().optional().describe("Optional include glob"),
+    max_files: z2.number().optional().default(200),
+    chunk_chars: z2.number().optional().default(2e4)
   },
   async ({ project, path, glob, max_files, chunk_chars }) => {
     try {
@@ -6136,12 +6637,12 @@ server.tool(
   "index.auto_repair",
   "Diagnose and apply deterministic retrieval/setup repairs. This is the canonical zero-stress repair path.",
   {
-    path: z.string().optional(),
-    workspace_id: z.string().optional(),
-    project: z.string().optional(),
-    apply: z.boolean().optional().default(true),
-    repair_scope: z.enum(["safe", "full"]).optional().default("safe"),
-    allow_restart_hint: z.boolean().optional().default(true)
+    path: z2.string().optional(),
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional(),
+    apply: z2.boolean().optional().default(true),
+    repair_scope: z2.enum(["safe", "full"]).optional().default("safe"),
+    allow_restart_hint: z2.boolean().optional().default(true)
   },
   async ({ path, workspace_id, project, apply, repair_scope, allow_restart_hint }) => {
     try {
@@ -6163,12 +6664,12 @@ server.tool(
   "fix",
   "Primary alias for zero-stress setup/retrieval repair. Delegates to index.auto_repair.",
   {
-    path: z.string().optional(),
-    workspace_id: z.string().optional(),
-    project: z.string().optional(),
-    apply: z.boolean().optional().default(true),
-    repair_scope: z.enum(["safe", "full"]).optional().default("safe"),
-    allow_restart_hint: z.boolean().optional().default(true)
+    path: z2.string().optional(),
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional(),
+    apply: z2.boolean().optional().default(true),
+    repair_scope: z2.enum(["safe", "full"]).optional().default("safe"),
+    allow_restart_hint: z2.boolean().optional().default(true)
   },
   async ({ path, workspace_id, project, apply, repair_scope, allow_restart_hint }) => {
     try {
@@ -6244,6 +6745,7 @@ async function runUnifiedContextRetrieval(params) {
   let retrievalReadiness = preflight.retrieval_readiness;
   let retrievalRoute = preflight.retrieval_route;
   let latencyMs = 0;
+  let memoryContribution = null;
   if (preflight.retrieval_route === "local_workspace_fallback") {
     const localRetrieval = await runLocalWorkspaceRetrieval({
       query: params.question,
@@ -6302,6 +6804,39 @@ async function runUnifiedContextRetrieval(params) {
       retrievalRoute = preflight.repo_grounded ? "project_repo" : "none";
     }
   }
+  if (resolvedProject && params.include_memories === true && !preflight.repo_grounded) {
+    try {
+      memoryContribution = await runContextQueryMemoryRescue({
+        project: resolvedProject,
+        query: params.question,
+        user_id: scope.userId,
+        session_id: params.session_id,
+        top_k: Math.max(4, Math.min(topK, 8))
+      });
+      if (memoryContribution.combined_results.length > 0) {
+        const memoryEvidence = memoryRescueResultsToEvidence({
+          workspaceId: preflight.trust_state.workspace_id,
+          hits: memoryContribution.combined_results
+        });
+        const existingSourceIds = new Set(evidence.map((item) => item.source_id));
+        const dedupedMemoryEvidence = memoryEvidence.filter((item) => !existingSourceIds.has(item.source_id));
+        evidence = [...evidence, ...dedupedMemoryEvidence];
+        const memoryContext = renderContextQueryMemoryRescue({
+          project: resolvedProject,
+          scope,
+          personal_results: memoryContribution.personal_results,
+          shared_results: memoryContribution.shared_results,
+          combined_results: memoryContribution.combined_results
+        });
+        contextText = contextText.trim().length > 0 ? `${contextText}
+
+${memoryContext}` : memoryContext;
+        if (retrievalRoute === "none") retrievalRoute = "memory_only";
+      }
+    } catch (error) {
+      warnings.push(`Scoped memory contribution failed: ${String(error?.message || error)}`);
+    }
+  }
   recordSemanticAttempt(preflight.trust_state.workspace_id, semanticStatus === "failed");
   const semanticStats = getWorkspaceSemanticFailureStats(preflight.trust_state.workspace_id);
   const trustScore = computeTrustScore({
@@ -6374,6 +6909,14 @@ async function runUnifiedContextRetrieval(params) {
         user_id: scope.userId,
         session_id: params.session_id || null
       },
+      memory: {
+        included: resolvedProject ? params.include_memories === true && !preflight.repo_grounded : false,
+        personal_count: memoryContribution?.personal_results.length || 0,
+        shared_count: memoryContribution?.shared_results.length || 0,
+        combined_count: memoryContribution?.combined_results.length || 0,
+        shared_user_id: resolvedProject ? sharedProjectMemoryUserId(resolvedProject) : null,
+        ordering: "personal_then_shared_bias"
+      },
       retrieval_profile: retrievalProfile,
       trust_score: trustScore,
       semantic_failure_rate: semanticStats.rate,
@@ -6383,7 +6926,11 @@ async function runUnifiedContextRetrieval(params) {
     }
   };
   if (params.include_alias_warning) {
-    payload.warnings = Array.from(/* @__PURE__ */ new Set([...payload.warnings, "deprecated_alias_use_context.query"]));
+    payload.warnings = Array.from(/* @__PURE__ */ new Set([
+      ...payload.warnings,
+      "deprecated_alias_use_context_query",
+      "deprecated_alias_use_context.query"
+    ]));
   }
   return payload;
 }
@@ -6391,17 +6938,17 @@ server.tool(
   "context.get_relevant",
   "Default grounded retrieval step for workspace/project questions. Returns ranked evidence with file:line citations and may abstain when workspace/repo trust is not ready.",
   {
-    question: z.string().describe("Task/question to retrieve context for"),
-    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
-    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(),
-    include_parent_content: z.boolean().optional().default(false),
-    retrieval_profile: z.enum(MCP_RETRIEVAL_PROFILE_VALUES).optional()
+    question: z2.string().describe("Task/question to retrieve context for"),
+    path: z2.string().optional().describe("Workspace path. Defaults to current working directory."),
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional(),
+    top_k: z2.number().optional().default(12),
+    include_memories: z2.boolean().optional().default(true),
+    include_graph: z2.boolean().optional().default(true),
+    session_id: z2.string().optional(),
+    user_id: z2.string().optional(),
+    include_parent_content: z2.boolean().optional().default(false),
+    retrieval_profile: z2.enum(MCP_RETRIEVAL_PROFILE_VALUES).optional()
   },
   async ({ question, path, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id, include_parent_content, retrieval_profile }) => {
     try {
@@ -6429,12 +6976,12 @@ server.tool(
   "context.claim_verify",
   "Verify whether a claim is supported by retrieved context. Returns supported/partial/unsupported with evidence.",
   {
-    claim: z.string().describe("Claim to verify"),
-    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
-    workspace_id: z.string().optional(),
-    project: z.string().optional(),
-    context_ids: z.array(z.string()).optional(),
-    strict: z.boolean().optional().default(true)
+    claim: z2.string().describe("Claim to verify"),
+    path: z2.string().optional().describe("Workspace path. Defaults to current working directory."),
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional(),
+    context_ids: z2.array(z2.string()).optional(),
+    strict: z2.boolean().optional().default(true)
   },
   async ({ claim, path, workspace_id, project, context_ids, strict }) => {
     try {
@@ -6504,20 +7051,20 @@ server.tool(
   "context.evidence_answer",
   "Answer a question only when evidence requirements are met. Fails closed with an abstain payload when not verifiable.",
   {
-    question: z.string(),
-    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
-    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)
+    question: z2.string(),
+    path: z2.string().optional().describe("Workspace path. Defaults to current working directory."),
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional(),
+    constraints: z2.object({
+      require_citations: z2.boolean().optional().default(true),
+      min_evidence_items: z2.number().optional().default(2),
+      min_confidence: z2.number().optional().default(0.65),
+      max_staleness_hours: z2.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)
+    retrieval: z2.object({
+      top_k: z2.number().optional().default(12),
+      include_symbols: z2.boolean().optional().default(true),
+      include_recent_decisions: z2.boolean().optional().default(true)
     }).optional()
   },
   async ({ question, path, workspace_id, project, constraints, retrieval }) => {
@@ -6630,18 +7177,18 @@ server.tool(
   "context.query",
   "Use this when answering from project knowledge rather than general model memory. Retrieves packed context and auto-falls back between repo, local, and memory routes based on trust/readiness.",
   {
-    project: z.string().optional().describe("Project name or slug (optional if WHISPER_PROJECT is set)"),
-    query: z.string().describe("What are you looking for?"),
-    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
-    top_k: z.number().optional().default(10).describe("Number of results"),
-    chunk_types: z.array(z.string()).optional().describe("Filter: code, function, class, documentation, api_spec, schema, config, text"),
-    include_memories: z.boolean().optional().describe("Include relevant memories. Omit to use automatic runtime defaults."),
-    include_graph: z.boolean().optional().default(false).describe("Include knowledge graph traversal"),
-    user_id: z.string().optional().describe("User ID for memory scoping"),
-    session_id: z.string().optional().describe("Session ID for memory scoping"),
-    max_tokens: z.number().optional().describe("Max tokens for packed context"),
-    include_parent_content: z.boolean().optional().default(false),
-    retrieval_profile: z.enum(MCP_RETRIEVAL_PROFILE_VALUES).optional()
+    project: z2.string().optional().describe("Project name or slug (optional if WHISPER_PROJECT is set)"),
+    query: z2.string().describe("What are you looking for?"),
+    path: z2.string().optional().describe("Workspace path. Defaults to current working directory."),
+    top_k: z2.number().optional().default(10).describe("Number of results"),
+    chunk_types: z2.array(z2.string()).optional().describe("Filter: code, function, class, documentation, api_spec, schema, config, text"),
+    include_memories: z2.boolean().optional().describe("Include relevant memories. Omit to use automatic runtime defaults."),
+    include_graph: z2.boolean().optional().default(false).describe("Include knowledge graph traversal"),
+    user_id: z2.string().optional().describe("User ID for memory scoping"),
+    session_id: z2.string().optional().describe("Session ID for memory scoping"),
+    max_tokens: z2.number().optional().describe("Max tokens for packed context"),
+    include_parent_content: z2.boolean().optional().default(false),
+    retrieval_profile: z2.enum(MCP_RETRIEVAL_PROFILE_VALUES).optional()
   },
   async ({ project, query, path, top_k, chunk_types, include_memories, include_graph, user_id, session_id, max_tokens, include_parent_content, retrieval_profile }) => {
     try {
@@ -6668,25 +7215,30 @@ server.tool(
   "memory.add",
   "Store a memory (fact, preference, decision) that persists across conversations. Memories can be scoped to a user, session, or agent.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    content: z.string().describe("The memory content to store"),
-    memory_type: z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"]).optional().default("factual"),
-    user_id: z.string().optional().describe("User this memory belongs to"),
-    session_id: z.string().optional().describe("Session scope"),
-    agent_id: z.string().optional().describe("Agent scope"),
-    importance: z.number().optional().default(0.5).describe("Importance 0-1")
+    project: z2.string().optional().describe("Project name or slug"),
+    content: z2.string().describe("The memory content to store"),
+    memory_type: z2.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"]).optional().default("factual"),
+    scope: z2.enum(["personal", "shared_project"]).optional().default("personal"),
+    user_id: z2.string().optional().describe("User this memory belongs to"),
+    session_id: z2.string().optional().describe("Session scope"),
+    agent_id: z2.string().optional().describe("Agent scope"),
+    importance: z2.number().optional().default(0.5).describe("Importance 0-1")
   },
-  async ({ project, content, memory_type, user_id, session_id, agent_id, importance }) => {
+  async ({ project, content, memory_type, scope, user_id, session_id, agent_id, importance }) => {
     try {
-      const scope = resolveMcpScope({ project, user_id, session_id });
+      const memoryScope = resolveMemoryScope({ project, user_id, session_id, scope });
       const result = await whisper.addMemory({
-        project: scope.project,
+        project: memoryScope.project,
         content,
         memory_type,
-        user_id: scope.userId,
-        session_id: scope.sessionId,
+        user_id: memoryScope.userId,
+        session_id: memoryScope.sessionId,
         agent_id,
-        importance
+        importance,
+        metadata: buildMemoryScopeMetadata({
+          memoryScope,
+          agent_id
+        })
       });
       const memoryId = result?.memory_id || result.id;
       const jobId = result?.job_id;
@@ -6699,12 +7251,16 @@ server.tool(
         mode: mode || null,
         semantic_status: semanticStatus || null,
         memory_type: memory_type || "factual",
+        scope: memoryScope.scopeMode,
         queued: mode === "async" || Boolean(jobId),
         diagnostics: {
           scope: {
-            project: scope.project || null,
-            user_id: scope.userId,
-            session_id: scope.sessionId || null
+            project: memoryScope.project || null,
+            user_id: memoryScope.userId,
+            session_id: memoryScope.sessionId || null,
+            scope: memoryScope.scopeMode,
+            actor_user_id: memoryScope.actorUserId,
+            actor_session_id: memoryScope.actorSessionId || null
           }
         }
       });
@@ -6717,30 +7273,31 @@ server.tool(
   "memory.search",
   "Call this before answering questions about user history (preferences, prior decisions, past tasks, or 'what did we discuss/search'). Returns memory context you would not otherwise know.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    query: z.string().describe("What to search for"),
-    user_id: z.string().optional().describe("Filter by user"),
-    session_id: z.string().optional().describe("Filter by session"),
-    top_k: z.number().optional().default(10).describe("Number of results"),
-    memory_types: z.array(z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"])).optional()
+    project: z2.string().optional().describe("Project name or slug"),
+    query: z2.string().describe("What to search for"),
+    scope: z2.enum(["personal", "shared_project"]).optional().default("personal"),
+    user_id: z2.string().optional().describe("Filter by user"),
+    session_id: z2.string().optional().describe("Filter by session"),
+    top_k: z2.number().optional().default(10).describe("Number of results"),
+    memory_types: z2.array(z2.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"])).optional()
   },
-  async ({ project, query, user_id, session_id, top_k, memory_types }) => {
+  async ({ project, query, scope, user_id, session_id, top_k, memory_types }) => {
     try {
-      const scope = resolveMcpScope({ project, user_id, session_id });
+      const memoryScope = resolveMemoryScope({ project, user_id, session_id, scope });
       const results = runtimeClient && (!memory_types || memory_types.length <= 1) ? await runtimeClient.memory.search({
-        project: scope.project,
+        project: memoryScope.project,
         query,
-        user_id: scope.userId,
-        session_id: scope.sessionId,
+        user_id: memoryScope.userId,
+        session_id: memoryScope.sessionId,
         top_k,
         include_pending: true,
         profile: "balanced",
         ...memory_types?.length === 1 ? { memory_type: memory_types[0] } : {}
       }) : await whisper.searchMemoriesSOTA({
-        project: scope.project,
+        project: memoryScope.project,
         query,
-        user_id: scope.userId,
-        session_id: scope.sessionId,
+        user_id: memoryScope.userId,
+        session_id: memoryScope.sessionId,
         top_k,
         memory_types
       });
@@ -6748,15 +7305,17 @@ server.tool(
       return primaryToolSuccess({
         tool: "memory.search",
         query,
-        user_id: scope.userId,
-        session_id: scope.sessionId,
+        scope: memoryScope.scopeMode,
+        user_id: memoryScope.userId,
+        session_id: memoryScope.sessionId,
         results: normalizedResults,
         count: normalizedResults.length,
         diagnostics: {
           scope: {
-            project: scope.project || null,
-            user_id: scope.userId,
-            session_id: scope.sessionId || null
+            project: memoryScope.project || null,
+            user_id: memoryScope.userId,
+            session_id: memoryScope.sessionId || null,
+            scope: memoryScope.scopeMode
           }
         }
       });
@@ -6794,7 +7353,7 @@ server.tool(
 server.tool(
   "context.list_sources",
   "List all data sources connected to a project.",
-  { project: z.string().optional().describe("Project name or slug") },
+  { project: z2.string().optional().describe("Project name or slug") },
   async ({ project }) => {
     try {
       const sourceData = await whisper.listSources(project || DEFAULT_PROJECT);
@@ -6810,38 +7369,38 @@ server.tool(
   "context.add_source",
   "Compatibility learning tool. Add a source to a project with normalized source contract and auto-index by default. Prefer `learn` for new integrations.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    type: z.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).default("github"),
-    name: z.string().optional(),
-    auto_index: z.boolean().optional().default(true),
-    metadata: z.record(z.string()).optional(),
-    ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
-    strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
-    profile_config: z.record(z.any()).optional(),
-    owner: z.string().optional(),
-    repo: z.string().optional(),
-    branch: z.string().optional(),
-    paths: z.array(z.string()).optional(),
-    url: z.string().url().optional(),
-    crawl_depth: z.number().optional(),
-    include_paths: z.array(z.string()).optional(),
-    exclude_paths: z.array(z.string()).optional(),
-    file_path: z.string().optional(),
-    path: z.string().optional(),
-    glob: z.string().optional(),
-    max_files: z.number().optional(),
-    max_pages: z.number().optional(),
-    extract_mode: z.enum(["text", "structured", "markdown"]).optional(),
-    workspace_id: z.string().optional(),
-    channel_ids: z.array(z.string()).optional(),
-    since: z.string().optional(),
-    token: z.string().optional(),
-    auth_ref: z.string().optional(),
-    platform: z.enum(["youtube", "loom", "generic"]).optional(),
-    language: z.string().optional(),
-    allow_stt_fallback: z.boolean().optional(),
-    max_duration_minutes: z.number().optional(),
-    max_chunks: z.number().optional()
+    project: z2.string().optional().describe("Project name or slug"),
+    type: z2.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).default("github"),
+    name: z2.string().optional(),
+    auto_index: z2.boolean().optional().default(true),
+    metadata: z2.record(z2.string()).optional(),
+    ingestion_profile: z2.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+    strategy_override: z2.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+    profile_config: z2.record(z2.any()).optional(),
+    owner: z2.string().optional(),
+    repo: z2.string().optional(),
+    branch: z2.string().optional(),
+    paths: z2.array(z2.string()).optional(),
+    url: z2.string().url().optional(),
+    crawl_depth: z2.number().optional(),
+    include_paths: z2.array(z2.string()).optional(),
+    exclude_paths: z2.array(z2.string()).optional(),
+    file_path: z2.string().optional(),
+    path: z2.string().optional(),
+    glob: z2.string().optional(),
+    max_files: z2.number().optional(),
+    max_pages: z2.number().optional(),
+    extract_mode: z2.enum(["text", "structured", "markdown"]).optional(),
+    workspace_id: z2.string().optional(),
+    channel_ids: z2.array(z2.string()).optional(),
+    since: z2.string().optional(),
+    token: z2.string().optional(),
+    auth_ref: z2.string().optional(),
+    platform: z2.enum(["youtube", "loom", "generic"]).optional(),
+    language: z2.string().optional(),
+    allow_stt_fallback: z2.boolean().optional(),
+    max_duration_minutes: z2.number().optional(),
+    max_chunks: z2.number().optional()
   },
   async (input) => {
     try {
@@ -6897,7 +7456,7 @@ server.tool(
   "context.source_status",
   "Get status and stage/progress details for a source sync job.",
   {
-    source_id: z.string().describe("Source id")
+    source_id: z2.string().describe("Source id")
   },
   async ({ source_id }) => {
     try {
@@ -6912,12 +7471,12 @@ server.tool(
   "context.add_text",
   "Compatibility learning tool. Add text content to a project's knowledge base. Prefer `learn` for new integrations.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    title: z.string().describe("Title for this content"),
-    content: z.string().describe("The text content to index"),
-    ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
-    strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
-    profile_config: z.record(z.any()).optional()
+    project: z2.string().optional().describe("Project name or slug"),
+    title: z2.string().describe("Title for this content"),
+    content: z2.string().describe("The text content to index"),
+    ingestion_profile: z2.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+    strategy_override: z2.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+    profile_config: z2.record(z2.any()).optional()
   },
   async ({ project, title, content, ingestion_profile, strategy_override, profile_config }) => {
     try {
@@ -6945,18 +7504,18 @@ server.tool(
   "context.add_document",
   "Compatibility learning tool. Ingest a document into project knowledge. Supports plain text and video URLs. Prefer `learn` for new integrations.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    source_type: z.enum(["text", "video"]).default("text"),
-    title: z.string().optional().describe("Title for text documents"),
-    content: z.string().optional().describe("Text document content"),
-    url: z.string().url().optional().describe("Video URL when source_type=video"),
-    auto_sync: z.boolean().optional().default(true),
-    tags: z.array(z.string()).optional(),
-    platform: z.enum(["youtube", "loom", "generic"]).optional(),
-    language: z.string().optional(),
-    ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
-    strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
-    profile_config: z.record(z.any()).optional()
+    project: z2.string().optional().describe("Project name or slug"),
+    source_type: z2.enum(["text", "video"]).default("text"),
+    title: z2.string().optional().describe("Title for text documents"),
+    content: z2.string().optional().describe("Text document content"),
+    url: z2.string().url().optional().describe("Video URL when source_type=video"),
+    auto_sync: z2.boolean().optional().default(true),
+    tags: z2.array(z2.string()).optional(),
+    platform: z2.enum(["youtube", "loom", "generic"]).optional(),
+    language: z2.string().optional(),
+    ingestion_profile: z2.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+    strategy_override: z2.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+    profile_config: z2.record(z2.any()).optional()
   },
   async ({ project, source_type, title, content, url, auto_sync, tags, platform, language, ingestion_profile, strategy_override, profile_config }) => {
     try {
@@ -7011,23 +7570,24 @@ server.tool(
   "memory.search_sota",
   "SOTA memory search with temporal reasoning and relation graphs. Searches memories with support for temporal queries ('what did I say yesterday?'), type filtering, and knowledge graph traversal.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    query: z.string().describe("Search query (supports temporal: 'yesterday', 'last week')"),
-    user_id: z.string().optional().describe("Filter by user"),
-    session_id: z.string().optional().describe("Filter by session"),
-    question_date: z.string().optional().describe("ISO datetime for temporal grounding"),
-    memory_types: z.array(z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"])).optional(),
-    top_k: z.number().optional().default(10),
-    include_relations: z.boolean().optional().default(true).describe("Include related memories via knowledge graph")
+    project: z2.string().optional().describe("Project name or slug"),
+    query: z2.string().describe("Search query (supports temporal: 'yesterday', 'last week')"),
+    scope: z2.enum(["personal", "shared_project"]).optional().default("personal"),
+    user_id: z2.string().optional().describe("Filter by user"),
+    session_id: z2.string().optional().describe("Filter by session"),
+    question_date: z2.string().optional().describe("ISO datetime for temporal grounding"),
+    memory_types: z2.array(z2.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"])).optional(),
+    top_k: z2.number().optional().default(10),
+    include_relations: z2.boolean().optional().default(true).describe("Include related memories via knowledge graph")
   },
-  async ({ project, query, user_id, session_id, question_date, memory_types, top_k, include_relations }) => {
+  async ({ project, query, scope, user_id, session_id, question_date, memory_types, top_k, include_relations }) => {
     try {
-      const scope = resolveMcpScope({ project, user_id, session_id });
+      const memoryScope = resolveMemoryScope({ project, user_id, session_id, scope });
       const results = await whisper.searchMemoriesSOTA({
-        project: scope.project,
+        project: memoryScope.project,
         query,
-        user_id: scope.userId,
-        session_id: scope.sessionId,
+        user_id: memoryScope.userId,
+        session_id: memoryScope.sessionId,
         question_date,
         memory_types,
         top_k,
@@ -7037,17 +7597,19 @@ server.tool(
       return primaryToolSuccess({
         tool: "memory.search_sota",
         query,
-        user_id: scope.userId,
-        session_id: scope.sessionId || null,
+        scope: memoryScope.scopeMode,
+        user_id: memoryScope.userId,
+        session_id: memoryScope.sessionId || null,
         question_date: question_date || null,
         include_relations,
         results: normalizedResults,
         count: normalizedResults.length,
         diagnostics: {
           scope: {
-            project: scope.project || null,
-            user_id: scope.userId,
-            session_id: scope.sessionId || null
+            project: memoryScope.project || null,
+            user_id: memoryScope.userId,
+            session_id: memoryScope.sessionId || null,
+            scope: memoryScope.scopeMode
           }
         }
       });
@@ -7060,40 +7622,51 @@ server.tool(
   "memory.ingest_conversation",
   "Compatibility learning tool. Extract memories from a conversation session. Prefer `learn` for new integrations.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    session_id: z.string().describe("Session identifier"),
-    user_id: z.string().optional().describe("User identifier"),
-    messages: z.array(z.object({
-      role: z.string(),
-      content: z.string(),
-      timestamp: z.string()
+    project: z2.string().optional().describe("Project name or slug"),
+    session_id: z2.string().describe("Session identifier"),
+    user_id: z2.string().optional().describe("User identifier"),
+    messages: z2.array(z2.object({
+      role: z2.string(),
+      content: z2.string(),
+      timestamp: z2.string()
     })).describe("Array of conversation messages with timestamps")
   },
   async ({ project, session_id, user_id, messages }) => {
     try {
-      const scope = resolveMcpScope({ project, user_id, session_id });
+      const memoryScope = resolveMemoryScope({
+        project,
+        user_id,
+        session_id,
+        scope: "personal"
+      });
       const normalizedMessages = messages.map((message) => ({
         role: message.role,
         content: message.content,
         timestamp: message.timestamp
       }));
       const result = await ingestSessionWithSyncFallback({
-        project: scope.project,
-        session_id: scope.sessionId,
-        user_id: scope.userId,
+        project: memoryScope.project,
+        session_id: memoryScope.sessionId,
+        user_id: memoryScope.userId,
         messages: normalizedMessages
       });
-      return {
-        content: [{
-          type: "text",
-          text: `Processed ${normalizedMessages.length} messages:
-- Scope ${scope.project || "auto-project"} / ${scope.userId} / ${scope.sessionId}
-- Created ${result.memories_created} memories
-- Detected ${result.relations_created} relations
-- Updated ${result.memories_invalidated} outdated memories` + (result.errors && result.errors.length > 0 ? `
-- Errors: ${result.errors.join(", ")}` : "")
-        }]
-      };
+      return primaryToolSuccess({
+        tool: "memory.ingest_conversation",
+        messages_processed: normalizedMessages.length,
+        memories_created: result.memories_created,
+        relations_created: result.relations_created,
+        memories_invalidated: result.memories_invalidated,
+        errors: result.errors || [],
+        scope: memoryScope.scopeMode,
+        diagnostics: {
+          scope: {
+            project: memoryScope.project || null,
+            user_id: memoryScope.userId,
+            session_id: memoryScope.sessionId || null,
+            scope: memoryScope.scopeMode
+          }
+        }
+      });
     } catch (error) {
       return { content: [{ type: "text", text: `Error: ${error.message}` }] };
     }
@@ -7103,11 +7676,11 @@ server.tool(
   "research.oracle",
   "Oracle Research Mode - Tree-guided document navigation with multi-step reasoning. More precise than standard search, especially for bleeding-edge features.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    query: z.string().describe("Research question"),
-    mode: z.enum(["search", "research"]).optional().default("search").describe("'search' for tree-guided, 'research' for multi-step reasoning"),
-    max_results: z.number().optional().default(5),
-    max_steps: z.number().optional().default(5).describe("For research mode: max reasoning steps")
+    project: z2.string().optional().describe("Project name or slug"),
+    query: z2.string().describe("Research question"),
+    mode: z2.enum(["search", "research"]).optional().default("search").describe("'search' for tree-guided, 'research' for multi-step reasoning"),
+    max_results: z2.number().optional().default(5),
+    max_steps: z2.number().optional().default(5).describe("For research mode: max reasoning steps")
   },
   async ({ project, query, mode, max_results, max_steps }) => {
     try {
@@ -7151,13 +7724,13 @@ server.tool(
   "index.autosubscribe_deps",
   "Automatically index a project's dependencies (package.json, requirements.txt, etc.). Resolves docs URLs and indexes documentation.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    source_type: z.enum(["github", "local"]).describe("Source location"),
-    github_owner: z.string().optional().describe("For GitHub: owner/org name"),
-    github_repo: z.string().optional().describe("For GitHub: repository name"),
-    local_path: z.string().optional().describe("For local: path to dependency file"),
-    dependency_file: z.enum(["package.json", "requirements.txt", "Cargo.toml", "go.mod", "Gemfile"]).optional(),
-    index_limit: z.number().optional().default(20).describe("Max dependencies to index")
+    project: z2.string().optional().describe("Project name or slug"),
+    source_type: z2.enum(["github", "local"]).describe("Source location"),
+    github_owner: z2.string().optional().describe("For GitHub: owner/org name"),
+    github_repo: z2.string().optional().describe("For GitHub: repository name"),
+    local_path: z2.string().optional().describe("For local: path to dependency file"),
+    dependency_file: z2.enum(["package.json", "requirements.txt", "Cargo.toml", "go.mod", "Gemfile"]).optional(),
+    index_limit: z2.number().optional().default(20).describe("Max dependencies to index")
   },
   async ({ project, source_type, github_owner, github_repo, local_path, dependency_file, index_limit }) => {
     try {
@@ -7184,10 +7757,10 @@ server.tool(
   "context.share",
   "Create a shareable snapshot of a conversation with memories. Returns a URL that can be shared or resumed later.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    session_id: z.string().describe("Session to share"),
-    title: z.string().optional().describe("Title for the shared context"),
-    expiry_days: z.number().optional().default(30).describe("Days until expiry")
+    project: z2.string().optional().describe("Project name or slug"),
+    session_id: z2.string().describe("Session to share"),
+    title: z2.string().optional().describe("Title for the shared context"),
+    expiry_days: z2.number().optional().default(30).describe("Days until expiry")
   },
   async ({ project, session_id, title, expiry_days }) => {
     try {
@@ -7222,9 +7795,9 @@ server.tool(
   "memory.consolidate",
   "Find and merge duplicate memories to reduce bloat. Uses vector similarity + LLM merging.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    similarity_threshold: z.number().optional().default(0.95).describe("Similarity threshold (0-1)"),
-    dry_run: z.boolean().optional().default(false).describe("Preview without merging")
+    project: z2.string().optional().describe("Project name or slug"),
+    similarity_threshold: z2.number().optional().default(0.95).describe("Similarity threshold (0-1)"),
+    dry_run: z2.boolean().optional().default(false).describe("Preview without merging")
   },
   async ({ project, similarity_threshold, dry_run }) => {
     try {
@@ -7265,8 +7838,8 @@ server.tool(
   "context.cost_summary",
   "Get cost tracking summary showing spending by model and task. Includes savings vs always-Opus.",
   {
-    project: z.string().optional().describe("Project name or slug (optional for org-wide)"),
-    days: z.number().optional().default(30).describe("Time period in days")
+    project: z2.string().optional().describe("Project name or slug (optional for org-wide)"),
+    days: z2.number().optional().default(30).describe("Time period in days")
   },
   async ({ project, days }) => {
     try {
@@ -7308,16 +7881,19 @@ server.tool(
   "memory.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()
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional(),
+    scope: z2.enum(["personal", "shared_project"]).optional().default("personal"),
+    user_id: z2.string().optional(),
+    session_id: z2.string().optional(),
+    target: z2.object({
+      memory_id: z2.string().optional(),
+      query: z2.string().optional()
     }),
-    mode: z.enum(["delete", "invalidate"]).optional().default("invalidate"),
-    reason: z.string().optional()
+    mode: z2.enum(["delete", "invalidate"]).optional().default("invalidate"),
+    reason: z2.string().optional()
   },
-  async ({ workspace_id, project, target, mode, reason }) => {
+  async ({ workspace_id, project, scope, user_id, session_id, target, mode, reason }) => {
     try {
       if (!target.memory_id && !target.query) {
         return { content: [{ type: "text", text: "Error: target.memory_id or target.query is required." }] };
@@ -7326,8 +7902,22 @@ server.tool(
       let queryResolution = null;
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const actor = process.env.WHISPER_AGENT_ID || process.env.USERNAME || "api_key_principal";
-      const resolvedProject = await resolveProjectRef(project);
+      const memoryScope = resolveMemoryScope({
+        project,
+        user_id,
+        session_id,
+        scope
+      });
+      const resolvedProject = await resolveProjectRef(memoryScope.project);
+      async function assertScopedMemoryId(memoryId) {
+        const memoryResult = await whisper.getMemory(memoryId);
+        const memory = memoryResult?.memory || memoryResult;
+        if (!isMemoryInScope({ memory, memoryScope })) {
+          throw new Error(`memory_id ${memoryId} is outside the effective ${memoryScope.scopeMode} scope.`);
+        }
+      }
       async function applyToMemory(memoryId) {
+        await assertScopedMemoryId(memoryId);
         if (mode === "delete") {
           await whisper.deleteMemory(memoryId);
         } else {
@@ -7342,7 +7932,10 @@ server.tool(
                 project: resolvedProject,
                 content: `Invalidated memory ${memoryId} at ${now}. Reason: ${reason || "No reason provided"}`,
                 memory_type: "instruction",
-                importance: 1
+                user_id: memoryScope.userId,
+                session_id: memoryScope.sessionId,
+                importance: 1,
+                metadata: buildMemoryScopeMetadata({ memoryScope })
               });
             }
           }
@@ -7374,13 +7967,25 @@ server.tool(
               mode: audit2.mode,
               ...audit2.reason ? { reason: audit2.reason } : {}
             },
-            warning: "No project resolved for query-based forget. Nothing was changed."
+            warning: "No project resolved for query-based forget. Nothing was changed.",
+            diagnostics: {
+              scope: {
+                project: memoryScope.project || null,
+                user_id: memoryScope.userId,
+                session_id: memoryScope.sessionId || null,
+                scope: memoryScope.scopeMode,
+                actor_user_id: memoryScope.actorUserId,
+                actor_session_id: memoryScope.actorSessionId || null
+              }
+            }
           };
           return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
         }
         const search = await whisper.searchMemoriesSOTA({
           project: resolvedProject,
           query: target.query || "",
+          user_id: memoryScope.userId,
+          session_id: memoryScope.sessionId,
           top_k: 25,
           include_relations: false,
           include_pending: true
@@ -7393,7 +7998,17 @@ server.tool(
             status: "completed",
             affected_ids: affectedIds,
             warning: resolved.warning || "Query did not resolve to a reliable memory match. No memories were changed.",
-            resolved_by: resolved.resolved_by
+            resolved_by: resolved.resolved_by,
+            diagnostics: {
+              scope: {
+                project: resolvedProject,
+                user_id: memoryScope.userId,
+                session_id: memoryScope.sessionId || null,
+                scope: memoryScope.scopeMode,
+                actor_user_id: memoryScope.actorUserId,
+                actor_session_id: memoryScope.actorSessionId || null
+              }
+            }
           };
           return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
         }
@@ -7422,6 +8037,16 @@ server.tool(
           called_at: audit.called_at,
           mode: audit.mode,
           ...audit.reason ? { reason: audit.reason } : {}
+        },
+        diagnostics: {
+          scope: {
+            project: resolvedProject || null,
+            user_id: memoryScope.userId,
+            session_id: memoryScope.sessionId || null,
+            scope: memoryScope.scopeMode,
+            actor_user_id: memoryScope.actorUserId,
+            actor_session_id: memoryScope.actorSessionId || null
+          }
         }
       };
       return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
@@ -7434,8 +8059,8 @@ server.tool(
   "context.export_bundle",
   "Export project/workspace memory and context to a portable bundle with checksum.",
   {
-    workspace_id: z.string().optional(),
-    project: z.string().optional()
+    workspace_id: z2.string().optional(),
+    project: z2.string().optional()
   },
   async ({ workspace_id, project }) => {
     try {
@@ -7485,26 +8110,26 @@ server.tool(
   "context.import_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(),
-      project: z.string().optional(),
-      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({})
+    workspace_id: z2.string().optional(),
+    bundle: z2.object({
+      bundle_version: z2.string(),
+      workspace_id: z2.string(),
+      project: z2.string().optional(),
+      exported_at: z2.string(),
+      contents: z2.object({
+        memories: z2.array(z2.any()).default([]),
+        entities: z2.array(z2.any()).default([]),
+        decisions: z2.array(z2.any()).default([]),
+        failures: z2.array(z2.any()).default([]),
+        annotations: z2.array(z2.any()).default([]),
+        session_summaries: z2.array(z2.any()).default([]),
+        documents: z2.array(z2.any()).default([]),
+        index_metadata: z2.record(z2.any()).default({})
       }),
-      checksum: z.string()
+      checksum: z2.string()
     }),
-    mode: z.enum(["merge", "replace"]).optional().default("merge"),
-    dedupe_strategy: z.enum(["semantic", "id", "none"]).optional().default("semantic")
+    mode: z2.enum(["merge", "replace"]).optional().default("merge"),
+    dedupe_strategy: z2.enum(["semantic", "id", "none"]).optional().default("semantic")
   },
   async ({ workspace_id, bundle, mode, dedupe_strategy }) => {
     try {
@@ -7648,13 +8273,13 @@ server.tool(
   "context.diff",
   "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()
+    workspace_id: z2.string().optional(),
+    anchor: z2.object({
+      type: z2.enum(["session_id", "timestamp", "commit"]),
+      value: z2.string()
     }).optional(),
-    scope: z.object({
-      include: z.array(z.enum(["decisions", "failures", "entities", "documents", "summaries"])).optional().default(["decisions", "failures", "entities", "documents", "summaries"])
+    scope: z2.object({
+      include: z2.array(z2.enum(["decisions", "failures", "entities", "documents", "summaries"])).optional().default(["decisions", "failures", "entities", "documents", "summaries"])
     }).optional()
   },
   async ({ workspace_id, anchor, scope }) => {
@@ -7765,12 +8390,12 @@ server.tool(
   "code.search_semantic",
   "Semantically search a local codebase without pre-indexing. Unlike grep/ripgrep, this understands meaning \u2014 so 'find authentication logic' finds auth code even if it doesn't literally say 'auth'. Uses vector embeddings via the Whisper API. Perfect for exploring unfamiliar codebases.",
   {
-    query: z.string().describe("Natural language description of what you're looking for. E.g. 'authentication and session management', 'database connection pooling', 'error handling middleware'"),
-    path: z.string().optional().describe("Absolute path to the codebase root. Defaults to current working directory."),
-    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(150).describe("Max files to scan. For large codebases, narrow with file_types instead of raising this.")
+    query: z2.string().describe("Natural language description of what you're looking for. E.g. 'authentication and session management', 'database connection pooling', 'error handling middleware'"),
+    path: z2.string().optional().describe("Absolute path to the codebase root. Defaults to current working directory."),
+    file_types: z2.array(z2.string()).optional().describe("Limit to specific extensions e.g. ['ts', 'py']. Defaults to all common code files."),
+    top_k: z2.number().optional().default(10).describe("Number of most relevant files to return"),
+    threshold: z2.number().optional().default(0.2).describe("Minimum similarity score 0-1. Lower = more results but less precise."),
+    max_files: z2.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 }) => {
     try {
@@ -7845,13 +8470,13 @@ server.tool(
   "code.search_text",
   "Search files and content in a local directory without requiring pre-indexing. Uses ripgrep when available, falls back to Node.js. Great for finding files, functions, patterns, or any text across a codebase instantly.",
   {
-    query: z.string().describe("What to search for \u2014 natural language keyword, function name, pattern, etc."),
-    path: z.string().optional().describe("Absolute path to search in. Defaults to current working directory."),
-    mode: z.enum(["content", "filename", "both"]).optional().default("both").describe("Search file contents, filenames, or both"),
-    file_types: z.array(z.string()).optional().describe("Limit to these file extensions e.g. ['ts', 'js', 'py', 'go']"),
-    max_results: z.number().optional().default(20).describe("Max number of matching files to return"),
-    context_lines: z.number().optional().default(2).describe("Lines of context around each match"),
-    case_sensitive: z.boolean().optional().default(false)
+    query: z2.string().describe("What to search for \u2014 natural language keyword, function name, pattern, etc."),
+    path: z2.string().optional().describe("Absolute path to search in. Defaults to current working directory."),
+    mode: z2.enum(["content", "filename", "both"]).optional().default("both").describe("Search file contents, filenames, or both"),
+    file_types: z2.array(z2.string()).optional().describe("Limit to these file extensions e.g. ['ts', 'js', 'py', 'go']"),
+    max_results: z2.number().optional().default(20).describe("Max number of matching files to return"),
+    context_lines: z2.number().optional().default(2).describe("Lines of context around each match"),
+    case_sensitive: z2.boolean().optional().default(false)
   },
   async ({ query, path: searchPath, mode, file_types, max_results, context_lines, case_sensitive }) => {
     const rootPath = searchPath || process.cwd();
@@ -7984,13 +8609,13 @@ server.tool(
   "code.semantic_documents",
   "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")
+    query: z2.string().describe("What to search for semantically (e.g. 'authentication logic', 'database connection')"),
+    documents: z2.array(z2.object({
+      id: z2.string().describe("Unique identifier (file path, URL, or any ID)"),
+      content: z2.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")
+    top_k: z2.number().optional().default(5).describe("Number of results to return"),
+    threshold: z2.number().optional().default(0.3).describe("Minimum similarity score 0-1")
   },
   async ({ query, documents, top_k, threshold }) => {
     try {
@@ -8028,14 +8653,14 @@ server.tool(
   "search",
   "Primary retrieval alias. Call this whenever the user asks to find or recall context: use `query` for semantic retrieval, `id` for exact memory fetch, or both for hybrid recall.",
   {
-    project: z.string().optional().describe("Project name or slug"),
-    query: z.string().optional().describe("Semantic retrieval query"),
-    id: z.string().optional().describe("Exact memory id to fetch"),
-    top_k: z.number().optional().default(10),
-    include_memories: z.boolean().optional().default(false),
-    include_graph: z.boolean().optional().default(false),
-    user_id: z.string().optional(),
-    session_id: z.string().optional()
+    project: z2.string().optional().describe("Project name or slug"),
+    query: z2.string().optional().describe("Semantic retrieval query"),
+    id: z2.string().optional().describe("Exact memory id to fetch"),
+    top_k: z2.number().optional().default(10),
+    include_memories: z2.boolean().optional().default(false),
+    include_graph: z2.boolean().optional().default(false),
+    user_id: z2.string().optional(),
+    session_id: z2.string().optional()
   },
   async ({ project, query, id, top_k, include_memories, include_graph, user_id, session_id }) => {
     try {
@@ -8099,12 +8724,12 @@ server.tool(
   "search_code",
   "Semantically search a local codebase by meaning. Use this for questions like 'where is auth handled?' or 'find retry logic'.",
   {
-    query: z.string().describe("Natural-language code search query"),
-    path: z.string().optional().describe("Codebase root. Defaults to current working directory."),
-    file_types: z.array(z.string()).optional(),
-    top_k: z.number().optional().default(10),
-    threshold: z.number().optional().default(0.2),
-    max_files: z.number().optional().default(150)
+    query: z2.string().describe("Natural-language code search query"),
+    path: z2.string().optional().describe("Codebase root. Defaults to current working directory."),
+    file_types: z2.array(z2.string()).optional(),
+    top_k: z2.number().optional().default(10),
+    threshold: z2.number().optional().default(0.2),
+    max_files: z2.number().optional().default(150)
   },
   async ({ query, path, file_types, top_k, threshold, max_files }) => {
     try {
@@ -8125,11 +8750,11 @@ server.tool(
   "grep",
   "Regex or text search across a local codebase. Use this when you know the symbol, string, or pattern you want.",
   {
-    query: z.string().describe("Text or regex-like pattern to search for"),
-    path: z.string().optional().describe("Search root. Defaults to current working directory."),
-    file_types: z.array(z.string()).optional(),
-    max_results: z.number().optional().default(20),
-    case_sensitive: z.boolean().optional().default(false)
+    query: z2.string().describe("Text or regex-like pattern to search for"),
+    path: z2.string().optional().describe("Search root. Defaults to current working directory."),
+    file_types: z2.array(z2.string()).optional(),
+    max_results: z2.number().optional().default(20),
+    case_sensitive: z2.boolean().optional().default(false)
   },
   async ({ query, path, file_types, max_results, case_sensitive }) => {
     const rootPath = path || process.cwd();
@@ -8177,9 +8802,9 @@ server.tool(
   "read",
   "Read a local file with optional line ranges. Use this after search or grep when you want the actual source.",
   {
-    path: z.string().describe("Absolute or relative path to the file to read."),
-    start_line: z.number().optional().default(1),
-    end_line: z.number().optional().default(200)
+    path: z2.string().describe("Absolute or relative path to the file to read."),
+    start_line: z2.number().optional().default(1),
+    end_line: z2.number().optional().default(200)
   },
   async ({ path, start_line, end_line }) => {
     try {
@@ -8204,9 +8829,9 @@ server.tool(
   "explore",
   "Browse a repository tree or directory structure. Use this to orient yourself before reading files.",
   {
-    path: z.string().optional().describe("Root directory to inspect. Defaults to current working directory."),
-    max_depth: z.number().optional().default(3),
-    max_entries: z.number().optional().default(200)
+    path: z2.string().optional().describe("Root directory to inspect. Defaults to current working directory."),
+    max_depth: z2.number().optional().default(3),
+    max_entries: z2.number().optional().default(200)
   },
   async ({ path, max_depth, max_entries }) => {
     try {
@@ -8235,11 +8860,11 @@ server.tool(
   "research",
   "Run deeper research over indexed sources. Use this when search is not enough and you want synthesis or multi-step investigation.",
   {
-    project: z.string().optional(),
-    query: z.string().describe("Research question"),
-    mode: z.enum(["search", "research"]).optional().default("research"),
-    max_results: z.number().optional().default(5),
-    max_steps: z.number().optional().default(5)
+    project: z2.string().optional(),
+    query: z2.string().describe("Research question"),
+    mode: z2.enum(["search", "research"]).optional().default("research"),
+    max_results: z2.number().optional().default(5),
+    max_steps: z2.number().optional().default(5)
   },
   async ({ project, query, mode, max_results, max_steps }) => {
     try {
@@ -8261,27 +8886,27 @@ server.tool(
   "index",
   "Administrative indexing tool. Call this when retrieval is stale/missing or the user asks to connect new data. Use action='source' to add GitHub/web/pdf/local/slack/video, action='workspace' to refresh local workspace metadata.",
   {
-    action: z.enum(["source", "workspace"]).default("source"),
-    project: z.string().optional(),
-    type: z.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).optional(),
-    name: z.string().optional(),
-    owner: z.string().optional(),
-    repo: z.string().optional(),
-    branch: z.string().optional(),
-    url: z.string().optional(),
-    file_path: z.string().optional(),
-    path: z.string().optional(),
-    glob: z.string().optional(),
-    max_files: z.number().optional(),
-    channel_ids: z.array(z.string()).optional(),
-    token: z.string().optional(),
-    workspace_id: z.string().optional(),
-    mode: z.enum(["full", "incremental"]).optional().default("incremental"),
-    platform: z.enum(["youtube", "loom", "generic"]).optional(),
-    language: z.string().optional(),
-    allow_stt_fallback: z.boolean().optional(),
-    max_duration_minutes: z.number().optional(),
-    max_chunks: z.number().optional()
+    action: z2.enum(["source", "workspace"]).default("source"),
+    project: z2.string().optional(),
+    type: z2.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).optional(),
+    name: z2.string().optional(),
+    owner: z2.string().optional(),
+    repo: z2.string().optional(),
+    branch: z2.string().optional(),
+    url: z2.string().optional(),
+    file_path: z2.string().optional(),
+    path: z2.string().optional(),
+    glob: z2.string().optional(),
+    max_files: z2.number().optional(),
+    channel_ids: z2.array(z2.string()).optional(),
+    token: z2.string().optional(),
+    workspace_id: z2.string().optional(),
+    mode: z2.enum(["full", "incremental"]).optional().default("incremental"),
+    platform: z2.enum(["youtube", "loom", "generic"]).optional(),
+    language: z2.string().optional(),
+    allow_stt_fallback: z2.boolean().optional(),
+    max_duration_minutes: z2.number().optional(),
+    max_chunks: z2.number().optional()
   },
   async (input) => {
     try {
@@ -8342,25 +8967,30 @@ server.tool(
   "remember",
   "Call this whenever the user states a durable preference, decision, instruction, or personal/project fact that should persist across sessions. Save proactively without waiting for an explicit 'remember this'.",
   {
-    project: z.string().optional(),
-    content: z.string().describe("Memory content"),
-    memory_type: z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"]).optional().default("factual"),
-    user_id: z.string().optional(),
-    session_id: z.string().optional(),
-    agent_id: z.string().optional(),
-    importance: z.number().optional().default(0.5)
+    project: z2.string().optional(),
+    content: z2.string().describe("Memory content"),
+    memory_type: z2.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"]).optional().default("factual"),
+    scope: z2.enum(["personal", "shared_project"]).optional().default("personal"),
+    user_id: z2.string().optional(),
+    session_id: z2.string().optional(),
+    agent_id: z2.string().optional(),
+    importance: z2.number().optional().default(0.5)
   },
-  async ({ project, content, memory_type, user_id, session_id, agent_id, importance }) => {
+  async ({ project, content, memory_type, scope, user_id, session_id, agent_id, importance }) => {
     try {
-      const scope = resolveMcpScope({ project, user_id, session_id });
+      const memoryScope = resolveMemoryScope({ project, user_id, session_id, scope });
       const result = await whisper.addMemory({
-        project: scope.project,
+        project: memoryScope.project,
         content,
         memory_type,
-        user_id: scope.userId,
-        session_id: scope.sessionId,
+        user_id: memoryScope.userId,
+        session_id: memoryScope.sessionId,
         agent_id,
-        importance
+        importance,
+        metadata: buildMemoryScopeMetadata({
+          memoryScope,
+          agent_id
+        })
       });
       const memoryId = result?.memory_id || (result.mode === "sync" ? result.id : null);
       const jobId = result?.job_id || (result.mode === "async" ? result.id : null);
@@ -8371,13 +9001,17 @@ server.tool(
         job_id: jobId,
         mode: result?.mode || null,
         memory_type,
+        scope: memoryScope.scopeMode,
         stored: result.success === true,
         queued: result?.mode === "async" || Boolean(jobId),
         diagnostics: {
           scope: {
-            project: scope.project || null,
-            user_id: scope.userId,
-            session_id: scope.sessionId || null
+            project: memoryScope.project || null,
+            user_id: memoryScope.userId,
+            session_id: memoryScope.sessionId || null,
+            scope: memoryScope.scopeMode,
+            actor_user_id: memoryScope.actorUserId,
+            actor_session_id: memoryScope.actorSessionId || null
           }
         }
       });
@@ -8390,17 +9024,17 @@ server.tool(
   "record",
   "Record what just happened in a session or conversation. Use this for temporal capture, not durable preference storage.",
   {
-    project: z.string().optional(),
-    session_id: z.string().describe("Session to record into"),
-    user_id: z.string().optional(),
-    messages: z.array(z.object({
-      role: z.string().optional(),
-      content: z.string(),
-      timestamp: z.string().optional()
+    project: z2.string().optional(),
+    session_id: z2.string().describe("Session to record into"),
+    user_id: z2.string().optional(),
+    messages: z2.array(z2.object({
+      role: z2.string().optional(),
+      content: z2.string(),
+      timestamp: z2.string().optional()
     })).optional(),
-    role: z.string().optional(),
-    content: z.string().optional(),
-    timestamp: z.string().optional()
+    role: z2.string().optional(),
+    content: z2.string().optional(),
+    timestamp: z2.string().optional()
   },
   async ({ project, session_id, user_id, messages, role, content, timestamp }) => {
     try {
@@ -8415,29 +9049,31 @@ server.tool(
         timestamp
       });
       const resolvedProject = await resolveProjectRef(project);
-      const scope = resolveMcpScope({
+      const memoryScope = resolveMemoryScope({
         project: resolvedProject || project,
         user_id,
-        session_id
+        session_id,
+        scope: "personal"
       });
       const result = await ingestSessionWithSyncFallback({
-        project: scope.project,
-        session_id: scope.sessionId || session_id,
-        user_id: scope.userId,
+        project: memoryScope.project,
+        session_id: memoryScope.sessionId || session_id,
+        user_id: memoryScope.userId,
         messages: normalizedMessages
       });
       return primaryToolSuccess({
         tool: "record",
-        session_id: scope.sessionId || session_id,
-        user_id: scope.userId,
+        session_id: memoryScope.sessionId || session_id,
+        user_id: memoryScope.userId,
         messages_recorded: normalizedMessages.length,
         memories_created: result.memories_created,
         relations_created: result.relations_created,
         diagnostics: {
           scope: {
-            project: scope.project || null,
-            user_id: scope.userId,
-            session_id: scope.sessionId || session_id
+            project: memoryScope.project || null,
+            user_id: memoryScope.userId,
+            session_id: memoryScope.sessionId || session_id,
+            scope: memoryScope.scopeMode
           }
         }
       });
@@ -8450,60 +9086,62 @@ server.tool(
   "learn",
   "Unified ingestion entrypoint. Call this when the user asks to import knowledge: mode='conversation' for chat logs, mode='text' for raw text, mode='source' for external sources to index. Prefer this over legacy compatibility tools.",
   {
-    mode: z.enum(["conversation", "text", "source"]).describe("What kind of learning to perform"),
-    project: z.string().optional(),
-    user_id: z.string().optional().describe("Optional end-user identity for conversation learning"),
-    session_id: z.string().optional().describe("Session identifier for conversation learning"),
-    messages: z.array(z.object({
-      role: z.string(),
-      content: z.string(),
-      timestamp: z.string().optional()
+    mode: z2.enum(["conversation", "text", "source"]).describe("What kind of learning to perform"),
+    project: z2.string().optional(),
+    user_id: z2.string().optional().describe("Optional end-user identity for conversation learning"),
+    session_id: z2.string().optional().describe("Session identifier for conversation learning"),
+    messages: z2.array(z2.object({
+      role: z2.string(),
+      content: z2.string(),
+      timestamp: z2.string().optional()
     })).optional().describe("Conversation messages to learn from"),
-    title: z.string().optional().describe("Title for text learning"),
-    content: z.string().optional().describe("Inline text content to ingest"),
-    metadata: z.record(z.any()).optional(),
-    tags: z.array(z.string()).optional(),
-    namespace: z.string().optional(),
-    type: z.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).optional().describe("Source type when mode=source"),
-    url: z.string().optional().describe("URL to learn from"),
-    owner: z.string().optional().describe("GitHub owner"),
-    repo: z.string().optional().describe("GitHub repository"),
-    branch: z.string().optional(),
-    paths: z.array(z.string()).optional(),
-    path: z.string().optional().describe("Local path to learn from"),
-    file_path: z.string().optional().describe("Single file path to learn from"),
-    name: z.string().optional().describe("Optional source name"),
-    channel_ids: z.array(z.string()).optional(),
-    since: z.string().optional(),
-    token: z.string().optional(),
-    auth_ref: z.string().optional(),
-    platform: z.enum(["youtube", "loom", "generic"]).optional(),
-    language: z.string().optional(),
-    options: z.object({
-      async: z.boolean().optional(),
-      auto_index: z.boolean().optional(),
-      ingestion_profile: z.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
-      strategy_override: z.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
-      profile_config: z.record(z.any()).optional(),
-      crawl_depth: z.number().optional(),
-      include_paths: z.array(z.string()).optional(),
-      exclude_paths: z.array(z.string()).optional(),
-      glob: z.string().optional(),
-      max_files: z.number().optional(),
-      max_pages: z.number().optional(),
-      extract_mode: z.enum(["text", "structured", "markdown"]).optional(),
-      workspace_id: z.string().optional(),
-      allow_stt_fallback: z.boolean().optional(),
-      max_duration_minutes: z.number().optional(),
-      max_chunks: z.number().optional()
+    title: z2.string().optional().describe("Title for text learning"),
+    content: z2.string().optional().describe("Inline text content to ingest"),
+    metadata: z2.record(z2.any()).optional(),
+    tags: z2.array(z2.string()).optional(),
+    namespace: z2.string().optional(),
+    type: z2.enum(["github", "web", "playwright", "pdf", "local", "slack", "video"]).optional().describe("Source type when mode=source"),
+    url: z2.string().optional().describe("URL to learn from"),
+    owner: z2.string().optional().describe("GitHub owner"),
+    repo: z2.string().optional().describe("GitHub repository"),
+    branch: z2.string().optional(),
+    paths: z2.array(z2.string()).optional(),
+    path: z2.string().optional().describe("Local path to learn from"),
+    file_path: z2.string().optional().describe("Single file path to learn from"),
+    name: z2.string().optional().describe("Optional source name"),
+    channel_ids: z2.array(z2.string()).optional(),
+    since: z2.string().optional(),
+    token: z2.string().optional(),
+    auth_ref: z2.string().optional(),
+    platform: z2.enum(["youtube", "loom", "generic"]).optional(),
+    language: z2.string().optional(),
+    options: z2.object({
+      async: z2.boolean().optional(),
+      auto_index: z2.boolean().optional(),
+      ingestion_profile: z2.enum(["auto", "repo", "web_docs", "pdf_layout", "video_transcript", "plain_text"]).optional(),
+      strategy_override: z2.enum(["fixed", "recursive", "semantic", "hierarchical", "adaptive"]).optional(),
+      profile_config: z2.record(z2.any()).optional(),
+      crawl_depth: z2.number().optional(),
+      include_paths: z2.array(z2.string()).optional(),
+      exclude_paths: z2.array(z2.string()).optional(),
+      glob: z2.string().optional(),
+      max_files: z2.number().optional(),
+      max_pages: z2.number().optional(),
+      extract_mode: z2.enum(["text", "structured", "markdown"]).optional(),
+      workspace_id: z2.string().optional(),
+      allow_stt_fallback: z2.boolean().optional(),
+      max_duration_minutes: z2.number().optional(),
+      max_chunks: z2.number().optional()
     }).optional()
   },
   async (input) => {
     try {
       const result = await learnFromInput(input);
+      const indexingNote = result.mode === "source" && result.index_started ? "Indexing has started in the background and usually completes in 1\u20132 minutes. Queries may return limited results until then. Run `index.workspace_status` or `context.source_status` to check progress." : void 0;
       return primaryToolSuccess({
         tool: "learn",
-        ...result
+        ...result,
+        ...indexingNote ? { _note: indexingNote } : {}
       });
     } catch (error) {
       return primaryToolError(error.message);
@@ -8514,10 +9152,10 @@ server.tool(
   "share_context",
   "Create a shareable snapshot of a session so another agent or teammate can continue with the same context.",
   {
-    project: z.string().optional(),
-    session_id: z.string().describe("Session to share"),
-    title: z.string().optional(),
-    expiry_days: z.number().optional().default(30)
+    project: z2.string().optional(),
+    session_id: z2.string().describe("Session to share"),
+    title: z2.string().optional(),
+    expiry_days: z2.number().optional().default(30)
   },
   async ({ project, session_id, title, expiry_days }) => {
     try {