@recapt/mcp 0.0.26 → 0.0.28

package/dist/index.js

@@ -1181,7 +1181,7 @@ var updateImprovementRunTool = {
   inputSchema: z27.object({
     run_id: z27.string().describe("The ID of the improvement run to update"),
     status: z27.enum(["running", "completed", "failed", "cancelled"]).optional().describe("New status for the run"),
-    title: z27.string().optional().describe("A concise title summarizing what was fixed in this run (e.g., 'Fixed checkout button, improved mobile nav'). Set when completing the run."),
+    title: z27.string().optional().describe("A user-friendly title summarizing what was improved (e.g., 'Fixed checkout responsiveness, improved mobile navigation'). Avoid technical jargon - write for non-developers."),
     phases: z27.array(z27.object({
       name: z27.string(),
       status: z27.enum([
@@ -1233,9 +1233,9 @@ var updateImprovementRunTool = {
 };
 var recordImprovementActionTool = {
   name: "record_improvement_action",
-  description: "Record an action taken during an improvement run. Use to track what was done for each issue: code fixes, deferrals, dismissals, etc. IMPORTANT: When recording code_fix actions, the code_changes.diff field must contain ACTUAL SOURCE CODE in unified diff format, not a description of what changed. Include the literal code lines with proper +/- prefixes.",
+  description: "Record an action taken during an improvement run. REQUIRED: run_id, action_type, hypothesis, expected_improvement. For code_fix: include code_changes array with actual unified diff format (not descriptions). For needs_more_data: include deferral_reason. For dismissed: include dismissal_reason. Use expected_improvement='N/A' for non-fix actions.",
   inputSchema: z27.object({
-    run_id: z27.string().describe("The ID of the improvement run"),
+    run_id: z27.string().describe("REQUIRED. The ID of the improvement run"),
     issue_id: z27.string().optional().describe("The ID of the issue this action relates to (if any)"),
     action_type: z27.enum([
       "code_fix",
@@ -1243,9 +1243,9 @@ var recordImprovementActionTool = {
       "dismissed",
       "marked_intended",
       "knowledge_added"
-    ]).describe("Type of action taken"),
-    hypothesis: z27.string().describe("AI's reasoning for this action"),
-    expected_improvement: z27.string().describe("What improvement is expected from this action"),
+    ]).describe("REQUIRED. Type of action taken"),
+    hypothesis: z27.string().describe("REQUIRED. AI's reasoning for this action"),
+    expected_improvement: z27.string().describe("REQUIRED. What improvement is expected (use 'N/A' for non-fix actions)"),
     code_changes: z27.array(z27.object({
       file: z27.string().describe("Path to the changed file"),
       diff: z27.string().describe("Unified diff format code changes"),
@@ -1269,6 +1269,12 @@ var recordImprovementActionTool = {
     if (!isApiConfigured()) {
       return apiNotConfiguredResult();
     }
+    if (remediation_id) {
+      const { data: remediation, error: remediationError } = await apiGet(`/remediations/${remediation_id}`);
+      if (remediationError || !remediation) {
+        return errorResult(`Remediation ${remediation_id} not found`);
+      }
+    }
     const { data, error } = await apiPost(`/improvement-runs/${run_id}/actions`, {
       issue_id,
       action_type,
@@ -1569,17 +1575,28 @@ var predictOutcomesTool = {
 import { z as z32 } from "zod";
 var proposeFixTool = {
   name: "propose_fix",
-  description: "Propose a fix for an issue. Creates a remediation record with baseline metrics for later evaluation. Include detailed diagnosis and code suggestions when possible.",
+  description: "Propose a fix for an issue. REQUIRED: issue_id, diagnosis, proposed_fix, confidence. Creates a remediation record with baseline metrics for later evaluation. Returns remediation_id for tracking.",
   inputSchema: z32.object({
-    issue_id: z32.string().describe("The ID of the issue to fix"),
-    diagnosis: z32.string().describe("Detailed analysis of the root cause of the issue"),
-    proposed_fix: z32.string().describe("Description of the proposed fix and how it addresses the root cause"),
+    issue_id: z32.string().describe("REQUIRED. The ID of the issue to fix"),
+    diagnosis: z32.string().describe("REQUIRED. Detailed analysis of the root cause of the issue"),
+    proposed_fix: z32.string().describe("REQUIRED. Description of the proposed fix and how it addresses the root cause"),
     code_snippet: z32.string().optional().describe("Suggested code changes (if applicable)"),
     affected_files: z32.array(z32.string()).optional().describe("List of files that need to be modified"),
-    confidence: z32.number().min(0).max(1).describe("Confidence level in the fix (0-1). Use <0.7 when uncertain.")
+    confidence: z32.number().min(0).max(1).describe("REQUIRED. Confidence level in the fix (0-1). Use <0.7 when uncertain."),
+    title: z32.string().optional().describe("User-friendly title describing the issue from the user's perspective"),
+    execution_metadata: z32.object({
+      difficulty_class: z32.enum(["trivial", "light", "heavy"]),
+      difficulty_reasoning: z32.string(),
+      model_used: z32.string(),
+      was_escalated: z32.boolean().optional(),
+      escalation_reason: z32.string().optional(),
+      iterations: z32.number().optional(),
+      credits_used: z32.number().optional(),
+      duration_ms: z32.number().optional()
+    }).optional().describe("AI execution metadata for tracking model selection and performance")
   }),
   handler: async (args) => {
-    const { issue_id, diagnosis, proposed_fix, code_snippet, affected_files, confidence } = args;
+    const { issue_id, diagnosis, proposed_fix, code_snippet, affected_files, confidence, title, execution_metadata } = args;
     if (!isApiConfigured()) {
       return apiNotConfiguredResult();
     }
@@ -1589,7 +1606,9 @@ var proposeFixTool = {
       proposed_fix,
       code_snippet,
       affected_files,
-      confidence
+      confidence,
+      title,
+      execution_metadata
     });
     if (error) {
       return errorResult(error);
@@ -1624,7 +1643,8 @@ var listRemediationsTool = {
       "evaluating",
       "succeeded",
       "failed",
-      "reverted"
+      "reverted",
+      "deferred"
     ]).optional().describe("Filter by remediation status"),
     issue_id: z32.string().optional().describe("Filter by issue ID"),
     page_path: z32.string().optional().describe("Filter by page path"),
@@ -1704,10 +1724,10 @@ var getFixHistoryTool = {
 };
 var updateRemediationStatusTool = {
   name: "update_remediation_status",
-  description: "Update the status of a remediation based on PR events. Use to mark a fix as 'waiting' (PR created), 'deployed' (PR merged), or 'dismissed' (PR closed without merge).",
+  description: "Update remediation status based on PR events. REQUIRED: remediation_id, status. Status values: 'waiting' (PR created), 'deployed' (PR merged), 'dismissed' (PR closed without merge).",
   inputSchema: z32.object({
-    remediation_id: z32.string().describe("The ID of the remediation to update"),
-    status: z32.enum(["waiting", "deployed", "dismissed"]).describe("New status: 'waiting' = PR open, 'deployed' = PR merged, 'dismissed' = PR closed without merge"),
+    remediation_id: z32.string().describe("REQUIRED. The ID of the remediation to update"),
+    status: z32.enum(["waiting", "deployed", "dismissed"]).describe("REQUIRED. One of: waiting, deployed, dismissed"),
     pr_url: z32.string().optional().describe("URL of the pull request"),
     pr_number: z32.number().optional().describe("PR number"),
     pr_merged_at: z32.string().optional().describe("ISO timestamp when PR was merged"),
@@ -1733,7 +1753,7 @@ var updateRemediationStatusTool = {
 };
 var listRemediationsByStatusTool = {
   name: "list_remediations_by_status",
-  description: "List remediations filtered by one or more statuses. Use to find all 'waiting' PRs or 'deployed' fixes ready for evaluation.",
+  description: "List remediations filtered by one or more statuses. Use to find all 'waiting' PRs or 'deployed' fixes ready for evaluation. Set include_execution to get difficulty classification for model selection.",
   inputSchema: z32.object({
     statuses: z32.array(z32.enum([
       "proposed",
@@ -1743,16 +1763,19 @@ var listRemediationsByStatusTool = {
       "evaluating",
       "succeeded",
       "failed",
-      "reverted"
-    ])).describe("List of statuses to filter by")
+      "reverted",
+      "deferred"
+    ])).describe("List of statuses to filter by"),
+    include_execution: z32.boolean().optional().describe("Include execution metadata (difficulty class, model used) for each remediation")
   }),
   handler: async (args) => {
-    const { statuses } = args;
+    const { statuses, include_execution } = args;
     if (!isApiConfigured()) {
       return apiNotConfiguredResult();
     }
     const { data, error } = await apiGet(`/remediations/by-status`, {
-      statuses: statuses.join(",")
+      statuses: statuses.join(","),
+      include_execution: include_execution ? "true" : void 0
     });
     if (error) {
       return errorResult(error);
@@ -1778,6 +1801,34 @@ var getRemediationByPrTool = {
     return successResult(data);
   }
 };
+var deferIssueTool = {
+  name: "defer_issue",
+  description: "Defer an issue that needs more data. REQUIRED: issue_id, diagnosis, deferral_reason, confidence. Creates a remediation record with 'deferred' status. Returns remediation_id for tracking.",
+  inputSchema: z32.object({
+    issue_id: z32.string().describe("REQUIRED. The ID of the issue to defer"),
+    diagnosis: z32.string().describe("REQUIRED. Analysis of what you think the problem might be"),
+    deferral_reason: z32.string().describe("REQUIRED. Explanation of why the issue cannot be fixed yet"),
+    confidence: z32.number().min(0).max(1).describe("REQUIRED. Confidence level in the diagnosis (0-1). Typically low for deferred issues."),
+    affected_files: z32.array(z32.string()).optional().describe("List of files that might need to be modified")
+  }),
+  handler: async (args) => {
+    const { issue_id, diagnosis, deferral_reason, confidence, affected_files } = args;
+    if (!isApiConfigured()) {
+      return apiNotConfiguredResult();
+    }
+    const { data, error } = await apiPost("/remediations/defer", {
+      issue_id,
+      diagnosis,
+      deferral_reason,
+      confidence,
+      affected_files
+    });
+    if (error) {
+      return errorResult(error);
+    }
+    return successResult(data);
+  }
+};
 
 // ../../libraries/mcp-tools/dist/tools/scanSite.js
 import { z as z33 } from "zod";
@@ -1841,11 +1892,11 @@ var DISMISS_REASONS = [
 ];
 var dismissIssueTool = {
   name: "dismiss_issue",
-  description: "Dismiss an issue as a false positive. Creates site knowledge to prevent re-flagging. Use when an issue is stale, intended behavior, a duplicate, or a false positive. Always confirm with user before dismissing.",
+  description: "Dismiss an issue as a false positive. REQUIRED: issue_id, reason (enum), explanation. Creates site knowledge to prevent re-flagging. Confirm with user before dismissing in interactive mode.",
   inputSchema: z35.object({
-    issue_id: z35.string().describe("The ID of the issue to dismiss"),
-    reason: z35.enum(DISMISS_REASONS).describe("Reason for dismissal: stale, intended, duplicate, or false_positive"),
-    explanation: z35.string().describe("Detailed explanation of why this issue is being dismissed"),
+    issue_id: z35.string().describe("REQUIRED. The ID of the issue to dismiss"),
+    reason: z35.enum(DISMISS_REASONS).describe("REQUIRED. One of: stale, intended, duplicate, false_positive"),
+    explanation: z35.string().describe("REQUIRED. Detailed explanation of why this issue is being dismissed"),
     create_knowledge: z35.boolean().optional().default(true).describe("Whether to create site knowledge entry (default: true)")
   }),
   handler: async (args) => {
@@ -2078,22 +2129,32 @@ var PROPOSAL_STATUSES = [
 ];
 var createProposalTool = {
   name: "create_proposal",
-  description: "Create a fix proposal for audit mode. Proposals are suggestions that developers review and implement manually. Use this in audit mode instead of propose_fix when you cannot make code changes directly.",
+  description: "AUDIT MODE ONLY. Create a fix proposal. REQUIRED: title, diagnosis, proposed_fix, confidence, page_path, category, severity. Proposals are suggestions that developers review and implement manually. Do NOT use in fix mode - use propose_fix instead.",
   inputSchema: z37.object({
     issue_id: z37.string().optional().describe("The ID of the related issue (if any)"),
     improvement_run_id: z37.string().optional().describe("The ID of the improvement run creating this proposal"),
-    title: z37.string().describe("Short title describing the proposed fix"),
-    diagnosis: z37.string().describe("Detailed analysis of the root cause of the issue"),
-    proposed_fix: z37.string().describe("Description of the proposed fix and how it addresses the root cause"),
+    title: z37.string().describe("REQUIRED. Short user-friendly title describing the issue from the user's perspective"),
+    diagnosis: z37.string().describe("REQUIRED. Detailed analysis of the root cause of the issue"),
+    proposed_fix: z37.string().describe("REQUIRED. Description of the proposed fix and how it addresses the root cause"),
     affected_files: z37.array(z37.string()).optional().describe("List of files that likely need to be modified"),
-    confidence: z37.number().min(0).max(1).describe("Confidence level in the fix (0-1). Use <0.7 when uncertain."),
-    page_path: z37.string().describe("The page path where the issue occurs"),
+    confidence: z37.number().min(0).max(1).describe("REQUIRED. Confidence level in the fix (0-1). Use <0.7 when uncertain."),
+    page_path: z37.string().describe("REQUIRED. The page path where the issue occurs"),
     element_selector: z37.string().optional().describe("CSS selector of the affected element (if applicable)"),
-    category: z37.enum(ISSUE_CATEGORIES2).describe("Category of the issue being addressed"),
-    severity: z37.enum(ISSUE_SEVERITIES).describe("Severity of the issue being addressed")
+    category: z37.enum(ISSUE_CATEGORIES2).describe("REQUIRED. Category: code_error, dead_click, rage_click, ux_friction, performance, form_issue, behavioral_anomaly, structural_issue"),
+    severity: z37.enum(ISSUE_SEVERITIES).describe("REQUIRED. Severity: critical, high, medium, low, info"),
+    execution_metadata: z37.object({
+      difficulty_class: z37.enum(["trivial", "light", "heavy"]),
+      difficulty_reasoning: z37.string(),
+      model_used: z37.string(),
+      was_escalated: z37.boolean().optional(),
+      escalation_reason: z37.string().optional(),
+      iterations: z37.number().optional(),
+      credits_used: z37.number().optional(),
+      duration_ms: z37.number().optional()
+    }).optional().describe("AI execution metadata for tracking model selection and performance")
   }),
   handler: async (args) => {
-    const { issue_id, improvement_run_id, title, diagnosis, proposed_fix, affected_files, confidence, page_path, element_selector, category, severity } = args;
+    const { issue_id, improvement_run_id, title, diagnosis, proposed_fix, affected_files, confidence, page_path, element_selector, category, severity, execution_metadata } = args;
     if (!isApiConfigured()) {
       return apiNotConfiguredResult();
     }
@@ -2108,7 +2169,8 @@ var createProposalTool = {
       page_path,
       element_selector,
       category,
-      severity
+      severity,
+      execution_metadata
     });
     if (error) {
       return errorResult(error);
@@ -2194,11 +2256,11 @@ var resolveProposalTool = {
 };
 var dismissProposalTool = {
   name: "dismiss_proposal",
-  description: "Dismiss a proposal that won't be implemented. Use when the proposal is not applicable, the issue is intended behavior, or a different approach is preferred.",
+  description: "Dismiss a proposal that won't be implemented. REQUIRED: proposal_id, reason. Use when the proposal is not applicable, the issue is intended behavior, or a different approach is preferred.",
   inputSchema: z37.object({
-    proposal_id: z37.string().describe("The ID of the proposal to dismiss"),
-    reason: z37.string().describe("Explanation of why the proposal is being dismissed"),
-    member_id: z37.string().optional().describe("The ID of the member who dismissed it (optional)")
+    proposal_id: z37.string().describe("REQUIRED. The ID of the proposal to dismiss"),
+    reason: z37.string().describe("REQUIRED. Explanation of why the proposal is being dismissed"),
+    member_id: z37.string().optional().describe("The ID of the member who dismissed it")
   }),
   handler: async (args) => {
     const { proposal_id, reason, member_id } = args;
@@ -2293,10 +2355,11 @@ async function gitlabRequest(endpoint, options = {}) {
   const ctx = getGitContext();
   const baseUrl = ctx.baseUrl || "https://gitlab.com";
   const url = `${baseUrl}/api/v4${endpoint}`;
+  const authHeader = ctx.token.startsWith("glpat-") ? { "PRIVATE-TOKEN": ctx.token } : { Authorization: `Bearer ${ctx.token}` };
   return fetch(url, {
     ...options,
     headers: {
-      "PRIVATE-TOKEN": ctx.token,
+      ...authHeader,
       "Content-Type": "application/json",
       ...options.headers
     }
@@ -2417,13 +2480,13 @@ var getFileContentTool = {
 };
 var updateFileTool = {
   name: "update_file",
-  description: "Update or create a file in the repository. Works with both GitHub and GitLab.",
+  description: "Update or create a file in the repository. Works with both GitHub and GitLab. SHA is auto-fetched for existing files.",
   inputSchema: z38.object({
     path: z38.string().describe("Path to the file in the repository"),
     content: z38.string().describe("New content for the file"),
     message: z38.string().describe("Commit message"),
     branch: z38.string().describe("Branch to commit to"),
-    sha: z38.string().optional().describe("SHA of the file being replaced (required for updates)")
+    sha: z38.string().optional().describe("SHA of the file being replaced (auto-fetched if not provided)")
   }),
   handler: async (args) => {
     try {
@@ -2432,8 +2495,15 @@ var updateFileTool = {
       const content = args.content;
       const message = args.message;
       const branch = args.branch;
-      const sha = args.sha;
+      let sha = args.sha;
       if (ctx.provider === "github") {
+        if (!sha) {
+          const checkRes = await githubRequest(`/repos/${ctx.repoFullName}/contents/${filePath}?ref=${branch}`);
+          if (checkRes.ok) {
+            const existingFile = await checkRes.json();
+            sha = existingFile.sha;
+          }
+        }
         const body = {
           message,
           content: Buffer.from(content).toString("base64"),
@@ -2461,7 +2531,15 @@ var updateFileTool = {
       } else {
         const encodedPath = encodeURIComponent(ctx.repoFullName);
         const encodedFilePath = encodeURIComponent(filePath);
-        const method = sha ? "PUT" : "POST";
+        let method = "POST";
+        if (!sha) {
+          const checkRes = await gitlabRequest(`/projects/${encodedPath}/repository/files/${encodedFilePath}?ref=${branch}`);
+          if (checkRes.ok) {
+            method = "PUT";
+          }
+        } else {
+          method = "PUT";
+        }
         const res = await gitlabRequest(`/projects/${encodedPath}/repository/files/${encodedFilePath}`, {
           method,
           body: JSON.stringify({
@@ -2859,6 +2937,7 @@ var allTools = [
   updateRemediationStatusTool,
   listRemediationsByStatusTool,
   getRemediationByPrTool,
+  deferIssueTool,
   // Scan
   scanSiteTool,
   // Search
@@ -2902,6 +2981,604 @@ var EXPOSED_TOOL_NAMES = [
 var exposedTools = allTools.filter((t) => EXPOSED_TOOL_NAMES.includes(t.name));
 var hiddenTools = allTools.filter((t) => !EXPOSED_TOOL_NAMES.includes(t.name));
 
+// ../../libraries/mcp-tools/dist/memory.js
+var MAX_ENTRIES = 100;
+var MAX_SIZE_BYTES = 2 * 1024 * 1024;
+var PRUNE_TARGET_RATIO = 0.8;
+var MemoryStore = class _MemoryStore {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Save a value to memory. Updates access tracking and triggers pruning if needed.
+   */
+  save(key, value, annotation) {
+    const now = Date.now();
+    const existing = this.store.get(key);
+    this.store.set(key, {
+      key,
+      value,
+      timestamp: existing?.timestamp ?? now,
+      annotation,
+      lastAccessedAt: now,
+      accessCount: existing?.accessCount ?? 0
+    });
+    this.pruneIfNeeded();
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ success: true, key, size: value.length })
+        }
+      ]
+    };
+  }
+  /**
+   * Save a value directly without returning ToolResult (for internal use).
+   */
+  saveRaw(key, value) {
+    const now = Date.now();
+    const existing = this.store.get(key);
+    this.store.set(key, {
+      key,
+      value,
+      timestamp: existing?.timestamp ?? now,
+      annotation: void 0,
+      lastAccessedAt: now,
+      accessCount: existing?.accessCount ?? 0
+    });
+    this.pruneIfNeeded();
+  }
+  /**
+   * Recall a value from memory. Updates access tracking.
+   * Supports optional query parameters for filtering and selecting data.
+   */
+  recall(key, options) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Key "${key}" not found in memory`,
+              available_keys: this.keys().slice(0, 10)
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+    entry.lastAccessedAt = Date.now();
+    entry.accessCount++;
+    if (!options || !options.where && !options.select && !options.limit) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: entry.value
+          }
+        ]
+      };
+    }
+    try {
+      const data = JSON.parse(entry.value);
+      const result = this.queryData(data, options);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result)
+          }
+        ]
+      };
+    } catch {
+      return {
+        content: [
+          {
+            type: "text",
+            text: entry.value
+          }
+        ]
+      };
+    }
+  }
+  /**
+   * Query data with filtering, selection, and pagination.
+   */
+  queryData(data, options) {
+    let items;
+    if (Array.isArray(data)) {
+      items = data;
+    } else if (this.isRecord(data)) {
+      const arrayField = Object.entries(data).find(([, v]) => Array.isArray(v));
+      if (arrayField) {
+        items = arrayField[1];
+      } else {
+        return data;
+      }
+    } else {
+      return data;
+    }
+    if (options.where && options.where.length > 0) {
+      items = items.filter((item) => this.matchesWhere(item, options.where));
+    }
+    if (options.select && options.select.length > 0) {
+      items = items.map((item) => this.selectFields(item, options.select));
+    }
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? items.length;
+    items = items.slice(offset, offset + limit);
+    return {
+      items,
+      total: items.length,
+      offset,
+      limit
+    };
+  }
+  isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  matchesWhere(item, conditions) {
+    if (!this.isRecord(item))
+      return true;
+    for (const condition of conditions) {
+      const match = condition.match(/^(\w+)\s*(>|<|>=|<=|==|!=|=)\s*(.+)$/);
+      if (!match)
+        continue;
+      const [, field, op, rawValue] = match;
+      const itemValue = item[field];
+      let compareValue = rawValue.trim();
+      if (compareValue === "true")
+        compareValue = true;
+      else if (compareValue === "false")
+        compareValue = false;
+      else if (!isNaN(Number(compareValue)))
+        compareValue = Number(compareValue);
+      else if (compareValue.startsWith('"') && compareValue.endsWith('"')) {
+        compareValue = compareValue.slice(1, -1);
+      }
+      let passes = false;
+      switch (op) {
+        case ">":
+          passes = Number(itemValue) > Number(compareValue);
+          break;
+        case "<":
+          passes = Number(itemValue) < Number(compareValue);
+          break;
+        case ">=":
+          passes = Number(itemValue) >= Number(compareValue);
+          break;
+        case "<=":
+          passes = Number(itemValue) <= Number(compareValue);
+          break;
+        case "==":
+        case "=":
+          passes = itemValue === compareValue;
+          break;
+        case "!=":
+          passes = itemValue !== compareValue;
+          break;
+      }
+      if (!passes)
+        return false;
+    }
+    return true;
+  }
+  selectFields(item, fields) {
+    if (!this.isRecord(item))
+      return {};
+    const result = {};
+    for (const field of fields) {
+      if (field in item) {
+        result[field] = item[field];
+      }
+    }
+    return result;
+  }
+  /**
+   * Recall a value directly without ToolResult wrapper (for internal use).
+   */
+  recallRaw(key) {
+    const entry = this.store.get(key);
+    if (!entry)
+      return void 0;
+    entry.lastAccessedAt = Date.now();
+    entry.accessCount++;
+    return entry.value;
+  }
+  /**
+   * Check if a key exists in memory.
+   */
+  has(key) {
+    return this.store.has(key);
+  }
+  /**
+   * Get all keys in memory.
+   */
+  keys() {
+    return [...this.store.keys()];
+  }
+  /**
+   * Get the number of entries in memory.
+   */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * List all entries with metadata.
+   */
+  list() {
+    const entries = [...this.store.values()].map((entry) => ({
+      key: entry.key,
+      size: entry.value.length,
+      timestamp: new Date(entry.timestamp).toISOString(),
+      annotation: entry.annotation,
+      accessCount: entry.accessCount
+    }));
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ count: entries.length, entries })
+        }
+      ]
+    };
+  }
+  /**
+   * Delete a key from memory.
+   */
+  delete(key) {
+    const existed = this.store.delete(key);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ success: true, deleted: existed })
+        }
+      ]
+    };
+  }
+  /**
+   * Clear all entries from memory.
+   */
+  clear() {
+    const count = this.store.size;
+    this.store.clear();
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ success: true, cleared: count })
+        }
+      ]
+    };
+  }
+  /**
+   * Build a human-readable memory key from tool name + input parameters.
+   */
+  static buildKey(toolName, input) {
+    const priorityFields = [
+      "page_path",
+      "session_id",
+      "session_ids",
+      "page_path_a",
+      "page_path_b",
+      "expression",
+      "query",
+      "moment_type",
+      "action",
+      "issue_id",
+      "remediation_id",
+      "proposal_id",
+      "run_id"
+    ];
+    for (const field of priorityFields) {
+      const value = input[field];
+      if (value !== void 0 && value !== null && value !== "") {
+        const strValue = Array.isArray(value) ? value.slice(0, 3).join(",") + (value.length > 3 ? "..." : "") : String(value);
+        return `${toolName}:${strValue}`;
+      }
+    }
+    const params = Object.entries(input).filter(([, v]) => v !== void 0 && v !== null).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${typeof v === "object" ? JSON.stringify(v) : v}`).join("&");
+    if (params) {
+      const hash = params.split("").reduce((acc, char) => {
+        return (acc << 5) - acc + char.charCodeAt(0) | 0;
+      }, 0);
+      return `${toolName}:${Math.abs(hash).toString(36)}`;
+    }
+    return toolName;
+  }
+  /**
+   * Get total size of all stored values in bytes.
+   */
+  getTotalSize() {
+    let total = 0;
+    for (const entry of this.store.values()) {
+      total += entry.value.length;
+    }
+    return total;
+  }
+  /**
+   * Prune entries if limits are exceeded.
+   * Uses a scoring system based on recency, access frequency, and size.
+   */
+  pruneIfNeeded() {
+    const overEntryLimit = this.store.size > MAX_ENTRIES;
+    const overSizeLimit = this.getTotalSize() > MAX_SIZE_BYTES;
+    if (!overEntryLimit && !overSizeLimit)
+      return;
+    const scored = [...this.store.entries()].map(([key, entry]) => ({
+      key,
+      entry,
+      score: this.computePruneScore(key, entry)
+    }));
+    scored.sort((a, b) => a.score - b.score);
+    const targetEntries = Math.floor(MAX_ENTRIES * PRUNE_TARGET_RATIO);
+    const targetSize = Math.floor(MAX_SIZE_BYTES * PRUNE_TARGET_RATIO);
+    while ((this.store.size > targetEntries || this.getTotalSize() > targetSize) && scored.length > 0) {
+      const toPrune = scored.shift();
+      if (!toPrune || toPrune.score >= 1e3)
+        break;
+      this.store.delete(toPrune.key);
+    }
+  }
+  /**
+   * Compute a score for pruning. Higher scores = more valuable = keep longer.
+   * System keys ($meta, $findings, etc.) are protected.
+   */
+  computePruneScore(key, entry) {
+    if (key.startsWith("$"))
+      return 1e3;
+    const now = Date.now();
+    const msSinceAccess = now - entry.lastAccessedAt;
+    const recencyScore = Math.max(0, 100 - msSinceAccess / 600);
+    const accessScore = Math.min(entry.accessCount * 10, 50);
+    const sizeScore = Math.max(0, 50 - entry.value.length / 1e3);
+    return recencyScore + accessScore + sizeScore;
+  }
+  /**
+   * Serialize all entries to a JSON string for external storage.
+   */
+  serialize() {
+    const plain = {};
+    for (const [k, entry] of this.store) {
+      plain[k] = entry.value;
+    }
+    return JSON.stringify(plain);
+  }
+  /**
+   * Hydrate a MemoryStore from a serialized JSON string.
+   */
+  static deserialize(json) {
+    const memory = new _MemoryStore();
+    const entries = JSON.parse(json);
+    const now = Date.now();
+    for (const [k, v] of Object.entries(entries)) {
+      memory.store.set(k, {
+        key: k,
+        value: v,
+        timestamp: now,
+        annotation: void 0,
+        lastAccessedAt: now,
+        accessCount: 0
+      });
+    }
+    return memory;
+  }
+};
+function createMemoryStore() {
+  return new MemoryStore();
+}
+
+// ../../libraries/mcp-tools/dist/wrapToolsWithMemory.js
+var SUMMARIZE_THRESHOLD = 2e3;
+var MAX_ARRAY_ITEMS = 2;
+var MAX_STRING_LENGTH = 120;
+var MAX_DEPTH = 3;
+var PASSTHROUGH_TOOLS = /* @__PURE__ */ new Set([
+  "memory_save",
+  "memory_recall",
+  "memory_list",
+  "memory_delete",
+  "memory_clear",
+  "search_tools",
+  "get_domains"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function wrapToolResult(toolName, args, result, memory, options) {
+  if (PASSTHROUGH_TOOLS.has(toolName)) {
+    return result;
+  }
+  const text = result.content[0]?.text;
+  if (!text || result.isError) {
+    return result;
+  }
+  if (text.length <= SUMMARIZE_THRESHOLD) {
+    return result;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return result;
+  }
+  if (isRecord(parsed) && parsed.error) {
+    return result;
+  }
+  const key = MemoryStore.buildKey(toolName, args);
+  memory.saveRaw(key, text);
+  const strategy = options?.strategy ?? "truncate";
+  const summary = strategy === "schema" ? summarizeSchema(parsed, key) : summarizeTruncate(parsed, key);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(summary)
+      }
+    ]
+  };
+}
+function summarizeTruncate(data, memoryKey) {
+  const summary = truncateDeep(data, 0);
+  addMemoryMetadata(summary, memoryKey, "truncate");
+  return isRecord(summary) ? summary : { data: summary, _memory_key: memoryKey };
+}
+function truncateDeep(value, depth) {
+  if (value == null || typeof value === "number" || typeof value === "boolean")
+    return value;
+  if (typeof value === "string") {
+    return value.length > MAX_STRING_LENGTH ? value.slice(0, 80) + "..." : value;
+  }
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_ARRAY_ITEMS).map((v) => truncateDeep(v, depth + 1));
+    if (value.length > MAX_ARRAY_ITEMS) {
+      items.push(`+${value.length - MAX_ARRAY_ITEMS} more in memory`);
+    }
+    return items;
+  }
+  if (isRecord(value)) {
+    if (depth >= MAX_DEPTH) {
+      const keys = Object.keys(value);
+      return `{${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", ..." : ""}}`;
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = truncateDeep(v, depth + 1);
+    }
+    return result;
+  }
+  return value;
+}
+function summarizeSchema(data, memoryKey) {
+  const summary = describeSchema(data, 0);
+  addMemoryMetadata(summary, memoryKey, "schema");
+  return isRecord(summary) ? summary : { data: summary, _memory_key: memoryKey };
+}
+var SCHEMA_MAX_DISTINCT = 6;
+var SCHEMA_PRIMITIVE_CAP = 5;
+var SCHEMA_DEPTH_LIMIT = 2;
+function round4(n) {
+  return Math.round(n * 1e4) / 1e4;
+}
+function describeSchema(value, depth) {
+  if (value == null)
+    return null;
+  if (typeof value === "number" || typeof value === "boolean")
+    return value;
+  if (typeof value === "string") {
+    return value.length > 200 ? value.slice(0, 150) + "..." : value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return [];
+    if (value[0] !== void 0 && isRecord(value[0])) {
+      return describeObjectArray(value);
+    }
+    if (value.length <= SCHEMA_PRIMITIVE_CAP)
+      return value;
+    return [
+      ...value.slice(0, SCHEMA_PRIMITIVE_CAP),
+      `+${value.length - SCHEMA_PRIMITIVE_CAP} more`
+    ];
+  }
+  if (isRecord(value)) {
+    if (depth >= SCHEMA_DEPTH_LIMIT) {
+      return { _keys: Object.keys(value) };
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = describeSchema(v, depth + 1);
+    }
+    return result;
+  }
+  return value;
+}
+function computeFieldStat(values) {
+  if (values.length === 0)
+    return { type: "null" };
+  if (values.every((v) => typeof v === "number")) {
+    const nums = values;
+    return {
+      type: "number",
+      min: round4(Math.min(...nums)),
+      max: round4(Math.max(...nums)),
+      avg: round4(nums.reduce((a, b) => a + b, 0) / nums.length)
+    };
+  }
+  if (values.every((v) => typeof v === "string")) {
+    const unique = [...new Set(values)];
+    return unique.length <= SCHEMA_MAX_DISTINCT ? { type: "string", values: unique } : { type: "string", distinct: unique.length, sample: unique.slice(0, 3) };
+  }
+  if (values.every((v) => typeof v === "boolean")) {
+    const trueCount = values.filter(Boolean).length;
+    return {
+      type: "boolean",
+      true_count: trueCount,
+      false_count: values.length - trueCount
+    };
+  }
+  if (values.every((v) => Array.isArray(v))) {
+    const arrays = values;
+    const avgLen = arrays.reduce((sum, a) => sum + a.length, 0) / arrays.length;
+    return { type: "array", avg_length: round4(avgLen) };
+  }
+  if (values.every((v) => isRecord(v))) {
+    const nestedKeys = /* @__PURE__ */ new Set();
+    for (const v of values) {
+      for (const k of Object.keys(v)) {
+        nestedKeys.add(k);
+      }
+    }
+    return { type: "object", keys: [...nestedKeys] };
+  }
+  return { type: "mixed" };
+}
+function describeObjectArray(items) {
+  const allKeys = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    for (const key of Object.keys(item))
+      allKeys.add(key);
+  }
+  const fields = [...allKeys];
+  const stats = {};
+  for (const field of fields) {
+    const values = items.map((item) => item[field]).filter((v) => v !== void 0 && v !== null);
+    stats[field] = computeFieldStat(values);
+  }
+  return {
+    _type: "array",
+    _count: items.length,
+    _fields: fields,
+    _stats: stats
+  };
+}
+function addMemoryMetadata(summary, memoryKey, strategy) {
+  if (!isRecord(summary))
+    return;
+  summary._memory_key = memoryKey;
+  if (strategy === "truncate") {
+    summary._recall = `Full data available via memory_recall with key "${memoryKey}"`;
+  } else {
+    const arrayPaths = detectArrayPaths(summary);
+    const pathHint = arrayPaths.length > 0 ? ` Array fields: ${arrayPaths.join(", ")}.` : "";
+    summary._hint = `Use memory_recall with key "${memoryKey}" to get full data.${pathHint}`;
+  }
+}
+function detectArrayPaths(data) {
+  if (!isRecord(data))
+    return [];
+  const paths = [];
+  for (const [key, value] of Object.entries(data)) {
+    if (key.startsWith("_"))
+      continue;
+    if (Array.isArray(value) && value.length > 0) {
+      paths.push(key);
+    }
+  }
+  return paths;
+}
+
 // src/tools/catalog/searchTools.ts
 import { z as z39 } from "zod";
 import { readFileSync } from "fs";
@@ -3053,16 +3730,108 @@ function registerSearchTools(server) {
 }
 
 // src/tools/catalog/callTool.ts
+import { z as z41 } from "zod";
+
+// src/tools/memory.ts
 import { z as z40 } from "zod";
+var memoryStore = null;
+function getMemoryStore() {
+  if (!memoryStore) {
+    memoryStore = createMemoryStore();
+  }
+  return memoryStore;
+}
+function getSharedMemoryStore() {
+  return getMemoryStore();
+}
+function registerMemoryTools(server) {
+  const memory = getMemoryStore();
+  server.registerTool(
+    "memory_save",
+    {
+      description: "Save a value to working memory for later retrieval. Use this to store intermediate results from tool calls that you want to reference later.",
+      inputSchema: z40.object({
+        key: z40.string().describe("Unique key to store the value under"),
+        value: z40.string().describe("Value to store (will be stored as string)"),
+        annotation: z40.string().optional().describe("Optional note about what this data represents")
+      })
+    },
+    async ({
+      key,
+      value,
+      annotation
+    }) => {
+      return memory.save(key, value, annotation);
+    }
+  );
+  server.registerTool(
+    "memory_recall",
+    {
+      description: "Retrieve a value from working memory by key. Supports optional filtering and selection for querying stored data. Use this to access data you previously stored or that was auto-saved from tool responses.",
+      inputSchema: z40.object({
+        key: z40.string().describe("Key to retrieve"),
+        where: z40.array(z40.string()).optional().describe(
+          'Filter conditions like ["frustration > 0.3", "status = active"]'
+        ),
+        select: z40.array(z40.string()).optional().describe("Fields to include in results"),
+        limit: z40.number().optional().describe("Maximum number of items to return"),
+        offset: z40.number().optional().describe("Number of items to skip")
+      })
+    },
+    async ({
+      key,
+      where,
+      select,
+      limit,
+      offset
+    }) => {
+      return memory.recall(key, { where, select, limit, offset });
+    }
+  );
+  server.registerTool(
+    "memory_list",
+    {
+      description: "List all keys currently stored in working memory. Returns key names, sizes, timestamps, annotations, and access counts.",
+      inputSchema: z40.object({})
+    },
+    async () => {
+      return memory.list();
+    }
+  );
+  server.registerTool(
+    "memory_delete",
+    {
+      description: "Delete a value from working memory by key.",
+      inputSchema: z40.object({
+        key: z40.string().describe("Key to delete")
+      })
+    },
+    async ({ key }) => {
+      return memory.delete(key);
+    }
+  );
+  server.registerTool(
+    "memory_clear",
+    {
+      description: "Clear all values from working memory. Use with caution.",
+      inputSchema: z40.object({})
+    },
+    async () => {
+      return memory.clear();
+    }
+  );
+}
+
+// src/tools/catalog/callTool.ts
 var toolRegistry = /* @__PURE__ */ new Map();
 function registerToolHandler(name, handler) {
   toolRegistry.set(name, handler);
 }
-var callToolSchema = z40.object({
-  tool_name: z40.string().describe(
+var callToolSchema = z41.object({
+  tool_name: z41.string().describe(
     "The exact name of the tool to call (e.g., 'get_page_metrics', 'analyze_flow', 'compare_cohorts')"
   ),
-  arguments: z40.record(z40.string(), z40.unknown()).describe(
+  arguments: z41.record(z41.string(), z41.unknown()).describe(
     "The arguments to pass to the tool as a JSON object. Check the tool description from search_tools for required parameters."
   )
 });
@@ -3070,7 +3839,7 @@ function registerCallTool(server) {
   server.registerTool(
     "call_tool",
     {
-      description: "Execute any analysis tool by name. Use search_tools first to discover available tools, then call them through this proxy. Pass the exact tool name and arguments as a JSON object. Example: call_tool({ tool_name: 'get_page_metrics', arguments: { page_path: '/checkout' } })",
+      description: "Execute any analysis tool by name. Use search_tools first to discover available tools, then call them through this proxy. Pass the exact tool name and arguments as a JSON object. Large responses are automatically saved to memory - use memory_recall to retrieve full data. Example: call_tool({ tool_name: 'get_page_metrics', arguments: { page_path: '/checkout' } })",
       inputSchema: callToolSchema
     },
     async ({ tool_name, arguments: args }) => {
@@ -3109,7 +3878,9 @@ function registerCallTool(server) {
         };
       }
       try {
-        return await handler(args);
+        const rawResult = await handler(args);
+        const memory = getSharedMemoryStore();
+        return wrapToolResult(tool_name, args, rawResult, memory);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return {
@@ -3130,138 +3901,6 @@ function registerCallTool(server) {
   );
 }
 
-// src/tools/memory.ts
-import { z as z41 } from "zod";
-var memoryStore = /* @__PURE__ */ new Map();
-function registerMemoryTools(server) {
-  server.registerTool(
-    "memory_save",
-    {
-      description: "Save a value to working memory for later retrieval. Use this to store intermediate results from tool calls that you want to reference later.",
-      inputSchema: z41.object({
-        key: z41.string().describe("Unique key to store the value under"),
-        value: z41.string().describe("Value to store (will be stored as string)"),
-        annotation: z41.string().optional().describe("Optional note about what this data represents")
-      })
-    },
-    async ({
-      key,
-      value,
-      annotation
-    }) => {
-      memoryStore.set(key, {
-        key,
-        value,
-        timestamp: Date.now(),
-        annotation
-      });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ success: true, key, size: value.length })
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "memory_recall",
-    {
-      description: "Retrieve a value from working memory by key. Use this to access data you previously stored with memory_save.",
-      inputSchema: z41.object({
-        key: z41.string().describe("Key to retrieve")
-      })
-    },
-    async ({ key }) => {
-      const entry = memoryStore.get(key);
-      if (!entry) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error: `Key "${key}" not found in memory`
-              })
-            }
-          ],
-          isError: true
-        };
-      }
-      return {
-        content: [
-          {
-            type: "text",
-            text: entry.value
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "memory_list",
-    {
-      description: "List all keys currently stored in working memory. Returns key names, sizes, timestamps, and annotations.",
-      inputSchema: z41.object({})
-    },
-    async () => {
-      const entries = [...memoryStore.values()].map((entry) => ({
-        key: entry.key,
-        size: entry.value.length,
-        timestamp: new Date(entry.timestamp).toISOString(),
-        annotation: entry.annotation
-      }));
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ count: entries.length, entries })
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "memory_delete",
-    {
-      description: "Delete a value from working memory by key.",
-      inputSchema: z41.object({
-        key: z41.string().describe("Key to delete")
-      })
-    },
-    async ({ key }) => {
-      const existed = memoryStore.delete(key);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ success: true, deleted: existed })
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "memory_clear",
-    {
-      description: "Clear all values from working memory. Use with caution.",
-      inputSchema: z41.object({})
-    },
-    async () => {
-      const count = memoryStore.size;
-      memoryStore.clear();
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ success: true, cleared: count })
-          }
-        ]
-      };
-    }
-  );
-}
-
 // src/index.ts
 function registerToolWithServer(server, tool) {
   server.tool(
@@ -3296,6 +3935,29 @@ call_tool({ tool_name: "analyze_flow", arguments: { start_page: "/pricing", end_
 \u2192 Returns: flow analysis with paths, bottlenecks, friction scores
 \`\`\`
 
+## Automatic Memory Storage
+
+Large tool responses (>500 chars) are automatically saved to memory and you receive a summary instead.
+This keeps your context lean while preserving all data for later retrieval.
+
+When you see a response with \`_memory_key\`, the full data is stored in memory:
+\`\`\`json
+{
+  "sessions": [{...}, {...}, "+18 more in memory"],
+  "_memory_key": "list_sessions:/checkout",
+  "_recall": "Full data available via memory_recall..."
+}
+\`\`\`
+
+To retrieve full data or query it:
+\`\`\`
+memory_recall({ key: "list_sessions:/checkout" })
+\u2192 Returns: Full JSON data
+
+memory_recall({ key: "...", where: ["frustration > 0.5"], select: ["session_id", "frustration"] })
+\u2192 Returns: Filtered and selected fields only
+\`\`\`
+
 ## Always-Available Tools
 
 These tools are always visible (no search needed):
@@ -3303,7 +3965,7 @@ These tools are always visible (no search needed):
 - **run_full_diagnostic** \u2014 Quick site health overview (lightweight, fast)
 - **triage_sessions** \u2014 Find sessions needing attention
 - **get_upgrade_options** \u2014 Check available plan upgrades and features
-- **memory_*** \u2014 Store/retrieve intermediate results
+- **memory_*** \u2014 Store/retrieve intermediate results (memory_recall supports where, select, limit, offset)
 
 ## Tier-Based Access
 
@@ -3348,7 +4010,7 @@ All behavioral scores are 0-1 where higher = more of that signal:
 - Backtrack hotspots suggest confusion on subsequent pages
 - Low confidence + high confusion = users don't understand what to do
 - High frustration + low confusion = users know what to do but can't (broken UI)
-- Use \`memory_save\` to store intermediate results when doing multi-step analysis
+- Large responses are auto-saved to memory - use \`memory_recall\` to query stored data
 
 ## Tool Limits