@usewhisper/mcp-server 1.4.0 → 2.0.0

package/README.md

@@ -14,13 +14,18 @@ Whisper MCP is the universal context bridge for coding agents. It connects Claud
 
 ## Install
 
-```bash
+```text
 npm i -g @usewhisper/mcp-server
 ```
 
+## Terminal vs MCP
+
+Use the terminal commands only to install the server, print migration info, or generate client config.
+Once the server is running, agents should call MCP tools like `search`, `remember`, `learn`, and `share_context`, not shell commands.
+
 ## Required Environment
 
-- `WHISPER_API_KEY` (required)
+- `WHISPER_API_KEY` (required, use your `wsk_*` API key)
 - `WHISPER_PROJECT` (optional default)
 - `WHISPER_BASE_URL` (optional, defaults to `https://context.usewhisper.dev`)
 - `WHISPER_MCP_MODE` (optional: `remote|local|auto`, default `remote`)
@@ -28,6 +33,22 @@ npm i -g @usewhisper/mcp-server
 - `SLACK_BOT_TOKEN` (required for Slack connector runs)
 - `SLACK_CHANNEL_ID` (required for Slack connector runs)
 
+Example values:
+
+```text
+WHISPER_API_KEY=wsk_your_api_key_here
+WHISPER_PROJECT=my-project
+WHISPER_BASE_URL=https://context.usewhisper.dev
+```
+
+Example shell setup:
+
+```text
+export WHISPER_API_KEY="wsk_your_api_key_here"
+export WHISPER_PROJECT="my-project"
+export WHISPER_BASE_URL="https://context.usewhisper.dev"
+```
+
 ## Connector Status + Credentials
 
 | Connector | Status | Minimum required config/creds |
@@ -65,21 +86,52 @@ npm i -g @usewhisper/mcp-server
 22. `code.search_text`
 23. `code.search_semantic`
 
-## Agent-Friendly Aliases
+## Agent-Friendly Primary Verbs
 
-These aliases sit on top of the canonical namespaced tools and are easier for coding agents to pick correctly:
+These verbs are the primary MCP interface for agents. Namespaced tools remain available as compatibility and advanced surfaces.
 
-- `search` -> `context.query`
+- `search` -> exact fetch by `id`, semantic retrieval by `query`, or hybrid retrieval when both are present
 - `search_code` -> `code.search_semantic`
 - `grep` -> `code.search_text`
 - `read` -> local file read with optional line ranges
 - `explore` -> local repository tree browsing
 - `research` -> `research.oracle`
-- `index` -> source add or workspace refresh
 - `remember` -> `memory.add`
-- `recall` -> `memory.search`
+- `record` -> `memory.ingest_conversation`
+- `learn` -> `context.add_text | context.add_source | context.add_document`
 - `share_context` -> `context.share`
 
+`index` remains available as an advanced/admin compatibility tool for indexing jobs and workspace refresh operations.
+
+### `search` behavior
+
+`search` is the only primary retrieval verb.
+
+- `search({ id })` returns an exact memory fetch
+- `search({ query })` returns semantic retrieval
+- `search({ id, query })` returns the exact memory plus related retrieval context
+- `search({})` is invalid and returns `{ "success": false, "error": { "code": "invalid_request", "message": "..." } }`
+
+All primary verbs return structured JSON text payloads. Success payloads begin with `"success": true`; failures use the shared `{ success: false, error: { code, message } }` envelope.
+
+All valid `search` calls return the same top-level payload shape:
+
+```json
+{
+  "success": true,
+  "mode": "exact | semantic | hybrid",
+  "query": "string | null",
+  "id": "string | null",
+  "exact_memory": {},
+  "context": "string",
+  "results": [],
+  "count": 0,
+  "degraded_mode": false,
+  "degraded_reason": null,
+  "warnings": []
+}
+```
+
 ## Source Contract (`context.add_source`)
 
 Input:
@@ -100,26 +152,46 @@ Output:
 
 ## Scoped MCP Generator
 
-```bash
+Print config to stdout:
+
+```text
 whisper-context-mcp scope --project my-project --source github --client claude
 ```
 
-Optional write:
+Write the generated config to a file:
 
-```bash
-whisper-context-mcp scope --project my-project --source github --client vscode --write "$HOME/.config/Code/User/mcp.json"
+```text
+whisper-context-mcp scope --project my-project --source github --client vscode --write /absolute/path/to/mcp.json
 ```
 
 ## Breaking Rename Migration
 
 Print full map:
 
-```bash
+```text
 whisper-context-mcp --print-tool-map
 ```
 
 This release removes legacy un-namespaced tool names.
 
+## Contract Metadata
+
+Public API metadata is available at:
+
+```text
+GET /v1/contracts/meta
+```
+
+It exposes:
+
+- current contract version
+- active surfaces (`http`, `sdk`, `mcp`)
+- approved primary MCP verbs
+- migration window and removal policy
+- deprecated HTTP routes with replacement hints
+
+It does not expose internal security checklist fields.
+
 ## Security Defaults
 
 Local ingest (`index.local_scan_ingest` and `type=local`) enforces:
@@ -129,18 +201,16 @@ Local ingest (`index.local_scan_ingest` and `type=local`) enforces:
 
 ## 30-Second Demo
 
-One-command wizard + production MCP connectors + scoped config:
+One command:
 
-```bash
+```text
 npx whisper-wizard
 ```
 
 Flow:
 1. Run wizard and complete auth/project setup.
-2. Add a source with MCP:
-`context.add_source` (for example GitHub/Web/PDF/Slack/Local/Video).
-3. Ask a grounded question:
-`context.query` or `context.evidence_answer` for citation-locked output.
+2. Add a source with MCP: `context.add_source`
+3. Ask a grounded question: `context.query` or `context.evidence_answer`
 
 ## License
 

package/dist/server.js

@@ -488,7 +488,7 @@ var WhisperContext = class _WhisperContext {
     });
     warnDeprecatedOnce(
       "whisper_context_class",
-      "[Whisper SDK] WhisperContext remains supported in v2 but is legacy. Prefer WhisperClient for runtime features (queue/cache/session/diagnostics)."
+      "[Whisper SDK] WhisperContext is deprecated in v3 and scheduled for removal in v4. Prefer WhisperClient for runtime features and future contract compatibility."
     );
   }
   withProject(project) {
@@ -1090,6 +1090,16 @@ var WhisperContext = class _WhisperContext {
       }
     });
   }
+  async getMemory(memoryId) {
+    try {
+      return await this.request(`/v1/memory/${memoryId}`);
+    } catch (error) {
+      if (!this.isEndpointNotFoundError(error)) {
+        throw error;
+      }
+      return this.request(`/v1/memories/${memoryId}`);
+    }
+  }
   async getMemoryVersions(memoryId) {
     return this.request(`/v1/memory/${memoryId}/versions`);
   }
@@ -1288,6 +1298,7 @@ var WhisperContext = class _WhisperContext {
     ingestSession: (params) => this.ingestSession(params),
     getSessionMemories: (params) => this.getSessionMemories(params),
     getUserProfile: (params) => this.getUserProfile(params),
+    get: (memoryId) => this.getMemory(memoryId),
     getVersions: (memoryId) => this.getMemoryVersions(memoryId),
     update: (memoryId, params) => this.updateMemory(memoryId, params),
     delete: (memoryId) => this.deleteMemory(memoryId),
@@ -1321,6 +1332,75 @@ var WhisperContext = class _WhisperContext {
   };
 };
 
+// ../src/mcp/search-payload.mjs
+function normalizeExactMemory(memory) {
+  if (!memory) return null;
+  return {
+    id: memory.id ? String(memory.id) : null,
+    type: memory.type ? String(memory.type) : memory.memoryType ? String(memory.memoryType) : null,
+    content: String(memory.content || ""),
+    user_id: memory.user_id ? String(memory.user_id) : memory.userId ? String(memory.userId) : null,
+    session_id: memory.session_id ? String(memory.session_id) : memory.sessionId ? String(memory.sessionId) : null,
+    updated_at: memory.updated_at ? String(memory.updated_at) : memory.updatedAt ? String(memory.updatedAt) : null,
+    metadata: memory.metadata && typeof memory.metadata === "object" && !Array.isArray(memory.metadata) ? memory.metadata : null
+  };
+}
+function normalizeSearchResults(results) {
+  return (results || []).map((result) => {
+    const candidate = result?.memory ? result.memory : result;
+    const similarity = result?.similarity;
+    return {
+      id: candidate?.id ? String(candidate.id) : null,
+      content: String(candidate?.content || result?.content || ""),
+      score: typeof similarity === "number" ? similarity : typeof result?.score === "number" ? result.score : similarity != null ? Number(similarity) : result?.score != null ? Number(result.score) : null,
+      source: result?.source ? String(result.source) : result?.chunk ? "memory" : null,
+      document: result?.document ? String(result.document) : result?.chunk?.id ? String(result.chunk.id) : null,
+      metadata: result?.metadata && typeof result.metadata === "object" && !Array.isArray(result.metadata) ? result.metadata : candidate?.metadata && typeof candidate.metadata === "object" && !Array.isArray(candidate.metadata) ? candidate.metadata : null,
+      memory_type: candidate?.type ? String(candidate.type) : candidate?.memory_type ? String(candidate.memory_type) : null
+    };
+  });
+}
+function normalizeCanonicalResults(input) {
+  if (Array.isArray(input?.results)) return input.results;
+  if (Array.isArray(input?.memories)) return input.memories;
+  return [];
+}
+function buildPrimaryToolSuccess(payload) {
+  return {
+    success: true,
+    ...payload
+  };
+}
+function buildPrimaryToolError(message, options = {}) {
+  return {
+    success: false,
+    error: {
+      code: options.code ?? "tool_error",
+      message
+    }
+  };
+}
+function buildMcpSearchPayload(input) {
+  const normalizedResults = normalizeSearchResults(input.results);
+  return buildPrimaryToolSuccess({
+    mode: input.mode,
+    query: input.query ?? null,
+    id: input.id ?? null,
+    exact_memory: normalizeExactMemory(input.exactMemory),
+    context: input.context ?? "",
+    results: normalizedResults,
+    count: normalizedResults.length,
+    degraded_mode: Boolean(input.degradedMode),
+    degraded_reason: input.degradedReason ?? null,
+    warnings: input.warnings || []
+  });
+}
+function buildMcpSearchError(message, options = {}) {
+  return buildPrimaryToolError(message, {
+    code: options.code ?? "invalid_request"
+  });
+}
+
 // ../src/mcp/server.ts
 var API_KEY = process.env.WHISPER_API_KEY || "";
 var DEFAULT_PROJECT = process.env.WHISPER_PROJECT || "";
@@ -1366,7 +1446,7 @@ var TOOL_MIGRATION_MAP = [
   { old: "semantic_search_codebase", next: "code.search_semantic" }
 ];
 var ALIAS_TOOL_MAP = [
-  { alias: "search", target: "context.query" },
+  { alias: "search", target: "context.query | memory.get" },
   { alias: "search_code", target: "code.search_semantic" },
   { alias: "grep", target: "code.search_text" },
   { alias: "read", target: "local.file_read" },
@@ -1374,7 +1454,8 @@ var ALIAS_TOOL_MAP = [
   { alias: "research", target: "research.oracle" },
   { alias: "index", target: "context.add_source | index.workspace_run" },
   { alias: "remember", target: "memory.add" },
-  { alias: "recall", target: "memory.search" },
+  { alias: "record", target: "memory.ingest_conversation" },
+  { alias: "learn", target: "context.add_text | context.add_source | context.add_document" },
   { alias: "share_context", target: "context.share" }
 ];
 function ensureStateDir() {
@@ -1567,6 +1648,25 @@ function countCodeFiles(searchPath, maxFiles = 5e3) {
 function toTextResult(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
 }
+function primaryToolSuccess(payload) {
+  return toTextResult(buildPrimaryToolSuccess(payload));
+}
+function primaryToolError(message, code = "tool_error") {
+  return toTextResult(buildPrimaryToolError(message, { code }));
+}
+function formatCanonicalMemoryResults(rawResults) {
+  const results = normalizeCanonicalResults(rawResults);
+  return results.map((result) => {
+    const memory = result?.memory || result;
+    return {
+      id: memory?.id ? String(memory.id) : null,
+      content: String(memory?.content || result?.content || ""),
+      memory_type: memory?.type ? String(memory.type) : memory?.memory_type ? String(memory.memory_type) : null,
+      similarity: typeof result?.similarity === "number" ? result.similarity : typeof result?.score === "number" ? result.score : null,
+      metadata: memory?.metadata && typeof memory.metadata === "object" && !Array.isArray(memory.metadata) ? memory.metadata : null
+    };
+  });
+}
 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");
@@ -1798,6 +1898,90 @@ async function createSourceByType(params) {
     warnings: []
   };
 }
+function normalizeRecordMessages(input) {
+  if (Array.isArray(input.messages) && input.messages.length > 0) {
+    return input.messages.map((message) => ({
+      role: message.role || "user",
+      content: message.content,
+      timestamp: message.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    }));
+  }
+  if (!input.content) {
+    throw new Error("Provide messages[] or content.");
+  }
+  return [{
+    role: input.role || "user",
+    content: input.content,
+    timestamp: input.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+  }];
+}
+async function learnFromInput(input) {
+  const resolvedProject = await resolveProjectRef(input.project);
+  if (!resolvedProject) {
+    throw new Error("No project resolved. Set WHISPER_PROJECT or provide project.");
+  }
+  if (input.content) {
+    const result = await whisper.addContext({
+      project: resolvedProject,
+      content: input.content,
+      title: input.title || "Learned Context",
+      metadata: input.metadata
+    });
+    return {
+      mode: "text",
+      project: resolvedProject,
+      ingested: result.ingested
+    };
+  }
+  if (input.owner && input.repo) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: "github",
+      owner: input.owner,
+      repo: input.repo,
+      branch: input.branch,
+      name: input.name,
+      auto_index: true,
+      metadata: input.metadata
+    });
+  }
+  if (input.path) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: "local",
+      path: input.path,
+      glob: input.glob,
+      max_files: input.max_files,
+      name: input.name,
+      metadata: input.metadata
+    });
+  }
+  if (input.file_path) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: "pdf",
+      file_path: input.file_path,
+      name: input.name,
+      metadata: input.metadata
+    });
+  }
+  if (input.url) {
+    return createSourceByType({
+      project: resolvedProject,
+      type: input.url.endsWith(".pdf") ? "pdf" : "web",
+      url: input.url,
+      name: input.name,
+      metadata: input.metadata,
+      crawl_depth: input.crawl_depth,
+      channel_ids: input.channel_ids,
+      token: input.token,
+      workspace_id: input.workspace_id,
+      since: input.since,
+      auth_ref: input.auth_ref
+    });
+  }
+  throw new Error("Provide content, owner+repo, path, file_path, or url.");
+}
 function scopeConfigJson(project, source, client) {
   const serverDef = {
     command: "npx",
@@ -2288,14 +2472,15 @@ server.tool(
         top_k,
         memory_types
       });
-      if (!results.memories || results.memories.length === 0) {
-        return { content: [{ type: "text", text: "No memories found." }] };
-      }
-      const text = results.memories.map((r, i) => `${i + 1}. [${r.memory_type}, score: ${r.similarity?.toFixed(3) || "N/A"}]
-${r.content}`).join("\n\n");
-      return { content: [{ type: "text", text }] };
+      const normalizedResults = formatCanonicalMemoryResults(results);
+      return primaryToolSuccess({
+        tool: "memory.search",
+        query,
+        results: normalizedResults,
+        count: normalizedResults.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -2511,23 +2696,17 @@ server.tool(
         top_k,
         include_relations
       });
-      if (!results.memories || results.memories.length === 0) {
-        return { content: [{ type: "text", text: "No memories found." }] };
-      }
-      const text = results.memories.map((r, i) => {
-        let line = `${i + 1}. [${r.memory_type}, score: ${r.similarity?.toFixed(3) || "N/A"}]
-`;
-        line += `   ${r.content}
-`;
-        if (r.event_date) {
-          line += `   Event: ${new Date(r.event_date).toISOString().split("T")[0]}
-`;
-        }
-        return line;
-      }).join("\n");
-      return { content: [{ type: "text", text }] };
+      const normalizedResults = formatCanonicalMemoryResults(results);
+      return primaryToolSuccess({
+        tool: "memory.search_sota",
+        query,
+        question_date: question_date || null,
+        include_relations,
+        results: normalizedResults,
+        count: normalizedResults.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3460,25 +3639,50 @@ server.tool(
 );
 server.tool(
   "search",
-  "Search indexed code, docs, and connected sources with one obvious verb. Use this first for most retrieval tasks.",
+  "Search retrievable context by query, exact id, or both. Use `id` for exact fetch and `query` for semantic retrieval.",
   {
     project: z.string().optional().describe("Project name or slug"),
-    query: z.string().describe("What you want to find"),
+    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()
   },
-  async ({ project, query, top_k, include_memories, include_graph, user_id, session_id }) => {
+  async ({ project, query, id, top_k, include_memories, include_graph, user_id, session_id }) => {
     try {
+      if (!id && !query) {
+        return toTextResult(buildMcpSearchError("Provide query, id, or both."));
+      }
+      let exactMemory;
+      if (id) {
+        const memoryResult = await whisper.getMemory(id);
+        exactMemory = memoryResult?.memory || memoryResult;
+      }
+      if (!query) {
+        return toTextResult(buildMcpSearchPayload({
+          mode: "exact",
+          id,
+          exactMemory
+        }));
+      }
       const resolvedProject = await resolveProjectRef(project);
       if (!resolvedProject) {
-        return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or pass project." }] };
+        if (exactMemory) {
+          return toTextResult(buildMcpSearchPayload({
+            mode: "hybrid",
+            query,
+            id,
+            exactMemory,
+            warnings: ["Project not resolved, so semantic context was skipped."]
+          }));
+        }
+        return toTextResult(buildMcpSearchError("No project resolved. Set WHISPER_PROJECT or pass project."));
       }
       const queryResult = await queryWithDegradedFallback({
         project: resolvedProject,
-        query,
+        query: query || exactMemory?.content || "",
         top_k,
         include_memories,
         include_graph,
@@ -3486,15 +3690,18 @@ server.tool(
         session_id
       });
       const response = queryResult.response;
-      if (!response.results?.length) {
-        return { content: [{ type: "text", text: `No relevant results found for "${query}".` }] };
-      }
-      const suffix = queryResult.degraded_mode ? `
-
-[degraded_mode=true] ${queryResult.degraded_reason}` : "";
-      return { content: [{ type: "text", text: response.context + suffix }] };
+      return toTextResult(buildMcpSearchPayload({
+        mode: exactMemory ? "hybrid" : "semantic",
+        query,
+        id,
+        exactMemory,
+        context: response.context,
+        results: response.results,
+        degradedMode: queryResult.degraded_mode,
+        degradedReason: queryResult.degraded_reason
+      }));
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3534,7 +3741,13 @@ server.tool(
     }
     collect(rootPath);
     if (files.length === 0) {
-      return { content: [{ type: "text", text: `No code files found in ${rootPath}` }] };
+      return primaryToolSuccess({
+        tool: "search_code",
+        query,
+        path: rootPath,
+        results: [],
+        count: 0
+      });
     }
     const documents = [];
     for (const filePath of files) {
@@ -3555,13 +3768,23 @@ server.tool(
         threshold: threshold ?? 0.2
       });
       if (!response.results?.length) {
-        return { content: [{ type: "text", text: `No semantically relevant files found for "${query}".` }] };
+        return primaryToolSuccess({
+          tool: "search_code",
+          query,
+          path: rootPath,
+          results: [],
+          count: 0
+        });
       }
-      const lines = response.results.map((result) => `${result.id} (score: ${result.score})${result.snippet ? `
-${result.snippet}` : ""}`);
-      return { content: [{ type: "text", text: lines.join("\n\n") }] };
+      return primaryToolSuccess({
+        tool: "search_code",
+        query,
+        path: rootPath,
+        results: response.results,
+        count: response.results.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Semantic search failed: ${error.message}` }] };
+      return primaryToolError(`Semantic search failed: ${error.message}`);
     }
   }
 );
@@ -3585,9 +3808,9 @@ server.tool(
         const stat = statSync(filePath);
         if (stat.size > 512 * 1024) continue;
         const text = readFileSync(filePath, "utf-8");
-        const lines2 = text.split("\n");
+        const lines = text.split("\n");
         const matches = [];
-        lines2.forEach((line, index) => {
+        lines.forEach((line, index) => {
           regex.lastIndex = 0;
           if (regex.test(line)) {
             matches.push({ line: index + 1, content: line.trimEnd() });
@@ -3600,14 +3823,21 @@ server.tool(
       }
     }
     if (!results.length) {
-      return { content: [{ type: "text", text: `No matches found for "${query}" in ${rootPath}` }] };
+      return primaryToolSuccess({
+        tool: "grep",
+        query,
+        path: rootPath,
+        results: [],
+        count: 0
+      });
     }
-    const lines = results.flatMap((result) => [
-      `FILE ${result.file}`,
-      ...result.matches.map((match) => `L${match.line}: ${match.content}`),
-      ""
-    ]);
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return primaryToolSuccess({
+      tool: "grep",
+      query,
+      path: rootPath,
+      results,
+      count: results.length
+    });
   }
 );
 server.tool(
@@ -3623,11 +3853,17 @@ server.tool(
       const fullPath = path.includes(":") || path.startsWith("/") ? path : join(process.cwd(), path);
       const stats = statSync(fullPath);
       if (!stats.isFile()) {
-        return { content: [{ type: "text", text: `Error: ${path} is not a file.` }] };
+        return primaryToolError(`${path} is not a file.`, "invalid_request");
       }
-      return { content: [{ type: "text", text: readFileWindow(fullPath, start_line, end_line) }] };
+      return primaryToolSuccess({
+        tool: "read",
+        path: fullPath,
+        start_line,
+        end_line,
+        content: readFileWindow(fullPath, start_line, end_line)
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3644,11 +3880,21 @@ server.tool(
       const rootPath = path || process.cwd();
       const tree = listTree(rootPath, max_depth, max_entries);
       if (!tree.length) {
-        return { content: [{ type: "text", text: `No visible files found in ${rootPath}` }] };
+        return primaryToolSuccess({
+          tool: "explore",
+          path: rootPath,
+          entries: [],
+          count: 0
+        });
       }
-      return { content: [{ type: "text", text: [`TREE ${rootPath}`, ...tree].join("\n") }] };
+      return primaryToolSuccess({
+        tool: "explore",
+        path: rootPath,
+        entries: tree,
+        count: tree.length
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3665,17 +3911,16 @@ server.tool(
   async ({ project, query, mode, max_results, max_steps }) => {
     try {
       const results = await whisper.oracleSearch({ project, query, mode, max_results, max_steps });
-      if (mode === "research" && results.answer) {
-        return { content: [{ type: "text", text: results.answer }] };
-      }
-      if (!results.results?.length) {
-        return { content: [{ type: "text", text: "No research results found." }] };
-      }
-      const text = results.results.map((r, i) => `${i + 1}. ${r.path || r.source}
-${String(r.content || "").slice(0, 200)}...`).join("\n\n");
-      return { content: [{ type: "text", text }] };
+      return primaryToolSuccess({
+        tool: "research",
+        mode,
+        query,
+        answer: results.answer || null,
+        results: results.results || [],
+        count: Array.isArray(results.results) ? results.results.length : 0
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3771,34 +4016,77 @@ server.tool(
   async ({ project, content, memory_type, user_id, session_id, agent_id, importance }) => {
     try {
       const result = await whisper.addMemory({ project, content, memory_type, user_id, session_id, agent_id, importance });
-      return { content: [{ type: "text", text: `Memory stored (id: ${result.id}, type: ${memory_type}).` }] };
+      return primaryToolSuccess({
+        tool: "remember",
+        id: result.id || null,
+        memory_type,
+        stored: result.success === true
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
 server.tool(
-  "recall",
-  "Recall facts, decisions, and preferences from previous sessions or prior work.",
+  "record",
+  "Record what just happened in a session or conversation. Use this for temporal capture, not durable preference storage.",
   {
     project: z.string().optional(),
-    query: z.string().describe("What to recall"),
+    session_id: z.string().describe("Session to record into"),
     user_id: z.string().optional(),
-    session_id: z.string().optional(),
-    top_k: z.number().optional().default(10),
-    memory_types: z.array(z.enum(["factual", "preference", "event", "relationship", "opinion", "goal", "instruction"])).optional()
+    messages: z.array(z.object({
+      role: z.string().optional(),
+      content: z.string(),
+      timestamp: z.string().optional()
+    })).optional(),
+    role: z.string().optional(),
+    content: z.string().optional(),
+    timestamp: z.string().optional()
   },
-  async ({ project, query, user_id, session_id, top_k, memory_types }) => {
+  async ({ project, session_id, user_id, messages, role, content, timestamp }) => {
     try {
-      const results = await whisper.searchMemoriesSOTA({ project, query, user_id, session_id, top_k, memory_types });
-      if (!results.memories?.length) {
-        return { content: [{ type: "text", text: "No memories found." }] };
-      }
-      const text = results.memories.map((r, i) => `${i + 1}. [${r.memory_type}, score: ${r.similarity?.toFixed(3) || "N/A"}]
-${r.content}`).join("\n\n");
-      return { content: [{ type: "text", text }] };
+      const normalizedMessages = normalizeRecordMessages({ messages, role, content, timestamp });
+      const result = await whisper.ingestSession({ project, session_id, user_id, messages: normalizedMessages });
+      return primaryToolSuccess({
+        tool: "record",
+        session_id,
+        messages_recorded: normalizedMessages.length,
+        memories_created: result.memories_created,
+        relations_created: result.relations_created
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
+    }
+  }
+);
+server.tool(
+  "learn",
+  "Learn content or connect a source so it becomes retrievable later. Use this for docs, URLs, repos, files, or local paths.",
+  {
+    project: z.string().optional(),
+    content: z.string().optional().describe("Inline text content to ingest"),
+    title: z.string().optional().describe("Title for inline content"),
+    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(),
+    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"),
+    metadata: z.record(z.string()).optional(),
+    max_files: z.number().optional(),
+    glob: z.string().optional(),
+    crawl_depth: z.number().optional()
+  },
+  async (input) => {
+    try {
+      const result = await learnFromInput(input);
+      return primaryToolSuccess({
+        tool: "learn",
+        ...result
+      });
+    } catch (error) {
+      return primaryToolError(error.message);
     }
   }
 );
@@ -3814,18 +4102,15 @@ server.tool(
   async ({ project, session_id, title, expiry_days }) => {
     try {
       const result = await whisper.createSharedContext({ project, session_id, title, expiry_days });
-      return {
-        content: [{
-          type: "text",
-          text: `Shared context created:
-- Share ID: ${result.share_id}
-- Expires: ${result.expires_at || "Never"}
-
-Share URL: ${result.share_url}`
-        }]
-      };
+      return primaryToolSuccess({
+        tool: "share_context",
+        share_id: result.share_id,
+        share_url: result.share_url,
+        expires_at: result.expires_at || null,
+        title: result.title || title || null
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );

package/package.json

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