kiro-memory 1.6.0 → 1.7.1

package/plugin/dist/servers/mcp-server.js

@@ -41,7 +41,7 @@ var TOOLS = [
       properties: {
         query: { type: "string", description: "Text to search in observations and summaries" },
         project: { type: "string", description: "Filter by project name (optional)" },
-        type: { type: "string", description: "Filter by observation type: file-write, command, research, tool-use (optional)" },
+        type: { type: "string", description: "Filter by observation type: file-write, command, research, tool-use, constraint, decision, heuristic, rejected (optional)" },
         limit: { type: "number", description: "Max number of results (default: 20)" }
       },
       required: ["query"]
@@ -85,6 +85,77 @@ var TOOLS = [
       },
       required: ["project"]
     }
+  },
+  {
+    name: "semantic_search",
+    description: 'Semantic search using vector embeddings. Finds observations by meaning, not just keywords. E.g. searching "authentication fix" also finds "OAuth token refresh". Falls back to keyword search if embeddings are unavailable.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural language query for semantic search" },
+        project: { type: "string", description: "Filter by project name (optional)" },
+        limit: { type: "number", description: "Max number of results (default: 10)" }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "embedding_stats",
+    description: "Show embedding statistics: total observations, how many have embeddings, embedding provider info.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: "store_knowledge",
+    description: 'Store structured knowledge: constraints (rules), decisions (architectural choices), heuristics (soft preferences), or rejected solutions. This knowledge is boosted in search rankings and helps remember the "why" behind code decisions.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        knowledge_type: {
+          type: "string",
+          enum: ["constraint", "decision", "heuristic", "rejected"],
+          description: "Type of knowledge: constraint (hard/soft rules), decision (architectural choices with alternatives), heuristic (soft preferences), rejected (discarded solutions with reason)"
+        },
+        title: { type: "string", description: "Short descriptive title for the knowledge entry" },
+        content: { type: "string", description: "Detailed content explaining the knowledge" },
+        project: { type: "string", description: "Project name (required)" },
+        severity: { type: "string", enum: ["hard", "soft"], description: "For constraints: hard (must never violate) or soft (prefer to follow)" },
+        alternatives: { type: "array", items: { type: "string" }, description: "For decisions/rejected: alternative options considered" },
+        reason: { type: "string", description: "For decisions/rejected: why this choice was made or rejected" },
+        context: { type: "string", description: "For heuristics: when this preference applies" },
+        confidence: { type: "string", enum: ["high", "medium", "low"], description: "For heuristics: confidence level" },
+        concepts: { type: "array", items: { type: "string" }, description: "Related concepts/tags (optional)" },
+        files: { type: "array", items: { type: "string" }, description: "Related files (optional)" }
+      },
+      required: ["knowledge_type", "title", "content", "project"]
+    }
+  },
+  {
+    name: "resume_session",
+    description: "Resume a previous coding session. Returns the checkpoint with task, progress, next steps, and relevant files from the last session on this project. Use when starting a new session to continue previous work.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project name (optional, uses auto-detected project from environment)" },
+        session_id: { type: "number", description: "Specific session ID to resume (optional, uses latest checkpoint for the project)" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "generate_report",
+    description: "Generate an activity report for a project. Returns a markdown summary with observations, sessions, learnings, completed tasks, and file hotspots for the specified time period.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project name (optional, uses auto-detected project)" },
+        period: { type: "string", description: 'Time period: "weekly" (default) or "monthly"' }
+      },
+      required: []
+    }
   }
 ];
 var handlers = {
@@ -215,6 +286,135 @@ var handlers = {
       });
     }
     return output;
+  },
+  async semantic_search(args) {
+    const result = await callWorkerGET("/api/hybrid-search", {
+      q: args.query,
+      project: args.project || "",
+      limit: String(args.limit || 10)
+    });
+    const hits = result.results || [];
+    if (hits.length === 0) {
+      return "No semantic results found for the query.";
+    }
+    let output = `## Semantic Search: "${args.query}"
+
+`;
+    output += `Found ${hits.length} results:
+
+`;
+    hits.forEach((h) => {
+      const scorePercent = Math.round((h.score || 0) * 100);
+      const source = h.source || "unknown";
+      output += `- **#${h.id}** [${h.type}] ${h.title} (score: ${scorePercent}%, source: ${source})
+`;
+      if (h.content) output += `  ${h.content.substring(0, 150)}
+`;
+      output += "\n";
+    });
+    return output;
+  },
+  async embedding_stats() {
+    const result = await callWorkerGET("/api/embeddings/stats");
+    let output = `## Embedding Statistics
+
+`;
+    output += `- **Total observations**: ${result.total}
+`;
+    output += `- **With embeddings**: ${result.embedded}
+`;
+    output += `- **Coverage**: ${result.percentage}%
+`;
+    output += `- **Provider**: ${result.provider || "none"}
+`;
+    output += `- **Dimensions**: ${result.dimensions}
+`;
+    output += `- **Available**: ${result.available ? "yes" : "no"}
+`;
+    if (result.percentage < 100 && result.total > 0) {
+      output += `
+_Tip: Run \`kiro-memory embeddings backfill\` to generate missing embeddings._
+`;
+    }
+    return output;
+  },
+  async store_knowledge(args) {
+    const result = await callWorkerPOST("/api/knowledge", args);
+    return `Knowledge stored successfully.
+- **ID**: ${result.id}
+- **Type**: ${result.knowledge_type}
+- **Title**: ${args.title}`;
+  },
+  async resume_session(args) {
+    let checkpoint;
+    if (args.session_id) {
+      checkpoint = await callWorkerGET(`/api/sessions/${args.session_id}/checkpoint`);
+    } else {
+      const project = args.project || process.env.KIRO_MEMORY_PROJECT || "";
+      if (!project) {
+        return "No project specified and unable to auto-detect. Provide a project name or session_id.";
+      }
+      checkpoint = await callWorkerGET("/api/checkpoint", { project });
+    }
+    if (!checkpoint || checkpoint.error) {
+      return "No checkpoint found. There is no previous session to resume for this project.";
+    }
+    const parts = [
+      `## Session Checkpoint \u2014 ${checkpoint.project}`,
+      `**Task**: ${checkpoint.task}`
+    ];
+    if (checkpoint.progress) parts.push(`**Progress**: ${checkpoint.progress}`);
+    if (checkpoint.next_steps) parts.push(`**Next Steps**: ${checkpoint.next_steps}`);
+    if (checkpoint.open_questions) parts.push(`**Open Questions**: ${checkpoint.open_questions}`);
+    if (checkpoint.relevant_files) parts.push(`**Relevant Files**: ${checkpoint.relevant_files}`);
+    if (checkpoint.created_at) parts.push(`
+_Checkpoint created: ${checkpoint.created_at}_`);
+    return parts.join("\n");
+  },
+  async generate_report(args) {
+    const project = args.project || process.env.KIRO_MEMORY_PROJECT || "";
+    const period = args.period === "monthly" ? "monthly" : "weekly";
+    const params = { period, format: "markdown" };
+    if (project) params.project = project;
+    const result = await callWorkerGET("/api/report", params);
+    if (typeof result === "string") return result;
+    if (result?.error) return `Report generation failed: ${result.error}`;
+    const d = result;
+    const parts = [
+      `# Activity Report \u2014 ${d.period?.label || period}`,
+      `**Period**: ${d.period?.start} \u2192 ${d.period?.end} (${d.period?.days} days)`,
+      "",
+      "## Overview",
+      `- Observations: ${d.overview?.observations || 0}`,
+      `- Summaries: ${d.overview?.summaries || 0}`,
+      `- Sessions: ${d.overview?.sessions || 0}`,
+      `- Knowledge items: ${d.overview?.knowledgeCount || 0}`
+    ];
+    if (d.sessionStats?.total > 0) {
+      const pct = Math.round(d.sessionStats.completed / d.sessionStats.total * 100);
+      parts.push("", "## Sessions");
+      parts.push(`- Total: ${d.sessionStats.total} | Completed: ${d.sessionStats.completed} (${pct}%)`);
+      if (d.sessionStats.avgDurationMinutes > 0) {
+        parts.push(`- Avg duration: ${d.sessionStats.avgDurationMinutes} min`);
+      }
+    }
+    if (d.topLearnings?.length > 0) {
+      parts.push("", "## Key Learnings");
+      d.topLearnings.forEach((l) => parts.push(`- ${l}`));
+    }
+    if (d.completedTasks?.length > 0) {
+      parts.push("", "## Completed");
+      d.completedTasks.forEach((t) => parts.push(`- ${t}`));
+    }
+    if (d.nextSteps?.length > 0) {
+      parts.push("", "## Next Steps");
+      d.nextSteps.forEach((s) => parts.push(`- ${s}`));
+    }
+    if (d.fileHotspots?.length > 0) {
+      parts.push("", "## File Hotspots");
+      d.fileHotspots.slice(0, 10).forEach((f) => parts.push(`- \`${f.file}\` (${f.count}x)`));
+    }
+    return parts.join("\n");
   }
 };
 async function main() {
@@ -251,8 +451,9 @@ Start the worker with: cd <kiro-memory-dir> && npm run worker:start`
           isError: true
         };
       }
+      const safeMsg = msg.includes("Worker") ? "Worker communication error" : "Internal error processing request";
       return {
-        content: [{ type: "text", text: `Error: ${msg}` }],
+        content: [{ type: "text", text: `Error: ${safeMsg}` }],
         isError: true
       };
     }

package/plugin/dist/services/search/EmbeddingService.js

@@ -0,0 +1,363 @@
+import { createRequire } from 'module';const require = createRequire(import.meta.url);
+
+// src/utils/logger.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  LogLevel2[LogLevel2["SILENT"] = 4] = "SILENT";
+  return LogLevel2;
+})(LogLevel || {});
+var DEFAULT_DATA_DIR = join(homedir(), ".contextkit");
+var Logger = class {
+  level = null;
+  useColor;
+  logFilePath = null;
+  logFileInitialized = false;
+  constructor() {
+    this.useColor = process.stdout.isTTY ?? false;
+  }
+  /**
+   * Initialize log file path and ensure directory exists (lazy initialization)
+   */
+  ensureLogFileInitialized() {
+    if (this.logFileInitialized) return;
+    this.logFileInitialized = true;
+    try {
+      const logsDir = join(DEFAULT_DATA_DIR, "logs");
+      if (!existsSync(logsDir)) {
+        mkdirSync(logsDir, { recursive: true });
+      }
+      const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+      this.logFilePath = join(logsDir, `kiro-memory-${date}.log`);
+    } catch (error) {
+      console.error("[LOGGER] Failed to initialize log file:", error);
+      this.logFilePath = null;
+    }
+  }
+  /**
+   * Lazy-load log level from settings file
+   */
+  getLevel() {
+    if (this.level === null) {
+      try {
+        const settingsPath = join(DEFAULT_DATA_DIR, "settings.json");
+        if (existsSync(settingsPath)) {
+          const settingsData = readFileSync(settingsPath, "utf-8");
+          const settings = JSON.parse(settingsData);
+          const envLevel = (settings.KIRO_MEMORY_LOG_LEVEL || settings.CONTEXTKIT_LOG_LEVEL || "INFO").toUpperCase();
+          this.level = LogLevel[envLevel] ?? 1 /* INFO */;
+        } else {
+          this.level = 1 /* INFO */;
+        }
+      } catch (error) {
+        this.level = 1 /* INFO */;
+      }
+    }
+    return this.level;
+  }
+  /**
+   * Create correlation ID for tracking an observation through the pipeline
+   */
+  correlationId(sessionId, observationNum) {
+    return `obs-${sessionId}-${observationNum}`;
+  }
+  /**
+   * Create session correlation ID
+   */
+  sessionId(sessionId) {
+    return `session-${sessionId}`;
+  }
+  /**
+   * Format data for logging - create compact summaries instead of full dumps
+   */
+  formatData(data) {
+    if (data === null || data === void 0) return "";
+    if (typeof data === "string") return data;
+    if (typeof data === "number") return data.toString();
+    if (typeof data === "boolean") return data.toString();
+    if (typeof data === "object") {
+      if (data instanceof Error) {
+        return this.getLevel() === 0 /* DEBUG */ ? `${data.message}
+${data.stack}` : data.message;
+      }
+      if (Array.isArray(data)) {
+        return `[${data.length} items]`;
+      }
+      const keys = Object.keys(data);
+      if (keys.length === 0) return "{}";
+      if (keys.length <= 3) {
+        return JSON.stringify(data);
+      }
+      return `{${keys.length} keys: ${keys.slice(0, 3).join(", ")}...}`;
+    }
+    return String(data);
+  }
+  /**
+   * Format timestamp in local timezone (YYYY-MM-DD HH:MM:SS.mmm)
+   */
+  formatTimestamp(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    const hours = String(date.getHours()).padStart(2, "0");
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    const seconds = String(date.getSeconds()).padStart(2, "0");
+    const ms = String(date.getMilliseconds()).padStart(3, "0");
+    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${ms}`;
+  }
+  /**
+   * Core logging method
+   */
+  log(level, component, message, context, data) {
+    if (level < this.getLevel()) return;
+    this.ensureLogFileInitialized();
+    const timestamp = this.formatTimestamp(/* @__PURE__ */ new Date());
+    const levelStr = LogLevel[level].padEnd(5);
+    const componentStr = component.padEnd(6);
+    let correlationStr = "";
+    if (context?.correlationId) {
+      correlationStr = `[${context.correlationId}] `;
+    } else if (context?.sessionId) {
+      correlationStr = `[session-${context.sessionId}] `;
+    }
+    let dataStr = "";
+    if (data !== void 0 && data !== null) {
+      if (data instanceof Error) {
+        dataStr = this.getLevel() === 0 /* DEBUG */ ? `
+${data.message}
+${data.stack}` : ` ${data.message}`;
+      } else if (this.getLevel() === 0 /* DEBUG */ && typeof data === "object") {
+        dataStr = "\n" + JSON.stringify(data, null, 2);
+      } else {
+        dataStr = " " + this.formatData(data);
+      }
+    }
+    let contextStr = "";
+    if (context) {
+      const { sessionId, memorySessionId, correlationId, ...rest } = context;
+      if (Object.keys(rest).length > 0) {
+        const pairs = Object.entries(rest).map(([k, v]) => `${k}=${v}`);
+        contextStr = ` {${pairs.join(", ")}}`;
+      }
+    }
+    const logLine = `[${timestamp}] [${levelStr}] [${componentStr}] ${correlationStr}${message}${contextStr}${dataStr}`;
+    if (this.logFilePath) {
+      try {
+        appendFileSync(this.logFilePath, logLine + "\n", "utf8");
+      } catch (error) {
+        process.stderr.write(`[LOGGER] Failed to write to log file: ${error}
+`);
+      }
+    } else {
+      process.stderr.write(logLine + "\n");
+    }
+  }
+  // Public logging methods
+  debug(component, message, context, data) {
+    this.log(0 /* DEBUG */, component, message, context, data);
+  }
+  info(component, message, context, data) {
+    this.log(1 /* INFO */, component, message, context, data);
+  }
+  warn(component, message, context, data) {
+    this.log(2 /* WARN */, component, message, context, data);
+  }
+  error(component, message, context, data) {
+    this.log(3 /* ERROR */, component, message, context, data);
+  }
+  /**
+   * Log data flow: input → processing
+   */
+  dataIn(component, message, context, data) {
+    this.info(component, `\u2192 ${message}`, context, data);
+  }
+  /**
+   * Log data flow: processing → output
+   */
+  dataOut(component, message, context, data) {
+    this.info(component, `\u2190 ${message}`, context, data);
+  }
+  /**
+   * Log successful completion
+   */
+  success(component, message, context, data) {
+    this.info(component, `\u2713 ${message}`, context, data);
+  }
+  /**
+   * Log failure
+   */
+  failure(component, message, context, data) {
+    this.error(component, `\u2717 ${message}`, context, data);
+  }
+  /**
+   * Log timing information
+   */
+  timing(component, message, durationMs, context) {
+    this.info(component, `\u23F1 ${message}`, context, { duration: `${durationMs}ms` });
+  }
+  /**
+   * Happy Path Error - logs when the expected "happy path" fails but we have a fallback
+   */
+  happyPathError(component, message, context, data, fallback = "") {
+    const stack = new Error().stack || "";
+    const stackLines = stack.split("\n");
+    const callerLine = stackLines[2] || "";
+    const callerMatch = callerLine.match(/at\s+(?:.*\s+)?\(?([^:]+):(\d+):(\d+)\)?/);
+    const location = callerMatch ? `${callerMatch[1].split("/").pop()}:${callerMatch[2]}` : "unknown";
+    const enhancedContext = {
+      ...context,
+      location
+    };
+    this.warn(component, `[HAPPY-PATH] ${message}`, enhancedContext, data);
+    return fallback;
+  }
+};
+var logger = new Logger();
+
+// src/services/search/EmbeddingService.ts
+var EmbeddingService = class {
+  provider = null;
+  model = null;
+  initialized = false;
+  initializing = null;
+  /**
+   * Inizializza il servizio di embedding.
+   * Tenta fastembed, poi @huggingface/transformers, poi fallback a null.
+   */
+  async initialize() {
+    if (this.initialized) return this.provider !== null;
+    if (this.initializing) return this.initializing;
+    this.initializing = this._doInitialize();
+    const result = await this.initializing;
+    this.initializing = null;
+    return result;
+  }
+  async _doInitialize() {
+    try {
+      const fastembed = await import("fastembed");
+      const EmbeddingModel = fastembed.EmbeddingModel || fastembed.default?.EmbeddingModel;
+      const FlagEmbedding = fastembed.FlagEmbedding || fastembed.default?.FlagEmbedding;
+      if (FlagEmbedding && EmbeddingModel) {
+        this.model = await FlagEmbedding.init({
+          model: EmbeddingModel.BGESmallENV15
+        });
+        this.provider = "fastembed";
+        this.initialized = true;
+        logger.info("EMBEDDING", "Inizializzato con fastembed (BGE-small-en-v1.5)");
+        return true;
+      }
+    } catch (error) {
+      logger.debug("EMBEDDING", `fastembed non disponibile: ${error}`);
+    }
+    try {
+      const transformers = await import("@huggingface/transformers");
+      const pipeline = transformers.pipeline || transformers.default?.pipeline;
+      if (pipeline) {
+        this.model = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2", {
+          quantized: true
+        });
+        this.provider = "transformers";
+        this.initialized = true;
+        logger.info("EMBEDDING", "Inizializzato con @huggingface/transformers (all-MiniLM-L6-v2)");
+        return true;
+      }
+    } catch (error) {
+      logger.debug("EMBEDDING", `@huggingface/transformers non disponibile: ${error}`);
+    }
+    this.provider = null;
+    this.initialized = true;
+    logger.warn("EMBEDDING", "Nessun provider embedding disponibile, ricerca semantica disabilitata");
+    return false;
+  }
+  /**
+   * Genera embedding per un singolo testo.
+   * Ritorna Float32Array con 384 dimensioni, o null se non disponibile.
+   */
+  async embed(text) {
+    if (!this.initialized) await this.initialize();
+    if (!this.provider || !this.model) return null;
+    try {
+      const truncated = text.substring(0, 2e3);
+      if (this.provider === "fastembed") {
+        return await this._embedFastembed(truncated);
+      } else if (this.provider === "transformers") {
+        return await this._embedTransformers(truncated);
+      }
+    } catch (error) {
+      logger.error("EMBEDDING", `Errore generazione embedding: ${error}`);
+    }
+    return null;
+  }
+  /**
+   * Genera embeddings in batch.
+   */
+  async embedBatch(texts) {
+    if (!this.initialized) await this.initialize();
+    if (!this.provider || !this.model) return texts.map(() => null);
+    const results = [];
+    for (const text of texts) {
+      try {
+        const embedding = await this.embed(text);
+        results.push(embedding);
+      } catch {
+        results.push(null);
+      }
+    }
+    return results;
+  }
+  /**
+   * Verifica se il servizio è disponibile.
+   */
+  isAvailable() {
+    return this.initialized && this.provider !== null;
+  }
+  /**
+   * Nome del provider attivo.
+   */
+  getProvider() {
+    return this.provider;
+  }
+  /**
+   * Dimensioni del vettore embedding.
+   */
+  getDimensions() {
+    return 384;
+  }
+  // --- Provider specifici ---
+  async _embedFastembed(text) {
+    const embeddings = this.model.embed([text], 1);
+    for await (const batch of embeddings) {
+      if (batch && batch.length > 0) {
+        const vec = batch[0];
+        return vec instanceof Float32Array ? vec : new Float32Array(vec);
+      }
+    }
+    return null;
+  }
+  async _embedTransformers(text) {
+    const output = await this.model(text, {
+      pooling: "mean",
+      normalize: true
+    });
+    if (output?.data) {
+      return output.data instanceof Float32Array ? output.data : new Float32Array(output.data);
+    }
+    return null;
+  }
+};
+var embeddingService = null;
+function getEmbeddingService() {
+  if (!embeddingService) {
+    embeddingService = new EmbeddingService();
+  }
+  return embeddingService;
+}
+export {
+  EmbeddingService,
+  getEmbeddingService
+};