@contextstream/mcp-server 0.3.18 → 0.3.20

package/dist/index.js

@@ -5431,6 +5431,17 @@ var ContextStreamClient = class {
   // ============================================
   // Token-Saving Context Tools
   // ============================================
+  /**
+   * Record a token savings event for user-facing dashboard analytics.
+   * Best-effort: callers should not await this in latency-sensitive paths.
+   */
+  trackTokenSavings(body) {
+    const payload = this.withDefaults({
+      source: "mcp",
+      ...body
+    });
+    return request(this.config, "/analytics/token-savings", { body: payload });
+  }
   /**
    * Get a compact, token-efficient summary of workspace context.
    * Designed to be included in every AI prompt without consuming many tokens.
@@ -5519,7 +5530,31 @@ var ContextStreamClient = class {
     }
     parts.push("");
     parts.push('\u{1F4A1} Use session_recall("topic") for specific context');
-    const summary = parts.join("\n");
+    const candidateSummary = parts.join("\n");
+    const maxChars = maxTokens * 4;
+    const candidateLines = candidateSummary.split("\n");
+    const finalLines = [];
+    let used = 0;
+    for (const line of candidateLines) {
+      const next = (finalLines.length ? "\n" : "") + line;
+      if (used + next.length > maxChars) break;
+      finalLines.push(line);
+      used += next.length;
+    }
+    const summary = finalLines.join("\n");
+    this.trackTokenSavings({
+      tool: "session_summary",
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id,
+      candidate_chars: candidateSummary.length,
+      context_chars: summary.length,
+      max_tokens: maxTokens,
+      metadata: {
+        decision_count: decisionCount,
+        memory_count: memoryCount
+      }
+    }).catch(() => {
+    });
     return {
       summary,
       workspace_name: workspaceName,
@@ -5654,6 +5689,7 @@ var ContextStreamClient = class {
     const charsPerToken = 4;
     const maxChars = maxTokens * charsPerToken;
     const parts = [];
+    const candidateParts = [];
     const sources = [];
     let currentChars = 0;
     if (params.include_decisions !== false && withDefaults.workspace_id) {
@@ -5665,14 +5701,22 @@ var ContextStreamClient = class {
         });
         if (decisions.items) {
           parts.push("## Relevant Decisions\n");
+          candidateParts.push("## Relevant Decisions\n");
           currentChars += 25;
-          for (const d of decisions.items) {
-            const entry = `\u2022 ${d.title || "Decision"}
-`;
-            if (currentChars + entry.length > maxChars * 0.4) break;
-            parts.push(entry);
-            currentChars += entry.length;
-            sources.push({ type: "decision", title: d.title || "Decision" });
+          const decisionEntries = decisions.items.map((d) => {
+            const title = d.title || "Decision";
+            return { title, entry: `\u2022 ${title}
+` };
+          });
+          for (const d of decisionEntries) {
+            candidateParts.push(d.entry);
+          }
+          candidateParts.push("\n");
+          for (const d of decisionEntries) {
+            if (currentChars + d.entry.length > maxChars * 0.4) break;
+            parts.push(d.entry);
+            currentChars += d.entry.length;
+            sources.push({ type: "decision", title: d.title });
           }
           parts.push("\n");
         }
@@ -5689,16 +5733,23 @@ var ContextStreamClient = class {
         });
         if (memory.results) {
           parts.push("## Related Context\n");
+          candidateParts.push("## Related Context\n");
           currentChars += 20;
-          for (const m of memory.results) {
+          const memoryEntries = memory.results.map((m) => {
             const title = m.title || "Context";
             const content = m.content?.slice(0, 200) || "";
-            const entry = `\u2022 ${title}: ${content}...
-`;
-            if (currentChars + entry.length > maxChars * 0.7) break;
-            parts.push(entry);
-            currentChars += entry.length;
-            sources.push({ type: "memory", title });
+            return { title, entry: `\u2022 ${title}: ${content}...
+` };
+          });
+          for (const m of memoryEntries) {
+            candidateParts.push(m.entry);
+          }
+          candidateParts.push("\n");
+          for (const m of memoryEntries) {
+            if (currentChars + m.entry.length > maxChars * 0.7) break;
+            parts.push(m.entry);
+            currentChars += m.entry.length;
+            sources.push({ type: "memory", title: m.title });
           }
           parts.push("\n");
         }
@@ -5715,23 +5766,45 @@ var ContextStreamClient = class {
         });
         if (code.results) {
           parts.push("## Relevant Code\n");
+          candidateParts.push("## Relevant Code\n");
           currentChars += 18;
-          for (const c of code.results) {
+          const codeEntries = code.results.map((c) => {
             const path3 = c.file_path || "file";
             const content = c.content?.slice(0, 150) || "";
-            const entry = `\u2022 ${path3}: ${content}...
-`;
-            if (currentChars + entry.length > maxChars) break;
-            parts.push(entry);
-            currentChars += entry.length;
-            sources.push({ type: "code", title: path3 });
+            return { path: path3, entry: `\u2022 ${path3}: ${content}...
+` };
+          });
+          for (const c of codeEntries) {
+            candidateParts.push(c.entry);
+          }
+          for (const c of codeEntries) {
+            if (currentChars + c.entry.length > maxChars) break;
+            parts.push(c.entry);
+            currentChars += c.entry.length;
+            sources.push({ type: "code", title: c.path });
           }
         }
       } catch {
       }
     }
     const context = parts.join("");
+    const candidateContext = candidateParts.join("");
     const tokenEstimate = Math.ceil(context.length / charsPerToken);
+    this.trackTokenSavings({
+      tool: "ai_context_budget",
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id,
+      candidate_chars: candidateContext.length,
+      context_chars: context.length,
+      max_tokens: maxTokens,
+      metadata: {
+        include_decisions: params.include_decisions !== false,
+        include_memory: params.include_memory !== false,
+        include_code: !!params.include_code,
+        sources: sources.length
+      }
+    }).catch(() => {
+    });
     return {
       context,
       token_estimate: tokenEstimate,
@@ -5908,6 +5981,7 @@ var ContextStreamClient = class {
     let context;
     let charsUsed = 0;
     const maxChars = maxTokens * 4;
+    let candidateContext;
     if (format === "minified") {
       const parts = [];
       for (const item of items) {
@@ -5917,6 +5991,7 @@ var ContextStreamClient = class {
         charsUsed += entry.length + 1;
       }
       context = parts.join("|");
+      candidateContext = items.map((i) => `${i.type}:${i.value}`).join("|");
     } else if (format === "structured") {
       const grouped = {};
       for (const item of items) {
@@ -5926,6 +6001,12 @@ var ContextStreamClient = class {
         charsUsed += item.value.length + 5;
       }
       context = JSON.stringify(grouped);
+      const candidateGrouped = {};
+      for (const item of items) {
+        if (!candidateGrouped[item.type]) candidateGrouped[item.type] = [];
+        candidateGrouped[item.type].push(item.value);
+      }
+      candidateContext = JSON.stringify(candidateGrouped);
     } else {
       const lines = ["[CTX]"];
       for (const item of items) {
@@ -5936,6 +6017,12 @@ var ContextStreamClient = class {
       }
       lines.push("[/CTX]");
       context = lines.join("\n");
+      const candidateLines = ["[CTX]"];
+      for (const item of items) {
+        candidateLines.push(`${item.type}:${item.value}`);
+      }
+      candidateLines.push("[/CTX]");
+      candidateContext = candidateLines.join("\n");
     }
     if (context.length === 0 && withDefaults.workspace_id) {
       const wsHint = items.find((i) => i.type === "W")?.value || withDefaults.workspace_id.slice(0, 8);
@@ -5943,7 +6030,23 @@ var ContextStreamClient = class {
 W:${wsHint}
 [NO_MATCHES]
 [/CTX]`;
+      candidateContext = context;
     }
+    this.trackTokenSavings({
+      tool: "context_smart",
+      workspace_id: withDefaults.workspace_id,
+      project_id: withDefaults.project_id,
+      candidate_chars: candidateContext.length,
+      context_chars: context.length,
+      max_tokens: maxTokens,
+      metadata: {
+        format,
+        items: items.length,
+        keywords: keywords.slice(0, 10),
+        errors: errors.length
+      }
+    }).catch(() => {
+    });
     return {
       context,
       token_estimate: Math.ceil(context.length / 4),
@@ -6134,6 +6237,8 @@ You have access to ContextStream MCP tools for persistent memory and context.
 | **1st message** | \`session_init(folder_path="...", context_hint="<user's message>")\` |
 | **2nd+ messages** | \`context_smart(user_message="<user's message>")\` |
 | **After completing task** | \`session_capture(...)\` - MUST capture decisions/insights |
+| **User frustration/correction** | \`session_capture_lesson(...)\` - MUST capture lessons |
+| **Command/tool error + fix** | \`session_capture_lesson(...)\` - MUST capture lessons |
 
 **NO EXCEPTIONS.** Do not skip even if you think you have enough context.
 
@@ -6189,6 +6294,52 @@ You have access to ContextStream MCP tools for persistent memory and context.
 
 ---
 
+### Lesson Capture (MANDATORY)
+
+When:
+1. **Expresses frustration** (caps, profanity, "COME ON", "WTF", repeated corrections)
+2. **Corrects you** ("No, you should...", "That's wrong", "Fix this")
+3. **Points out a mistake** (broken code, wrong approach, production issue)
+4. **A command/tool call fails and you learn the correct fix** (even if the user didn\u2019t explicitly correct you)
+
+You MUST immediately call \`session_capture_lesson\` with:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| \`title\` | What to remember | "Verify assets in git before pushing" |
+| \`severity\` | \`critical\`/\`high\`/\`medium\`/\`low\` | \`critical\` for production issues |
+| \`category\` | \`workflow\`/\`code_quality\`/\`verification\`/\`communication\`/\`project_specific\` | \`workflow\` |
+| \`trigger\` | What action caused the problem | "Pushed code referencing images without committing them" |
+| \`impact\` | What went wrong | "Production 404 errors - broken landing page" |
+| \`prevention\` | How to prevent in future | "Run git status to check untracked files before pushing" |
+| \`keywords\` | Keywords for matching | \`["git", "images", "assets", "push"]\` |
+
+**Example call:**
+\`\`\`json
+{
+  "title": "Always verify assets in git before pushing code references",
+  "severity": "critical",
+  "category": "workflow",
+  "trigger": "Pushed code referencing /screenshots/*.png without committing images",
+  "impact": "Production 404 errors - broken landing page",
+  "prevention": "Run 'git status' to check untracked files before pushing code that references static assets",
+  "keywords": ["git", "images", "assets", "push", "404", "static"]
+}
+\`\`\`
+
+**Why this matters:**
+- Lessons are surfaced automatically in \`session_init\` and \`context_smart\`
+- Future sessions will warn you before repeating the same mistake
+- This prevents production issues and user frustration
+
+**Severity guide:**
+- \`critical\`: Production outages, data loss, security issues
+- \`high\`: Breaking changes, significant user impact
+- \`medium\`: Workflow inefficiencies, minor bugs
+- \`low\`: Style/preference corrections
+
+---
+
 ### Quick Examples
 
 \`\`\`
@@ -7182,7 +7333,7 @@ Automatically detects code files and skips ignored directories like node_modules
       title: "Initialize conversation session",
       description: `Initialize a new conversation session and automatically retrieve relevant context.
 This is the FIRST tool AI assistants should call when starting a conversation.
-Returns: workspace info, project info, recent memory, recent decisions, and relevant context.
+Returns: workspace info, project info, recent memory, recent decisions, relevant context, and high-priority lessons.
 Automatically detects the IDE workspace/project path and can auto-index code.
 
 IMPORTANT: Pass the user's FIRST MESSAGE as context_hint to get semantically relevant context!
@@ -7929,7 +8080,7 @@ Format options:
 - 'readable': Line-separated with labels
 - 'structured': JSON-like grouped format
 
-Type codes: W=Workspace, P=Project, D=Decision, M=Memory, I=Insight, T=Task
+Type codes: W=Workspace, P=Project, D=Decision, M=Memory, I=Insight, T=Task, L=Lesson
 
 Example usage:
 1. User asks "how should I implement auth?"
@@ -8027,7 +8178,7 @@ function registerPrompts(server) {
       title: "Explore Codebase",
       description: "Get an overview of a project codebase structure and key components",
       argsSchema: {
-        project_id: external_exports.string().uuid().describe("Project ID to explore"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID to explore (optional if session_init has set defaults)"),
         focus_area: external_exports.string().optional().describe('Optional area to focus on (e.g., "authentication", "api routes")')
       }
     },
@@ -8037,12 +8188,14 @@ function registerPrompts(server) {
           role: "user",
           content: {
             type: "text",
-            text: `I want to understand the codebase for project ${args.project_id}${args.focus_area ? ` with focus on ${args.focus_area}` : ""}.
+            text: `I want to understand the codebase${args.project_id ? ` for project ${args.project_id}` : ""}${args.focus_area ? ` with focus on ${args.focus_area}` : ""}.
+
+If project_id is not provided, first call \`session_init\` (or \`projects_list\`) to resolve the current project ID.
 
 Please help me by:
-1. First, use \`projects.overview\` to get the project summary
-2. Use \`projects.files\` to list the key files
-3. Use \`search.semantic\` to find relevant code${args.focus_area ? ` related to "${args.focus_area}"` : ""}
+1. First, use \`projects_overview\` to get the project summary
+2. Use \`projects_files\` to list the key files
+3. Use \`search_semantic\` to find relevant code${args.focus_area ? ` related to "${args.focus_area}"` : ""}
 4. Summarize the architecture and key patterns you observe
 
 Provide a clear, structured overview that helps me navigate this codebase effectively.`
@@ -8057,7 +8210,7 @@ Provide a clear, structured overview that helps me navigate this codebase effect
       title: "Capture Decision",
       description: "Document an architectural or technical decision in workspace memory",
       argsSchema: {
-        workspace_id: external_exports.string().uuid().describe("Workspace ID"),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional if session_init has set defaults)"),
         decision_title: external_exports.string().describe("Brief title of the decision"),
         context: external_exports.string().describe("What prompted this decision"),
         decision: external_exports.string().describe("The decision made"),
@@ -8077,12 +8230,15 @@ Provide a clear, structured overview that helps me navigate this codebase effect
 **Decision:** ${args.decision}
 ${args.consequences ? `**Consequences:** ${args.consequences}` : ""}
 
-Use \`memory.create_event\` with:
+If workspace_id is not provided, first call \`session_init\` to resolve the workspace, then capture the decision.
+
+Use \`session_capture\` with:
 - event_type: "decision"
-- workspace_id: "${args.workspace_id}"
-- title: The decision title
+${args.workspace_id ? `- workspace_id: "${args.workspace_id}"` : "- workspace_id: (omit to use session defaults)"}
+- title: "${args.decision_title}"
 - content: A well-formatted ADR (Architecture Decision Record) with context, decision, and consequences
-- metadata: Include relevant tags and status
+- tags: Include relevant tags (e.g., "adr", "architecture")
+- importance: "high"
 
 After creating, confirm the decision was recorded and summarize it.`
           }
@@ -8096,7 +8252,7 @@ After creating, confirm the decision was recorded and summarize it.`
       title: "Code Review Context",
       description: "Build context for reviewing code changes",
       argsSchema: {
-        project_id: external_exports.string().uuid().describe("Project ID"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional if session_init has set defaults)"),
         file_paths: external_exports.string().describe("Comma-separated file paths being changed"),
         change_description: external_exports.string().describe("Brief description of the changes")
       }
@@ -8112,10 +8268,10 @@ After creating, confirm the decision was recorded and summarize it.`
 Change description: ${args.change_description}
 
 Please help me understand the impact by:
-1. Use \`graph.dependencies\` to find what depends on these files
-2. Use \`graph.impact\` to analyze potential impact
-3. Use \`memory.search\` to find related decisions or notes about these areas
-4. Use \`search.semantic\` to find related code patterns
+1. Use \`graph_dependencies\` to find what depends on these files
+2. Use \`graph_impact\` to analyze potential impact
+3. Use \`memory_search\` to find related decisions or notes about these areas
+4. Use \`search_semantic\` to find related code patterns
 
 Provide:
 - Summary of what these files do
@@ -8133,7 +8289,7 @@ Provide:
       title: "Investigate Bug",
       description: "Build context for debugging an issue",
       argsSchema: {
-        project_id: external_exports.string().uuid().describe("Project ID"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional if session_init has set defaults)"),
         error_message: external_exports.string().describe("Error message or symptom"),
         affected_area: external_exports.string().optional().describe("Known affected area or component")
       }
@@ -8150,10 +8306,10 @@ Provide:
 ${args.affected_area ? `**Affected Area:** ${args.affected_area}` : ""}
 
 Please help me investigate by:
-1. Use \`search.semantic\` to find code related to this error
-2. Use \`search.pattern\` to find where similar errors are thrown
-3. Use \`graph.call_path\` to trace call flows if we identify key functions
-4. Use \`memory.search\` to check if this issue has been encountered before
+1. Use \`search_semantic\` to find code related to this error
+2. Use \`search_pattern\` to find where similar errors are thrown
+3. Use \`graph_call_path\` to trace call flows if we identify key functions
+4. Use \`memory_search\` to check if this issue has been encountered before
 
 Provide:
 - Likely locations where this error originates
@@ -8171,7 +8327,7 @@ Provide:
       title: "Explore Knowledge Graph",
       description: "Navigate and understand the knowledge graph for a workspace",
       argsSchema: {
-        workspace_id: external_exports.string().uuid().describe("Workspace ID"),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional if session_init has set defaults)"),
         starting_topic: external_exports.string().optional().describe("Topic to start exploration from")
       }
     },
@@ -8181,13 +8337,15 @@ Provide:
           role: "user",
           content: {
             type: "text",
-            text: `Help me explore the knowledge captured in workspace ${args.workspace_id}${args.starting_topic ? ` starting from "${args.starting_topic}"` : ""}.
+            text: `Help me explore the knowledge captured in the current workspace${args.workspace_id ? ` (${args.workspace_id})` : ""}${args.starting_topic ? ` starting from "${args.starting_topic}"` : ""}.
+
+If workspace_id is not provided, first call \`session_init\` to resolve the workspace.
 
 Please:
-1. Use \`memory.list_nodes\` to see available knowledge nodes
-2. Use \`memory.decisions\` to see decision history
-3. ${args.starting_topic ? `Use \`memory.search\` to find nodes related to "${args.starting_topic}"` : "Use `memory.summary` to get an overview"}
-4. Use \`graph.related\` to explore connections between nodes
+1. Use \`memory_list_nodes\` to see available knowledge nodes
+2. Use \`memory_decisions\` to see decision history
+3. ${args.starting_topic ? `Use \`memory_search\` to find nodes related to "${args.starting_topic}"` : "Use `memory_summary` to get an overview"}
+4. Use \`graph_related\` to explore connections between nodes
 
 Provide:
 - Overview of knowledge captured
@@ -8205,8 +8363,8 @@ Provide:
       title: "Project Onboarding",
       description: "Generate onboarding context for a new team member",
       argsSchema: {
-        project_id: external_exports.string().uuid().describe("Project ID"),
-        workspace_id: external_exports.string().uuid().describe("Workspace ID"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional if session_init has set defaults)"),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional if session_init has set defaults)"),
         role: external_exports.string().optional().describe('Role of the person being onboarded (e.g., "backend developer", "frontend developer")')
       }
     },
@@ -8220,11 +8378,11 @@ Provide:
 ${args.role ? `They will be working as a ${args.role}.` : ""}
 
 Please gather comprehensive context:
-1. Use \`projects.overview\` and \`projects.statistics\` for project summary
-2. Use \`projects.files\` to identify key entry points
-3. Use \`memory.timeline\` to see recent activity and changes
-4. Use \`memory.decisions\` to understand key architectural choices
-5. Use \`search.semantic\` to find documentation and READMEs
+1. Use \`projects_overview\` and \`projects_statistics\` for project summary
+2. Use \`projects_files\` to identify key entry points
+3. Use \`memory_timeline\` to see recent activity and changes
+4. Use \`memory_decisions\` to understand key architectural choices
+5. Use \`search_semantic\` to find documentation and READMEs
 
 Provide an onboarding guide that includes:
 - Project overview and purpose
@@ -8244,7 +8402,7 @@ Provide an onboarding guide that includes:
       title: "Refactoring Analysis",
       description: "Analyze a codebase for refactoring opportunities",
       argsSchema: {
-        project_id: external_exports.string().uuid().describe("Project ID"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional if session_init has set defaults)"),
         target_area: external_exports.string().optional().describe("Specific area to analyze")
       }
     },
@@ -8257,10 +8415,10 @@ Provide an onboarding guide that includes:
             text: `Analyze the codebase for refactoring opportunities${args.target_area ? ` in ${args.target_area}` : ""}.
 
 Please investigate:
-1. Use \`graph.circular_dependencies\` to find circular dependencies
-2. Use \`graph.unused_code\` to find dead code
-3. Use \`search.pattern\` to find code duplication patterns
-4. Use \`projects.statistics\` to identify complex areas
+1. Use \`graph_circular_dependencies\` to find circular dependencies
+2. Use \`graph_unused_code\` to find dead code
+3. Use \`search_pattern\` to find code duplication patterns
+4. Use \`projects_statistics\` to identify complex areas
 
 Provide:
 - Circular dependencies that should be broken
@@ -8295,7 +8453,7 @@ Provide:
 
 **Query:** ${args.query}
 
-Please use \`ai.enhanced_context\` with:
+Please use \`ai_enhanced_context\` with:
 - query: "${args.query}"
 ${args.workspace_id ? `- workspace_id: "${args.workspace_id}"` : ""}
 ${args.project_id ? `- project_id: "${args.project_id}"` : ""}
@@ -8309,6 +8467,491 @@ Then synthesize the retrieved context into a coherent briefing that will help wi
       ]
     })
   );
+  server.registerPrompt(
+    "smart-search",
+    {
+      title: "Smart Search",
+      description: "Search across memory, decisions, and code for a query",
+      argsSchema: {
+        query: external_exports.string().describe("What you want to find"),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Find the most relevant context for: "${args.query}"
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Please:
+1. Use \`session_smart_search\` with query "${args.query}"${args.workspace_id ? ` and workspace_id "${args.workspace_id}"` : ""}${args.project_id ? ` and project_id "${args.project_id}"` : ""}
+2. If results are thin, follow up with \`search_hybrid\` and \`memory_search\`
+3. Return the top results with file paths/links and a short synthesis of what matters`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "recall-context",
+    {
+      title: "Recall Context",
+      description: "Retrieve relevant past decisions and memory for a query",
+      argsSchema: {
+        query: external_exports.string().describe("What to recall (natural language)"),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Recall relevant context for: "${args.query}"
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Use \`session_recall\` with query "${args.query}"${args.workspace_id ? ` and workspace_id "${args.workspace_id}"` : ""}${args.project_id ? ` and project_id "${args.project_id}"` : ""}.
+Then summarize the key points and any relevant decisions/lessons.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "session-summary",
+    {
+      title: "Session Summary",
+      description: "Get a compact summary of workspace/project context",
+      argsSchema: {
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        max_tokens: external_exports.string().optional().describe("Max tokens for summary (default: 500)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Generate a compact, token-efficient summary of the current workspace/project context.
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Use \`session_summary\`${args.workspace_id ? ` with workspace_id "${args.workspace_id}"` : ""}${args.project_id ? ` and project_id "${args.project_id}"` : ""}${args.max_tokens ? ` and max_tokens ${args.max_tokens} (number)` : ""}.
+Then list the top decisions (titles only) and any high-priority lessons to watch for.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-lesson",
+    {
+      title: "Capture Lesson",
+      description: "Record a lesson learned from an error or correction",
+      argsSchema: {
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        title: external_exports.string().describe("Lesson title (what to remember)"),
+        severity: external_exports.string().optional().describe("low|medium|high|critical (default: medium)"),
+        category: external_exports.string().describe("workflow|code_quality|verification|communication|project_specific"),
+        trigger: external_exports.string().describe("What action caused the problem"),
+        impact: external_exports.string().describe("What went wrong"),
+        prevention: external_exports.string().describe("How to prevent in future"),
+        keywords: external_exports.string().optional().describe("Comma-separated keywords (optional)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Capture this lesson so it is surfaced in future sessions:
+
+Title: ${args.title}
+Severity: ${args.severity || "medium"}
+Category: ${args.category}
+Trigger: ${args.trigger}
+Impact: ${args.impact}
+Prevention: ${args.prevention}
+${args.keywords ? `Keywords: ${args.keywords}` : ""}
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Use \`session_capture_lesson\` with the fields above. If keywords were provided, split the comma-separated list into an array of strings.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-preference",
+    {
+      title: "Capture Preference",
+      description: "Save a user preference to memory",
+      argsSchema: {
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        title: external_exports.string().optional().describe("Preference title (optional)"),
+        preference: external_exports.string().describe("Preference details to remember")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Save this preference to memory:
+
+${args.title ? `Title: ${args.title}
+` : ""}Preference: ${args.preference}
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Use \`session_capture\` with:
+- event_type: "preference"
+- title: ${args.title ? `"${args.title}"` : "(choose a short title)"}
+- content: "${args.preference}"
+- importance: "medium"`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-task",
+    {
+      title: "Capture Task",
+      description: "Capture an action item into memory",
+      argsSchema: {
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        title: external_exports.string().optional().describe("Task title (optional)"),
+        task: external_exports.string().describe("Task details")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Capture this task in memory for tracking:
+
+${args.title ? `Title: ${args.title}
+` : ""}Task: ${args.task}
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Use \`session_capture\` with:
+- event_type: "task"
+- title: ${args.title ? `"${args.title}"` : "(choose a short title)"}
+- content: "${args.task}"
+- importance: "medium"`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-bug",
+    {
+      title: "Capture Bug",
+      description: "Capture a bug report into workspace memory",
+      argsSchema: {
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        title: external_exports.string().describe("Bug title"),
+        description: external_exports.string().describe("Bug description"),
+        reproduction_steps: external_exports.string().optional().describe("Steps to reproduce (optional)"),
+        expected: external_exports.string().optional().describe("Expected behavior (optional)"),
+        actual: external_exports.string().optional().describe("Actual behavior (optional)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Capture this bug report in memory:
+
+Title: ${args.title}
+Description: ${args.description}
+${args.reproduction_steps ? `Steps to reproduce:
+${args.reproduction_steps}
+` : ""}${args.expected ? `Expected:
+${args.expected}
+` : ""}${args.actual ? `Actual:
+${args.actual}
+` : ""}
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Use \`session_capture\` with:
+- event_type: "bug"
+- title: "${args.title}"
+- content: A well-formatted bug report with the details above
+- tags: include relevant component/area tags
+- importance: "high"`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "capture-feature",
+    {
+      title: "Capture Feature",
+      description: "Capture a feature request into workspace memory",
+      argsSchema: {
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        title: external_exports.string().describe("Feature title"),
+        description: external_exports.string().describe("Feature description"),
+        rationale: external_exports.string().optional().describe("Why this matters (optional)"),
+        acceptance_criteria: external_exports.string().optional().describe("Acceptance criteria (optional)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Capture this feature request in memory:
+
+Title: ${args.title}
+Description: ${args.description}
+${args.rationale ? `Rationale:
+${args.rationale}
+` : ""}${args.acceptance_criteria ? `Acceptance criteria:
+${args.acceptance_criteria}
+` : ""}
+
+If workspace_id/project_id are not provided, call \`session_init\` first to resolve the current workspace/project.
+
+Use \`session_capture\` with:
+- event_type: "feature"
+- title: "${args.title}"
+- content: A well-formatted feature request with the details above
+- tags: include relevant component/area tags
+- importance: "medium"`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "generate-plan",
+    {
+      title: "Generate Plan",
+      description: "Generate a development plan from a description",
+      argsSchema: {
+        description: external_exports.string().describe("What you want to build/fix"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        complexity: external_exports.string().optional().describe("low|medium|high (optional)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Generate a development plan for:
+
+${args.description}
+
+Use \`ai_plan\` with:
+- description: "${args.description}"
+${args.project_id ? `- project_id: "${args.project_id}"` : ""}
+${args.complexity ? `- complexity: "${args.complexity}"` : ""}
+
+Then present the plan as a concise ordered list with clear milestones and risks.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "generate-tasks",
+    {
+      title: "Generate Tasks",
+      description: "Generate actionable tasks from a plan or description",
+      argsSchema: {
+        plan_id: external_exports.string().optional().describe("Plan ID (optional)"),
+        description: external_exports.string().optional().describe("Description to generate tasks from (optional if plan_id provided)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        granularity: external_exports.string().optional().describe("fine|medium|coarse (optional)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Generate actionable tasks.
+
+${args.plan_id ? `Use plan_id: ${args.plan_id}` : ""}${!args.plan_id && args.description ? `Use description: ${args.description}` : ""}
+
+Use \`ai_tasks\` with:
+${args.plan_id ? `- plan_id: "${args.plan_id}"` : ""}${!args.plan_id && args.description ? `- description: "${args.description}"` : ""}
+${args.project_id ? `- project_id: "${args.project_id}"` : ""}
+${args.granularity ? `- granularity: "${args.granularity}"` : ""}
+
+Then output a checklist of tasks with clear acceptance criteria for each.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "token-budget-context",
+    {
+      title: "Token-Budget Context",
+      description: "Get the most relevant context that fits within a token budget",
+      argsSchema: {
+        query: external_exports.string().describe("What you need context for"),
+        max_tokens: external_exports.string().describe("Max tokens for context (e.g., 500, 1000, 2000)"),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        include_code: external_exports.string().optional().describe('Include code ("true" or "false")')
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Build the most relevant context for:
+
+Query: ${args.query}
+Token budget: ${args.max_tokens}
+
+Use \`ai_context_budget\` with:
+- query: "${args.query}"
+- max_tokens: ${args.max_tokens} (number)
+${args.workspace_id ? `- workspace_id: "${args.workspace_id}"` : ""}
+${args.project_id ? `- project_id: "${args.project_id}"` : ""}
+${args.include_code ? `- include_code: ${args.include_code}` : ""}
+
+Return the packed context plus a short note about what was included/excluded.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "find-todos",
+    {
+      title: "Find TODOs",
+      description: "Scan the codebase for TODO/FIXME/HACK notes and summarize",
+      argsSchema: {
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional)"),
+        pattern: external_exports.string().optional().describe("Regex/pattern to search (default: TODO|FIXME|HACK)")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Find TODO-style notes in the codebase.
+
+If project_id is not provided, first call \`session_init\` (or \`projects_list\`) to resolve the current project ID.
+
+Use \`search_pattern\` with query "${args.pattern || "TODO|FIXME|HACK"}"${args.project_id ? ` and project_id "${args.project_id}"` : ""}.
+Group results by file path, summarize themes, and propose a small prioritized cleanup list.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "generate-editor-rules",
+    {
+      title: "Generate Editor Rules",
+      description: "Generate ContextStream AI rule files for your editor",
+      argsSchema: {
+        folder_path: external_exports.string().describe("Project folder path (ideally absolute)"),
+        editors: external_exports.string().optional().describe('Comma-separated editors or "all" (windsurf,cursor,cline,kilo,roo,claude,aider)'),
+        workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (optional)"),
+        workspace_name: external_exports.string().optional().describe("Workspace name (optional)"),
+        project_name: external_exports.string().optional().describe("Project name (optional)"),
+        additional_rules: external_exports.string().optional().describe("Additional project-specific rules (optional)"),
+        dry_run: external_exports.string().optional().describe('Dry run ("true" or "false", default: false)')
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Generate ContextStream editor rule files in: ${args.folder_path}
+
+Use \`generate_editor_rules\` with:
+- folder_path: "${args.folder_path}"
+${args.editors ? `- editors: "${args.editors}"` : ""}
+${args.workspace_id ? `- workspace_id: "${args.workspace_id}"` : ""}
+${args.workspace_name ? `- workspace_name: "${args.workspace_name}"` : ""}
+${args.project_name ? `- project_name: "${args.project_name}"` : ""}
+${args.additional_rules ? `- additional_rules: "${args.additional_rules}"` : ""}
+${args.dry_run ? `- dry_run: ${args.dry_run}` : ""}
+
+If editors is provided as a comma-separated string, split it into an array (or use ["all"] to generate for all editors). If dry_run is provided as a string, convert to boolean.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "index-local-repo",
+    {
+      title: "Index Local Repo",
+      description: "Ingest local files into ContextStream for indexing/search",
+      argsSchema: {
+        project_id: external_exports.string().uuid().optional().describe("Project ID (optional if session_init has set defaults)"),
+        path: external_exports.string().describe("Local directory path to ingest")
+      }
+    },
+    async (args) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Ingest local files for indexing/search.
+
+Path: ${args.path}
+
+If project_id is not provided, call \`session_init\` first and use the resolved project_id (or use \`projects_list\` to select).
+
+Use \`projects_ingest_local\` with:
+- project_id: ${args.project_id ? `"${args.project_id}"` : "(resolved from session_init)"}
+- path: "${args.path}"
+
+Then advise how to monitor progress via \`projects_index_status\`.`
+          }
+        }
+      ]
+    })
+  );
 }
 
 // src/session-manager.ts
@@ -8540,6 +9183,21 @@ var SessionManager = class {
         parts.push(`   \u2022 [${type}] ${title}`);
       });
     }
+    const lessonsWarning = typeof context.lessons_warning === "string" ? context.lessons_warning : void 0;
+    const lessons = Array.isArray(context.lessons) ? context.lessons : [];
+    if (lessonsWarning || lessons.length > 0) {
+      parts.push("");
+      parts.push("\u26A0\uFE0F  Lessons (review before changes):");
+      if (lessonsWarning) {
+        parts.push(`   ${lessonsWarning}`);
+      }
+      lessons.slice(0, 3).forEach((l) => {
+        const title = l.title || "Lesson";
+        const severity = l.severity || "unknown";
+        parts.push(`   \u2022 [${severity}] ${title}`);
+      });
+      parts.push('   Use session_get_lessons(query="...") for details.');
+    }
     parts.push("");
     if (context.ide_roots && context.ide_roots.length > 0) {
       const roots = context.ide_roots;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextstream/mcp-server",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "MCP server exposing ContextStream public API - code context, memory, search, and AI tools for developers",
   "type": "module",
   "license": "MIT",