@usewhisper/mcp-server 2.14.0 → 2.15.0

package/dist/server.js

@@ -7,7 +7,7 @@ import { z } 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
@@ -4711,12 +4711,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 +4748,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 +5376,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");
@@ -6244,6 +6398,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 +6457,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 +6562,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 +6579,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;
 }
@@ -6671,22 +6871,27 @@ server.tool(
     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"),
+    scope: z.enum(["personal", "shared_project"]).optional().default("personal"),
     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")
   },
-  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 +6904,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
           }
         }
       });
@@ -6719,28 +6928,29 @@ server.tool(
   {
     project: z.string().optional().describe("Project name or slug"),
     query: z.string().describe("What to search for"),
+    scope: z.enum(["personal", "shared_project"]).optional().default("personal"),
     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()
   },
-  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 +6958,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
           }
         }
       });
@@ -7013,6 +7225,7 @@ server.tool(
   {
     project: z.string().optional().describe("Project name or slug"),
     query: z.string().describe("Search query (supports temporal: 'yesterday', 'last week')"),
+    scope: z.enum(["personal", "shared_project"]).optional().default("personal"),
     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"),
@@ -7020,14 +7233,14 @@ server.tool(
     top_k: z.number().optional().default(10),
     include_relations: z.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 +7250,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
           }
         }
       });
@@ -7071,29 +7286,40 @@ server.tool(
   },
   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}` }] };
     }
@@ -7310,6 +7536,9 @@ server.tool(
   {
     workspace_id: z.string().optional(),
     project: z.string().optional(),
+    scope: z.enum(["personal", "shared_project"]).optional().default("personal"),
+    user_id: z.string().optional(),
+    session_id: z.string().optional(),
     target: z.object({
       memory_id: z.string().optional(),
       query: z.string().optional()
@@ -7317,7 +7546,7 @@ server.tool(
     mode: z.enum(["delete", "invalidate"]).optional().default("invalidate"),
     reason: z.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 +7555,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 +7585,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 +7620,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 +7651,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 +7690,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) }] };
@@ -8345,22 +8623,27 @@ server.tool(
     project: z.string().optional(),
     content: z.string().describe("Memory content"),
     memory_type: z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"]).optional().default("factual"),
+    scope: z.enum(["personal", "shared_project"]).optional().default("personal"),
     user_id: z.string().optional(),
     session_id: z.string().optional(),
     agent_id: z.string().optional(),
     importance: z.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 +8654,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
           }
         }
       });
@@ -8415,29 +8702,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
           }
         }
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/mcp-server",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "whisperContractVersion": "2026.03.11",
   "scripts": {
     "build": "tsup ../src/mcp/server.ts --format esm --out-dir dist",