@contextstream/mcp-server 0.3.8 → 0.3.10

package/dist/index.js

@@ -5276,118 +5276,700 @@ var ContextStreamClient = class {
     }
     return results;
   }
+  // ============================================
+  // Token-Saving Context Tools
+  // ============================================
+  /**
+   * Get a compact, token-efficient summary of workspace context.
+   * Designed to be included in every AI prompt without consuming many tokens.
+   *
+   * Target: ~500 tokens max
+   *
+   * This replaces loading full chat history - AI can call session_recall
+   * for specific details when needed.
+   */
+  async getContextSummary(params) {
+    const withDefaults = this.withDefaults(params);
+    const maxTokens = params.max_tokens || 500;
+    if (!withDefaults.workspace_id) {
+      return {
+        summary: "No workspace context loaded. Call session_init first.",
+        decision_count: 0,
+        memory_count: 0
+      };
+    }
+    const parts = [];
+    let workspaceName;
+    let projectName;
+    let decisionCount = 0;
+    let memoryCount = 0;
+    try {
+      const ws = await this.getWorkspace(withDefaults.workspace_id);
+      workspaceName = ws?.name;
+      if (workspaceName) {
+        parts.push(`\u{1F4C1} Workspace: ${workspaceName}`);
+      }
+    } catch {
+    }
+    if (withDefaults.project_id) {
+      try {
+        const proj = await this.getProject(withDefaults.project_id);
+        projectName = proj?.name;
+        if (projectName) {
+          parts.push(`\u{1F4C2} Project: ${projectName}`);
+        }
+      } catch {
+      }
+    }
+    try {
+      const decisions = await this.memoryDecisions({
+        workspace_id: withDefaults.workspace_id,
+        project_id: withDefaults.project_id,
+        limit: 5
+      });
+      if (decisions.items && decisions.items.length > 0) {
+        decisionCount = decisions.items.length;
+        parts.push("");
+        parts.push("\u{1F4CB} Recent Decisions:");
+        decisions.items.slice(0, 3).forEach((d, i) => {
+          parts.push(`  ${i + 1}. ${d.title || "Untitled"}`);
+        });
+        if (decisions.items.length > 3) {
+          parts.push(`  (+${decisions.items.length - 3} more)`);
+        }
+      }
+    } catch {
+    }
+    try {
+      const prefs = await this.memorySearch({
+        query: "user preferences coding style settings",
+        workspace_id: withDefaults.workspace_id,
+        limit: 5
+      });
+      if (prefs.results && prefs.results.length > 0) {
+        parts.push("");
+        parts.push("\u2699\uFE0F Preferences:");
+        prefs.results.slice(0, 3).forEach((p) => {
+          const title = p.title || "Preference";
+          parts.push(`  \u2022 ${title.slice(0, 60)}${title.length > 60 ? "..." : ""}`);
+        });
+      }
+    } catch {
+    }
+    try {
+      const summary2 = await this.memorySummary(withDefaults.workspace_id);
+      memoryCount = summary2.events || 0;
+      if (memoryCount > 0) {
+        parts.push("");
+        parts.push(`\u{1F9E0} Memory: ${memoryCount} events stored`);
+      }
+    } catch {
+    }
+    parts.push("");
+    parts.push('\u{1F4A1} Use session_recall("topic") for specific context');
+    const summary = parts.join("\n");
+    return {
+      summary,
+      workspace_name: workspaceName,
+      project_name: projectName,
+      decision_count: decisionCount,
+      memory_count: memoryCount
+    };
+  }
+  /**
+   * Compress chat history into structured memory events.
+   * This extracts key information and stores it, allowing the chat
+   * history to be cleared while preserving context.
+   *
+   * Use this at the end of a conversation or when context window is full.
+   */
+  async compressChat(params) {
+    const withDefaults = this.withDefaults(params);
+    if (!withDefaults.workspace_id) {
+      throw new Error("workspace_id is required for compressChat");
+    }
+    const extractTypes = params.extract_types || ["decisions", "preferences", "insights", "tasks", "code_patterns"];
+    const extracted = {
+      decisions: [],
+      preferences: [],
+      insights: [],
+      tasks: [],
+      code_patterns: []
+    };
+    let eventsCreated = 0;
+    const lines = params.chat_history.split("\n");
+    for (const line of lines) {
+      const lowerLine = line.toLowerCase();
+      if (extractTypes.includes("decisions")) {
+        if (lowerLine.includes("decided to") || lowerLine.includes("decision:") || lowerLine.includes("we'll use") || lowerLine.includes("going with") || lowerLine.includes("chose ")) {
+          extracted.decisions.push(line.trim());
+        }
+      }
+      if (extractTypes.includes("preferences")) {
+        if (lowerLine.includes("prefer") || lowerLine.includes("i like") || lowerLine.includes("always use") || lowerLine.includes("don't use") || lowerLine.includes("never use")) {
+          extracted.preferences.push(line.trim());
+        }
+      }
+      if (extractTypes.includes("tasks")) {
+        if (lowerLine.includes("todo:") || lowerLine.includes("task:") || lowerLine.includes("need to") || lowerLine.includes("should implement") || lowerLine.includes("will add")) {
+          extracted.tasks.push(line.trim());
+        }
+      }
+      if (extractTypes.includes("insights")) {
+        if (lowerLine.includes("learned that") || lowerLine.includes("realized") || lowerLine.includes("found out") || lowerLine.includes("discovered") || lowerLine.includes("important:") || lowerLine.includes("note:")) {
+          extracted.insights.push(line.trim());
+        }
+      }
+      if (extractTypes.includes("code_patterns")) {
+        if (lowerLine.includes("pattern:") || lowerLine.includes("convention:") || lowerLine.includes("style:") || lowerLine.includes("always format") || lowerLine.includes("naming convention")) {
+          extracted.code_patterns.push(line.trim());
+        }
+      }
+    }
+    for (const decision of extracted.decisions.slice(0, 5)) {
+      try {
+        await this.captureContext({
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          event_type: "decision",
+          title: decision.slice(0, 100),
+          content: decision,
+          importance: "medium"
+        });
+        eventsCreated++;
+      } catch {
+      }
+    }
+    for (const pref of extracted.preferences.slice(0, 5)) {
+      try {
+        await this.captureContext({
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          event_type: "preference",
+          title: pref.slice(0, 100),
+          content: pref,
+          importance: "medium"
+        });
+        eventsCreated++;
+      } catch {
+      }
+    }
+    for (const task of extracted.tasks.slice(0, 5)) {
+      try {
+        await this.captureContext({
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          event_type: "task",
+          title: task.slice(0, 100),
+          content: task,
+          importance: "medium"
+        });
+        eventsCreated++;
+      } catch {
+      }
+    }
+    for (const insight of extracted.insights.slice(0, 5)) {
+      try {
+        await this.captureContext({
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          event_type: "insight",
+          title: insight.slice(0, 100),
+          content: insight,
+          importance: "medium"
+        });
+        eventsCreated++;
+      } catch {
+      }
+    }
+    return {
+      events_created: eventsCreated,
+      extracted
+    };
+  }
+  /**
+   * Get context optimized for a token budget.
+   * Returns the most relevant context that fits within the specified token limit.
+   *
+   * This is the key tool for token-efficient AI interactions:
+   * - AI calls this with a query and token budget
+   * - Gets optimally selected context
+   * - No need to include full chat history
+   */
+  async getContextWithBudget(params) {
+    const withDefaults = this.withDefaults(params);
+    const maxTokens = params.max_tokens || 2e3;
+    const charsPerToken = 4;
+    const maxChars = maxTokens * charsPerToken;
+    const parts = [];
+    const sources = [];
+    let currentChars = 0;
+    if (params.include_decisions !== false && withDefaults.workspace_id) {
+      try {
+        const decisions = await this.memoryDecisions({
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          limit: 10
+        });
+        if (decisions.items) {
+          parts.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" });
+          }
+          parts.push("\n");
+        }
+      } catch {
+      }
+    }
+    if (params.include_memory !== false && withDefaults.workspace_id) {
+      try {
+        const memory = await this.memorySearch({
+          query: params.query,
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          limit: 5
+        });
+        if (memory.results) {
+          parts.push("## Related Context\n");
+          currentChars += 20;
+          for (const m of memory.results) {
+            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 });
+          }
+          parts.push("\n");
+        }
+      } catch {
+      }
+    }
+    if (params.include_code && withDefaults.project_id && currentChars < maxChars * 0.8) {
+      try {
+        const code = await this.searchSemantic({
+          query: params.query,
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          limit: 3
+        });
+        if (code.results) {
+          parts.push("## Relevant Code\n");
+          currentChars += 18;
+          for (const c of code.results) {
+            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 });
+          }
+        }
+      } catch {
+      }
+    }
+    const context = parts.join("");
+    const tokenEstimate = Math.ceil(context.length / charsPerToken);
+    return {
+      context,
+      token_estimate: tokenEstimate,
+      sources
+    };
+  }
+  /**
+   * Get incremental context changes since a given timestamp.
+   * Useful for syncing context without reloading everything.
+   */
+  async getContextDelta(params) {
+    const withDefaults = this.withDefaults(params);
+    if (!withDefaults.workspace_id) {
+      return { new_decisions: 0, new_memory: 0, items: [] };
+    }
+    const items = [];
+    let newDecisions = 0;
+    let newMemory = 0;
+    try {
+      const memory = await this.listMemoryEvents({
+        workspace_id: withDefaults.workspace_id,
+        project_id: withDefaults.project_id,
+        limit: params.limit || 20
+      });
+      if (memory.items) {
+        for (const item of memory.items) {
+          const createdAt = item.created_at || "";
+          if (createdAt > params.since) {
+            const type = item.metadata?.original_type || "memory";
+            items.push({
+              type,
+              title: item.title || "Untitled",
+              created_at: createdAt
+            });
+            if (type === "decision") newDecisions++;
+            else newMemory++;
+          }
+        }
+      }
+    } catch {
+    }
+    return {
+      new_decisions: newDecisions,
+      new_memory: newMemory,
+      items
+    };
+  }
+  /**
+   * Get smart context for a user query - CALL THIS BEFORE EVERY RESPONSE.
+   *
+   * This is the key tool for automatic context injection:
+   * 1. Analyzes the user's message to understand what context is needed
+   * 2. Retrieves relevant context in a minified, token-efficient format
+   * 3. Returns context that the AI can use without including chat history
+   *
+   * The format is optimized for AI consumption:
+   * - Compact notation (D: for Decision, P: for Preference, etc.)
+   * - No redundant whitespace
+   * - Structured for easy parsing
+   *
+   * Format options:
+   * - 'minified': Ultra-compact TYPE:value|TYPE:value|...
+   * - 'readable': Human-readable with line breaks
+   * - 'structured': JSON-like grouped format
+   */
+  async getSmartContext(params) {
+    const withDefaults = this.withDefaults(params);
+    const maxTokens = params.max_tokens || 800;
+    const format = params.format || "minified";
+    if (!withDefaults.workspace_id) {
+      return {
+        context: "[NO_WORKSPACE]",
+        token_estimate: 2,
+        format,
+        sources_used: 0
+      };
+    }
+    const message = params.user_message.toLowerCase();
+    const keywords = this.extractKeywords(message);
+    const items = [];
+    try {
+      const ws = await this.getWorkspace(withDefaults.workspace_id);
+      if (ws?.name) {
+        items.push({ type: "W", key: "workspace", value: ws.name, relevance: 1 });
+      }
+    } catch {
+    }
+    if (withDefaults.project_id) {
+      try {
+        const proj = await this.getProject(withDefaults.project_id);
+        if (proj?.name) {
+          items.push({ type: "P", key: "project", value: proj.name, relevance: 1 });
+        }
+      } catch {
+      }
+    }
+    try {
+      const decisions = await this.memoryDecisions({
+        workspace_id: withDefaults.workspace_id,
+        project_id: withDefaults.project_id,
+        limit: 10
+      });
+      if (decisions.items) {
+        for (const d of decisions.items) {
+          const title = d.title || "";
+          const content = d.content || "";
+          const relevance = this.calculateRelevance(keywords, title + " " + content);
+          items.push({
+            type: "D",
+            key: "decision",
+            value: title.slice(0, 80),
+            relevance
+          });
+        }
+      }
+    } catch {
+    }
+    if (keywords.length > 0) {
+      try {
+        const memory = await this.memorySearch({
+          query: params.user_message.slice(0, 200),
+          workspace_id: withDefaults.workspace_id,
+          project_id: withDefaults.project_id,
+          limit: 5
+        });
+        if (memory.results) {
+          for (const m of memory.results) {
+            const title = m.title || "";
+            const content = m.content || "";
+            items.push({
+              type: "M",
+              key: "memory",
+              value: title.slice(0, 80) + (content ? ": " + content.slice(0, 100) : ""),
+              relevance: 0.8
+              // Memory search already ranked by relevance
+            });
+          }
+        }
+      } catch {
+      }
+    }
+    items.sort((a, b) => b.relevance - a.relevance);
+    let context;
+    let charsUsed = 0;
+    const maxChars = maxTokens * 4;
+    if (format === "minified") {
+      const parts = [];
+      for (const item of items) {
+        const entry = `${item.type}:${item.value}`;
+        if (charsUsed + entry.length + 1 > maxChars) break;
+        parts.push(entry);
+        charsUsed += entry.length + 1;
+      }
+      context = parts.join("|");
+    } else if (format === "structured") {
+      const grouped = {};
+      for (const item of items) {
+        if (charsUsed > maxChars) break;
+        if (!grouped[item.type]) grouped[item.type] = [];
+        grouped[item.type].push(item.value);
+        charsUsed += item.value.length + 5;
+      }
+      context = JSON.stringify(grouped);
+    } else {
+      const lines = ["[CTX]"];
+      for (const item of items) {
+        const line = `${item.type}:${item.value}`;
+        if (charsUsed + line.length + 1 > maxChars) break;
+        lines.push(line);
+        charsUsed += line.length + 1;
+      }
+      lines.push("[/CTX]");
+      context = lines.join("\n");
+    }
+    return {
+      context,
+      token_estimate: Math.ceil(context.length / 4),
+      format,
+      sources_used: items.filter((i) => context.includes(i.value.slice(0, 20))).length
+    };
+  }
+  /**
+   * Extract keywords from a message for relevance matching
+   */
+  extractKeywords(message) {
+    const stopWords = /* @__PURE__ */ new Set([
+      "the",
+      "a",
+      "an",
+      "is",
+      "are",
+      "was",
+      "were",
+      "be",
+      "been",
+      "being",
+      "have",
+      "has",
+      "had",
+      "do",
+      "does",
+      "did",
+      "will",
+      "would",
+      "could",
+      "should",
+      "may",
+      "might",
+      "must",
+      "can",
+      "to",
+      "of",
+      "in",
+      "for",
+      "on",
+      "with",
+      "at",
+      "by",
+      "from",
+      "as",
+      "into",
+      "through",
+      "during",
+      "before",
+      "after",
+      "above",
+      "below",
+      "between",
+      "under",
+      "again",
+      "further",
+      "then",
+      "once",
+      "here",
+      "there",
+      "when",
+      "where",
+      "why",
+      "how",
+      "all",
+      "each",
+      "few",
+      "more",
+      "most",
+      "other",
+      "some",
+      "such",
+      "no",
+      "nor",
+      "not",
+      "only",
+      "own",
+      "same",
+      "so",
+      "than",
+      "too",
+      "very",
+      "just",
+      "and",
+      "but",
+      "if",
+      "or",
+      "because",
+      "until",
+      "while",
+      "this",
+      "that",
+      "these",
+      "those",
+      "what",
+      "which",
+      "who",
+      "whom",
+      "i",
+      "me",
+      "my",
+      "we",
+      "our",
+      "you",
+      "your",
+      "he",
+      "she",
+      "it",
+      "they",
+      "them"
+    ]);
+    return message.toLowerCase().replace(/[^\w\s]/g, " ").split(/\s+/).filter((word) => word.length > 2 && !stopWords.has(word));
+  }
+  /**
+   * Calculate relevance score based on keyword matches
+   */
+  calculateRelevance(keywords, text) {
+    if (keywords.length === 0) return 0.5;
+    const textLower = text.toLowerCase();
+    let matches = 0;
+    for (const keyword of keywords) {
+      if (textLower.includes(keyword)) {
+        matches++;
+      }
+    }
+    return matches / keywords.length;
+  }
 };
 
 // src/rules-templates.ts
 var CONTEXTSTREAM_RULES = `
 ## ContextStream Integration
 
-You have access to ContextStream MCP tools for persistent memory and context across sessions.
+You have access to ContextStream MCP tools for persistent memory and context.
 
----
-
-### \u{1F6A8} ESSENTIAL Tools (Always Use)
+## TL;DR - REQUIRED EVERY MESSAGE
 
-These tools should be called automatically in every conversation:
+| Message | What to Call |
+|---------|--------------|
+| **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 |
 
-| When | Tool | Example Prompt |
-|------|------|----------------|
-| **Conversation start** | \`session_init\` | "Load my workspace context" |
-| **User makes a decision** | \`session_capture\` | "Remember we decided to use PostgreSQL" |
-| **User states a preference** | \`session_capture\` | "Remember I prefer TypeScript strict mode" |
-| **Before starting work** | \`session_recall\` | "What did we decide about auth?" |
+**NO EXCEPTIONS.** Do not skip even if you think you have enough context.
 
 ---
 
-### \u{1F4DD} Memory & Context Tools (Use Frequently)
+### \u26A0\uFE0F Why context_smart is Required (Even After session_init)
 
-| Tool | Example Prompt |
-|------|----------------|
-| \`session_remember\` | "Remember that the API uses JWT tokens" |
-| \`session_smart_search\` | "Search for everything about payment processing" |
-| \`memory_search\` | "Search my notes for caching strategy" |
-| \`memory_decisions\` | "Show me all past decisions" |
-| \`memory_timeline\` | "Show me the timeline of this workspace" |
-| \`memory_summary\` | "Summarize what we've worked on" |
+**Common mistake:** "session_init already gave me context, I don't need context_smart"
 
----
+**This is WRONG. Here's why:**
+- \`session_init\` returns the last ~10 items **BY TIME** (chronological)
+- \`context_smart\` **SEARCHES** for items **RELEVANT to THIS message** (semantic)
 
-### \u{1F50D} Code Search Tools (Use When Exploring Code)
+**Example failure:**
+- User asks: "how should I implement authentication?"
+- Auth decisions were made 20 conversations ago
+- \u274C \`session_init\` won't have it (too old, not in recent 10)
+- \u2705 \`context_smart\` FINDS it via semantic search
 
-| Tool | Example Prompt |
-|------|----------------|
-| \`search_semantic\` | "How does authentication work in this codebase?" |
-| \`search_hybrid\` | "Find code related to user permissions" |
-| \`search_keyword\` | "Search for handleSubmit function" |
-| \`search_pattern\` | "Find all TODO comments" |
-| \`ai_context\` | "Build context for implementing user roles" |
-| \`ai_enhanced_context\` | "Give me deep context on the payment system" |
+**Without context_smart, you WILL miss relevant older context.**
 
 ---
 
-### \u{1F578}\uFE0F Code Analysis Tools (Use for Architecture)
-
-| Tool | Example Prompt |
-|------|----------------|
-| \`graph_dependencies\` | "What does UserService depend on?" |
-| \`graph_impact\` | "What would be affected if I change the User model?" |
-| \`graph_call_path\` | "How does login() eventually call the database?" |
-| \`graph_circular_dependencies\` | "Are there any circular dependencies?" |
-| \`graph_unused_code\` | "Find unused code in this project" |
-
----
+### When to Capture (MANDATORY)
 
-### \u{1F4C1} Project & Workspace Tools
+| When | Tool | Example |
+|------|------|---------|
+| User makes a decision | \`session_capture\` | "Let's use PostgreSQL" \u2192 capture as decision |
+| User states preference | \`session_capture\` | "I prefer TypeScript" \u2192 capture as preference |
+| You complete a task | \`session_capture\` | Capture what was done, decisions made |
+| Need past context | \`session_recall\` | "What did we decide about X?" |
 
-| Tool | Example Prompt |
-|------|----------------|
-| \`projects_overview\` | "Give me an overview of this project" |
-| \`projects_index\` | "Re-index this project" |
-| \`workspaces_overview\` | "Give me a workspace overview" |
-| \`workspace_associate\` | "Associate this folder with my workspace" |
-| \`generate_editor_rules\` | "Generate ContextStream rules for this project" |
+**You MUST capture after completing any significant task.** This ensures future sessions have context.
 
 ---
 
-### Automatic Behavior Guidelines
+### Behavior Rules
 
-**At conversation start:**
-- Call \`session_init\` to load context (this happens automatically on first tool call)
-- Review the loaded decisions and memory before responding
+**First message of conversation:**
+1. Call \`session_init(folder_path="<cwd>", context_hint="<user's message>")\`
+2. Then respond
 
-**During the conversation:**
-- When the user makes a decision \u2192 \`session_capture\` with \`event_type: "decision"\`
-- When you learn a user preference \u2192 \`session_capture\` with \`event_type: "preference"\`
-- When discovering important context \u2192 \`session_remember\`
-- When encountering a bug \u2192 \`session_capture\` with \`event_type: "bug"\`
-- When a feature is discussed \u2192 \`session_capture\` with \`event_type: "feature"\`
+**Every subsequent message:**
+1. Call \`context_smart(user_message="<user's message>")\` FIRST
+2. Then respond
 
-**When exploring code:**
-- Use \`search_semantic\` or \`search_hybrid\` for code search
-- Use \`graph_dependencies\` to understand architecture
-- Use \`graph_impact\` before making changes
+**After completing a task:**
+1. Call \`session_capture\` to save decisions, preferences, or insights
+2. This is NOT optional
 
-**At conversation end (if significant work done):**
-- Summarize and capture key decisions with \`session_capture\`
+**When user asks about past decisions:**
+- Use \`session_recall\` - do NOT ask user to repeat themselves
 
 ---
 
 ### Quick Examples
 
 \`\`\`
-# Start of conversation - load context
-session_init()
+# First message - user asks about auth
+session_init(folder_path="/path/to/project", context_hint="how should I implement auth?")
+# Returns workspace info + semantically relevant auth decisions from ANY time
 
-# User says "Let's use PostgreSQL for the database"
-session_capture(event_type="decision", title="Database Choice", content="Decided to use PostgreSQL...")
+# Second message - user asks about database
+context_smart(user_message="what database should I use?")
+# Returns: W:Maker|P:myproject|D:Use PostgreSQL|D:No ORMs|M:DB schema at...
 
-# User says "I prefer async/await over callbacks"  
-session_capture(event_type="preference", title="Async Style", content="User prefers async/await...")
+# User says "Let's use Redis for caching"
+session_capture(event_type="decision", title="Caching Choice", content="Using Redis for caching layer")
 
-# Need to find related code
-search_semantic(query="authentication middleware")
+# After completing implementation
+session_capture(event_type="decision", title="Auth Implementation Complete", content="Implemented JWT auth with refresh tokens...")
 
-# Check what we discussed before
+# Check past decisions
 session_recall(query="what did we decide about caching?")
 \`\`\`
 `.trim();
@@ -5411,6 +5993,20 @@ ${CONTEXTSTREAM_RULES}
     description: "Cline AI rules",
     content: `# Cline Rules
 ${CONTEXTSTREAM_RULES}
+`
+  },
+  kilo: {
+    filename: ".kilocode/rules/contextstream.md",
+    description: "Kilo Code AI rules",
+    content: `# Kilo Code Rules
+${CONTEXTSTREAM_RULES}
+`
+  },
+  roo: {
+    filename: ".roo/rules/contextstream.md",
+    description: "Roo Code AI rules",
+    content: `# Roo Code Rules
+${CONTEXTSTREAM_RULES}
 `
   },
   claude: {
@@ -5484,6 +6080,7 @@ function registerTools(server, client, sessionManager) {
           contextPrefix = autoInitResult.contextSummary + "\n\n";
         }
       }
+      sessionManager.warnIfContextSmartNotCalled(toolName);
       const result = await handler(input);
       if (contextPrefix && result && typeof result === "object") {
         const r = result;
@@ -6287,13 +6884,17 @@ Automatically detects code files and skips ignored directories like node_modules
 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.
 Automatically detects the IDE workspace/project path and can auto-index code.
-IMPORTANT: If you know the current workspace folder path, pass it as folder_path for accurate context resolution.`,
+
+IMPORTANT: Pass the user's FIRST MESSAGE as context_hint to get semantically relevant context!
+Example: session_init(folder_path="/path/to/project", context_hint="how do I implement auth?")
+
+This does semantic search on the first message. You only need context_smart on subsequent messages.`,
       inputSchema: external_exports.object({
         folder_path: external_exports.string().optional().describe("Current workspace/project folder path (absolute). Use this when IDE roots are not available."),
         workspace_id: external_exports.string().uuid().optional().describe("Workspace to initialize context for"),
         project_id: external_exports.string().uuid().optional().describe("Project to initialize context for"),
         session_id: external_exports.string().optional().describe("Custom session ID (auto-generated if not provided)"),
-        context_hint: external_exports.string().optional().describe("Hint about what the user wants to work on (used for context search)"),
+        context_hint: external_exports.string().optional().describe("RECOMMENDED: Pass the user's first message here for semantic search. This finds relevant context from ANY time, not just recent items."),
         include_recent_memory: external_exports.boolean().optional().describe("Include recent memory events (default: true)"),
         include_decisions: external_exports.boolean().optional().describe("Include recent decisions (default: true)"),
         auto_index: external_exports.boolean().optional().describe("Automatically create and index project from IDE workspace (default: true)")
@@ -6347,7 +6948,7 @@ Optionally generates AI editor rules for automatic ContextStream usage.`,
         workspace_id: external_exports.string().uuid().describe("Workspace ID to associate with"),
         workspace_name: external_exports.string().optional().describe("Workspace name for reference"),
         create_parent_mapping: external_exports.boolean().optional().describe("Also create a parent folder mapping (e.g., /dev/maker/* -> workspace)"),
-        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules (.windsurfrules, .cursorrules, etc.) for automatic ContextStream usage")
+        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules for Windsurf, Cursor, Cline, Kilo Code, Roo Code, Claude Code, and Aider")
       })
     },
     async (input) => {
@@ -6548,12 +7149,12 @@ Example: "What were the auth decisions?" or "What are my TypeScript preferences?
     "generate_editor_rules",
     {
       title: "Generate editor AI rules",
-      description: `Generate AI rule files for editors (Windsurf, Cursor, Cline, Claude Code, Aider).
+      description: `Generate AI rule files for editors (Windsurf, Cursor, Cline, Kilo Code, Roo Code, Claude Code, Aider).
 These rules instruct the AI to automatically use ContextStream for memory and context.
 Supported editors: ${getAvailableEditors().join(", ")}`,
       inputSchema: external_exports.object({
         folder_path: external_exports.string().describe("Absolute path to the project folder"),
-        editors: external_exports.array(external_exports.enum(["windsurf", "cursor", "cline", "claude", "aider", "all"])).optional().describe("Which editors to generate rules for. Defaults to all."),
+        editors: external_exports.array(external_exports.enum(["windsurf", "cursor", "cline", "kilo", "roo", "claude", "aider", "all"])).optional().describe("Which editors to generate rules for. Defaults to all."),
         workspace_name: external_exports.string().optional().describe("Workspace name to include in rules"),
         workspace_id: external_exports.string().uuid().optional().describe("Workspace ID to include in rules"),
         project_name: external_exports.string().optional().describe("Project name to include in rules"),
@@ -6617,6 +7218,274 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
       return { content: [{ type: "text", text: formatContent(summary) }], structuredContent: toStructured(summary) };
     }
   );
+  registerTool(
+    "session_summary",
+    {
+      title: "Get compact context summary",
+      description: `Get a compact, token-efficient summary of workspace context (~500 tokens).
+This is designed to replace loading full chat history in AI prompts.
+Returns: workspace/project info, top decisions (titles only), preferences, memory count.
+Use this at conversation start instead of loading everything.
+For specific details, use session_recall or session_smart_search.`,
+      inputSchema: external_exports.object({
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        max_tokens: external_exports.number().optional().describe("Maximum tokens for summary (default: 500)")
+      })
+    },
+    async (input) => {
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      const result = await client.getContextSummary({
+        workspace_id: workspaceId,
+        project_id: projectId,
+        max_tokens: input.max_tokens
+      });
+      return {
+        content: [{ type: "text", text: result.summary }],
+        structuredContent: toStructured(result)
+      };
+    }
+  );
+  registerTool(
+    "session_compress",
+    {
+      title: "Compress chat history to memory",
+      description: `Extract and store key information from chat history as memory events.
+This allows clearing chat history while preserving important context.
+Use at conversation end or when context window is getting full.
+
+Extracts:
+- Decisions made
+- User preferences learned
+- Insights discovered
+- Tasks/action items
+- Code patterns established
+
+After compression, the AI can use session_recall to retrieve this context in future conversations.`,
+      inputSchema: external_exports.object({
+        chat_history: external_exports.string().describe("The chat history to compress and extract from"),
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        extract_types: external_exports.array(external_exports.enum(["decisions", "preferences", "insights", "tasks", "code_patterns"])).optional().describe("Types of information to extract (default: all)")
+      })
+    },
+    async (input) => {
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      if (!workspaceId) {
+        return {
+          content: [{
+            type: "text",
+            text: "Error: workspace_id is required. Please call session_init first or provide workspace_id explicitly."
+          }],
+          isError: true
+        };
+      }
+      const result = await client.compressChat({
+        workspace_id: workspaceId,
+        project_id: projectId,
+        chat_history: input.chat_history,
+        extract_types: input.extract_types
+      });
+      const summary = [
+        `\u2705 Compressed chat history into ${result.events_created} memory events:`,
+        "",
+        `\u{1F4CB} Decisions: ${result.extracted.decisions.length}`,
+        `\u2699\uFE0F Preferences: ${result.extracted.preferences.length}`,
+        `\u{1F4A1} Insights: ${result.extracted.insights.length}`,
+        `\u{1F4DD} Tasks: ${result.extracted.tasks.length}`,
+        `\u{1F527} Code patterns: ${result.extracted.code_patterns.length}`,
+        "",
+        "These are now stored in ContextStream memory.",
+        "Future conversations can access them via session_recall."
+      ].join("\n");
+      return {
+        content: [{ type: "text", text: summary }],
+        structuredContent: toStructured(result)
+      };
+    }
+  );
+  registerTool(
+    "ai_context_budget",
+    {
+      title: "Get context within token budget",
+      description: `Get the most relevant context that fits within a specified token budget.
+This is the key tool for token-efficient AI interactions:
+
+1. AI calls this with a query and token budget
+2. Gets optimally selected context (decisions, memory, code)
+3. No need to include full chat history in the prompt
+
+The tool prioritizes:
+1. Relevant decisions (highest value per token)
+2. Query-matched memory events
+3. Related code snippets (if requested and budget allows)
+
+Example: ai_context_budget(query="authentication", max_tokens=1000)`,
+      inputSchema: external_exports.object({
+        query: external_exports.string().describe("What context to retrieve"),
+        max_tokens: external_exports.number().describe("Maximum tokens for the context (e.g., 500, 1000, 2000)"),
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        include_decisions: external_exports.boolean().optional().describe("Include relevant decisions (default: true)"),
+        include_memory: external_exports.boolean().optional().describe("Include memory search results (default: true)"),
+        include_code: external_exports.boolean().optional().describe("Include code search results (default: false)")
+      })
+    },
+    async (input) => {
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      const result = await client.getContextWithBudget({
+        query: input.query,
+        workspace_id: workspaceId,
+        project_id: projectId,
+        max_tokens: input.max_tokens,
+        include_decisions: input.include_decisions,
+        include_memory: input.include_memory,
+        include_code: input.include_code
+      });
+      const footer = `
+---
+\u{1F4CA} Token estimate: ${result.token_estimate}/${input.max_tokens} | Sources: ${result.sources.length}`;
+      return {
+        content: [{ type: "text", text: result.context + footer }],
+        structuredContent: toStructured(result)
+      };
+    }
+  );
+  registerTool(
+    "session_delta",
+    {
+      title: "Get context changes since timestamp",
+      description: `Get new context added since a specific timestamp.
+Useful for efficient context synchronization without reloading everything.
+
+Returns:
+- Count of new decisions and memory events
+- List of new items with titles and timestamps
+
+Use case: AI can track what's new since last session_init.`,
+      inputSchema: external_exports.object({
+        since: external_exports.string().describe('ISO timestamp to get changes since (e.g., "2025-12-05T00:00:00Z")'),
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        limit: external_exports.number().optional().describe("Maximum items to return (default: 20)")
+      })
+    },
+    async (input) => {
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      const result = await client.getContextDelta({
+        workspace_id: workspaceId,
+        project_id: projectId,
+        since: input.since,
+        limit: input.limit
+      });
+      const summary = [
+        `\u{1F4C8} Context changes since ${input.since}:`,
+        `   New decisions: ${result.new_decisions}`,
+        `   New memory events: ${result.new_memory}`,
+        "",
+        ...result.items.slice(0, 10).map((i) => `\u2022 [${i.type}] ${i.title}`),
+        result.items.length > 10 ? `   (+${result.items.length - 10} more)` : ""
+      ].filter(Boolean).join("\n");
+      return {
+        content: [{ type: "text", text: summary }],
+        structuredContent: toStructured(result)
+      };
+    }
+  );
+  registerTool(
+    "context_smart",
+    {
+      title: "Get smart context for user query",
+      description: `**CALL THIS BEFORE EVERY AI RESPONSE** to get relevant context.
+
+This is the KEY tool for token-efficient AI interactions. It:
+1. Analyzes the user's message to understand what context is needed
+2. Retrieves only relevant context in a minified, token-efficient format
+3. Replaces the need to include full chat history in prompts
+
+Format options:
+- 'minified': Ultra-compact D:decision|P:preference|M:memory (default, ~200 tokens)
+- 'readable': Line-separated with labels
+- 'structured': JSON-like grouped format
+
+Type codes: W=Workspace, P=Project, D=Decision, M=Memory, I=Insight, T=Task
+
+Example usage:
+1. User asks "how should I implement auth?"
+2. AI calls context_smart(user_message="how should I implement auth?")
+3. Gets: "W:Maker|P:contextstream|D:Use JWT for auth|D:No session cookies|M:Auth API at /auth/..."
+4. AI responds with relevant context already loaded
+
+This saves ~80% tokens compared to including full chat history.`,
+      inputSchema: external_exports.object({
+        user_message: external_exports.string().describe("The user message to analyze and get context for"),
+        workspace_id: external_exports.string().uuid().optional(),
+        project_id: external_exports.string().uuid().optional(),
+        max_tokens: external_exports.number().optional().describe("Maximum tokens for context (default: 800)"),
+        format: external_exports.enum(["minified", "readable", "structured"]).optional().describe("Context format (default: minified)")
+      })
+    },
+    async (input) => {
+      if (sessionManager) {
+        sessionManager.markContextSmartCalled();
+      }
+      let workspaceId = input.workspace_id;
+      let projectId = input.project_id;
+      if (!workspaceId && sessionManager) {
+        const ctx = sessionManager.getContext();
+        if (ctx) {
+          workspaceId = ctx.workspace_id;
+          projectId = projectId || ctx.project_id;
+        }
+      }
+      const result = await client.getSmartContext({
+        user_message: input.user_message,
+        workspace_id: workspaceId,
+        project_id: projectId,
+        max_tokens: input.max_tokens,
+        format: input.format
+      });
+      const footer = `
+---
+\u{1F3AF} ${result.sources_used} sources | ~${result.token_estimate} tokens | format: ${result.format}`;
+      return {
+        content: [{ type: "text", text: result.context + footer }],
+        structuredContent: toStructured(result)
+      };
+    }
+  );
 }
 
 // src/resources.ts
@@ -6963,6 +7832,8 @@ var SessionManager = class {
     this.context = null;
     this.ideRoots = [];
     this.folderPath = null;
+    this.contextSmartCalled = false;
+    this.warningShown = false;
   }
   /**
    * Check if session has been auto-initialized
@@ -6989,6 +7860,30 @@ var SessionManager = class {
   setFolderPath(path3) {
     this.folderPath = path3;
   }
+  /**
+   * Mark that context_smart has been called in this session
+   */
+  markContextSmartCalled() {
+    this.contextSmartCalled = true;
+  }
+  /**
+   * Check if context_smart has been called and warn if not.
+   * Returns true if a warning was shown, false otherwise.
+   */
+  warnIfContextSmartNotCalled(toolName) {
+    const skipWarningTools = ["session_init", "context_smart", "session_recall", "session_remember"];
+    if (skipWarningTools.includes(toolName)) {
+      return false;
+    }
+    if (!this.initialized || this.contextSmartCalled || this.warningShown) {
+      return false;
+    }
+    this.warningShown = true;
+    console.warn(`[ContextStream] Warning: ${toolName} called without context_smart.`);
+    console.warn('[ContextStream] For best results, call context_smart(user_message="...") before other tools.');
+    console.warn("[ContextStream] context_smart provides semantically relevant context for the user's query.");
+    return true;
+  }
   /**
    * Auto-initialize the session if not already done.
    * Returns context summary to prepend to tool response.

package/package.json

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