kiro-memory 1.7.0 → 1.8.0

package/README.md

@@ -11,12 +11,16 @@
   <a href="https://www.npmjs.com/package/kiro-memory"><img src="https://img.shields.io/npm/v/kiro-memory" alt="npm" /></a>
   <img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License" />
   <img src="https://img.shields.io/badge/node-%3E%3D18-green" alt="Node" />
+  <a href="https://auritidesign.it/docs/kiro-memory/"><img src="https://img.shields.io/badge/docs-auritidesign.it-00b4d8" alt="Docs" /></a>
 </p>
 
 ---
 
 Kiro Memory gives your AI coding assistant memory that persists across sessions. It automatically captures what happened -- files changed, tools used, decisions made -- and feeds relevant context back at the start of the next session. No manual bookkeeping. Your agent picks up exactly where it left off.
 
+
+**[Read the full documentation →](https://auritidesign.it/docs/kiro-memory/)**
+
 Works with **Claude Code** (hooks), **Cursor** (rules + MCP), **Windsurf** (rules + MCP), **Cline** (custom instructions + MCP), and any editor that supports the **Model Context Protocol**.
 
 ## What Your Agent Sees
@@ -52,10 +56,13 @@ When a new session starts, Kiro Memory automatically injects previous session co
 - **Session Checkpoint & Resume** -- Checkpoint sessions and resume from where you left off
 - **Activity Reports** -- Weekly/monthly digests in text, Markdown, or JSON format
 - **Analytics Dashboard** -- Activity timeline, type distribution, session stats, and file hotspots
-- **Session Summaries** -- Structured summaries generated when sessions end
-- **Web Dashboard** -- Real-time viewer at `http://localhost:3001` with dark/light theme, search, project filters, and live updates via SSE
-- **MCP Server** -- 10 tools exposed via Model Context Protocol
-- **Full-Text Search** -- SQLite FTS5 for fast, typo-tolerant search across all stored context
+- **Session Tracking** -- Sessions view with stats (total, active, completed, avg duration) and expandable session details
+- **Session Summaries** -- Structured summaries with investigated/completed/learned/next_steps sections
+- **Web Dashboard** -- Real-time viewer at `http://localhost:3001` with dark/light/system theme, hybrid search, project filters, mobile drawer, and live updates via SSE
+- **MCP Server** -- 11 tools exposed via Model Context Protocol
+- **Full-Text Search** -- SQLite FTS5 with weighted BM25 scoring for relevance-ranked results
+- **Data Export** -- Export observations and summaries in JSON or Markdown format
+- **Retention Policy** -- Automatic cleanup of old data with configurable age and dry-run mode
 - **TypeScript SDK** -- Programmatic access to the entire memory system
 - **CLI** -- Query and manage context directly from the terminal
 
@@ -147,6 +154,7 @@ The MCP server exposes 10 tools that your AI assistant can use directly.
 | `resume_session` | Get checkpoint data to resume a previous session |
 | `generate_report` | Generate weekly/monthly activity report in Markdown |
 | `get_recent_context` | Get recent memory context for session injection |
+| `save_memory` | Save a structured observation from external tools or scripts |
 
 ### Storage
 
@@ -282,9 +290,12 @@ kiro-memory decay --days=30
 The worker starts automatically when a Kiro session begins (via the `agentSpawn` hook). Once running, open `http://localhost:3001` in your browser to access the web dashboard with:
 
 - **Live feed** of observations, summaries, and prompts (via SSE)
-- **Project sidebar** with type filters and stats
-- **Spotlight search** (Ctrl+K / Cmd+K) with instant results
-- **Dark/light theme** toggle
+- **Sessions view** with stats cards and expandable session details
+- **Analytics dashboard** with timeline charts and type distribution
+- **Project sidebar** with type filters, stats, and token economics
+- **Spotlight search** (Ctrl+K / Cmd+K) with hybrid search and source badges
+- **Dark/light/system theme** cycling
+- **Mobile-responsive** sidebar drawer
 
 For development, you can also manage the worker manually:
 
@@ -443,3 +454,11 @@ Contributions are welcome. Please open an issue to discuss proposed changes befo
 ---
 
 Built by [auriti-web-design](https://github.com/auriti-web-design)
+
+---
+
+<p align="center">
+  <a href="https://buymeacoffee.com/auritidesign">
+    <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me a Coffee" />
+  </a>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-memory",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Persistent cross-session memory for AI coding assistants. Works with Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible editor.",
   "keywords": [
     "kiro",
@@ -94,7 +94,6 @@
     "better-sqlite3": "^12.6.2",
     "chromadb": "^3.2.2",
     "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
     "cors": "^2.8.5",
     "dompurify": "^3.3.1",
     "express": "^4.18.2",
@@ -105,13 +104,12 @@
     "lucide-react": "^0.574.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "tailwind-merge": "^3.4.1",
     "yaml": "^2.8.2",
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "fastembed": "^2.1.0",
-    "@huggingface/transformers": "^3.8.0"
+    "@huggingface/transformers": "^3.8.0",
+    "fastembed": "^2.1.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",

package/plugin/dist/cli/contextkit.js

@@ -249,19 +249,28 @@ __export(Observations_exports, {
   deleteObservation: () => deleteObservation,
   getObservationsByProject: () => getObservationsByProject,
   getObservationsBySession: () => getObservationsBySession,
+  isDuplicateObservation: () => isDuplicateObservation,
   searchObservations: () => searchObservations,
   updateLastAccessed: () => updateLastAccessed
 });
 function escapeLikePattern(input) {
   return input.replace(/[%_\\]/g, "\\$&");
 }
-function createObservation(db, memorySessionId, project, type, title, subtitle, text, narrative, facts, concepts, filesRead, filesModified, promptNumber) {
+function isDuplicateObservation(db, contentHash, windowMs = 3e4) {
+  if (!contentHash) return false;
+  const threshold = Date.now() - windowMs;
+  const result = db.query(
+    "SELECT id FROM observations WHERE content_hash = ? AND created_at_epoch > ? LIMIT 1"
+  ).get(contentHash, threshold);
+  return !!result;
+}
+function createObservation(db, memorySessionId, project, type, title, subtitle, text, narrative, facts, concepts, filesRead, filesModified, promptNumber, contentHash = null, discoveryTokens = 0) {
   const now = /* @__PURE__ */ new Date();
   const result = db.run(
-    `INSERT INTO observations 
-     (memory_session_id, project, type, title, subtitle, text, narrative, facts, concepts, files_read, files_modified, prompt_number, created_at, created_at_epoch)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    [memorySessionId, project, type, title, subtitle, text, narrative, facts, concepts, filesRead, filesModified, promptNumber, now.toISOString(), now.getTime()]
+    `INSERT INTO observations
+     (memory_session_id, project, type, title, subtitle, text, narrative, facts, concepts, files_read, files_modified, prompt_number, created_at, created_at_epoch, content_hash, discovery_tokens)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [memorySessionId, project, type, title, subtitle, text, narrative, facts, concepts, filesRead, filesModified, promptNumber, now.toISOString(), now.getTime(), contentHash, discoveryTokens]
   );
   return Number(result.lastInsertRowid);
 }
@@ -317,39 +326,42 @@ function consolidateObservations(db, project, options = {}) {
   if (groups.length === 0) return { merged: 0, removed: 0 };
   let totalMerged = 0;
   let totalRemoved = 0;
-  for (const group of groups) {
-    const obsIds = group.ids.split(",").map(Number);
-    const placeholders = obsIds.map(() => "?").join(",");
-    const observations = db.query(
-      `SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch DESC`
-    ).all(...obsIds);
-    if (observations.length < minGroupSize) continue;
-    if (options.dryRun) {
-      totalMerged += 1;
-      totalRemoved += observations.length - 1;
-      continue;
-    }
-    const keeper = observations[0];
-    const others = observations.slice(1);
-    const uniqueTexts = /* @__PURE__ */ new Set();
-    if (keeper.text) uniqueTexts.add(keeper.text);
-    for (const obs of others) {
-      if (obs.text && !uniqueTexts.has(obs.text)) {
-        uniqueTexts.add(obs.text);
+  const runConsolidation = db.transaction(() => {
+    for (const group of groups) {
+      const obsIds = group.ids.split(",").map(Number);
+      const placeholders = obsIds.map(() => "?").join(",");
+      const observations = db.query(
+        `SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch DESC`
+      ).all(...obsIds);
+      if (observations.length < minGroupSize) continue;
+      if (options.dryRun) {
+        totalMerged += 1;
+        totalRemoved += observations.length - 1;
+        continue;
+      }
+      const keeper = observations[0];
+      const others = observations.slice(1);
+      const uniqueTexts = /* @__PURE__ */ new Set();
+      if (keeper.text) uniqueTexts.add(keeper.text);
+      for (const obs of others) {
+        if (obs.text && !uniqueTexts.has(obs.text)) {
+          uniqueTexts.add(obs.text);
+        }
       }
+      const consolidatedText = Array.from(uniqueTexts).join("\n---\n").substring(0, 1e5);
+      db.run(
+        "UPDATE observations SET text = ?, title = ? WHERE id = ?",
+        [consolidatedText, `[consolidato x${observations.length}] ${keeper.title}`, keeper.id]
+      );
+      const removeIds = others.map((o) => o.id);
+      const removePlaceholders = removeIds.map(() => "?").join(",");
+      db.run(`DELETE FROM observations WHERE id IN (${removePlaceholders})`, removeIds);
+      db.run(`DELETE FROM observation_embeddings WHERE observation_id IN (${removePlaceholders})`, removeIds);
+      totalMerged += 1;
+      totalRemoved += removeIds.length;
     }
-    const consolidatedText = Array.from(uniqueTexts).join("\n---\n").substring(0, 1e5);
-    db.run(
-      "UPDATE observations SET text = ?, title = ? WHERE id = ?",
-      [consolidatedText, `[consolidato x${observations.length}] ${keeper.title}`, keeper.id]
-    );
-    const removeIds = others.map((o) => o.id);
-    const removePlaceholders = removeIds.map(() => "?").join(",");
-    db.run(`DELETE FROM observations WHERE id IN (${removePlaceholders})`, removeIds);
-    db.run(`DELETE FROM observation_embeddings WHERE observation_id IN (${removePlaceholders})`, removeIds);
-    totalMerged += 1;
-    totalRemoved += removeIds.length;
-  }
+  });
+  runConsolidation();
   return { merged: totalMerged, removed: totalRemoved };
 }
 var init_Observations = __esm({
@@ -407,7 +419,7 @@ function searchObservationsFTS(db, query, filters = {}) {
       sql += " AND o.created_at_epoch <= ?";
       params.push(filters.dateEnd);
     }
-    sql += " ORDER BY rank LIMIT ?";
+    sql += ` ORDER BY bm25(observations_fts, ${BM25_WEIGHTS}) LIMIT ?`;
     params.push(limit);
     const stmt = db.query(sql);
     return stmt.all(...params);
@@ -421,7 +433,7 @@ function searchObservationsFTSWithRank(db, query, filters = {}) {
     const safeQuery = sanitizeFTS5Query(query);
     if (!safeQuery) return [];
     let sql = `
-      SELECT o.*, rank as fts5_rank FROM observations o
+      SELECT o.*, bm25(observations_fts, ${BM25_WEIGHTS}) as fts5_rank FROM observations o
       JOIN observations_fts fts ON o.id = fts.rowid
       WHERE observations_fts MATCH ?
     `;
@@ -442,7 +454,7 @@ function searchObservationsFTSWithRank(db, query, filters = {}) {
       sql += " AND o.created_at_epoch <= ?";
       params.push(filters.dateEnd);
     }
-    sql += " ORDER BY rank LIMIT ?";
+    sql += ` ORDER BY bm25(observations_fts, ${BM25_WEIGHTS}) LIMIT ?`;
     params.push(limit);
     const stmt = db.query(sql);
     return stmt.all(...params);
@@ -546,11 +558,23 @@ function getProjectStats(db, project) {
   const sumStmt = db.query("SELECT COUNT(*) as count FROM summaries WHERE project = ?");
   const sesStmt = db.query("SELECT COUNT(*) as count FROM sessions WHERE project = ?");
   const prmStmt = db.query("SELECT COUNT(*) as count FROM prompts WHERE project = ?");
+  const discoveryStmt = db.query(
+    "SELECT COALESCE(SUM(discovery_tokens), 0) as total FROM observations WHERE project = ?"
+  );
+  const discoveryTokens = discoveryStmt.get(project)?.total || 0;
+  const readStmt = db.query(
+    `SELECT COALESCE(SUM(
+      CAST((LENGTH(COALESCE(title, '')) + LENGTH(COALESCE(narrative, ''))) / 4 AS INTEGER)
+    ), 0) as total FROM observations WHERE project = ?`
+  );
+  const readTokens = readStmt.get(project)?.total || 0;
+  const savings = Math.max(0, discoveryTokens - readTokens);
   return {
     observations: obsStmt.get(project)?.count || 0,
     summaries: sumStmt.get(project)?.count || 0,
     sessions: sesStmt.get(project)?.count || 0,
-    prompts: prmStmt.get(project)?.count || 0
+    prompts: prmStmt.get(project)?.count || 0,
+    tokenEconomics: { discoveryTokens, readTokens, savings }
   };
 }
 function getStaleObservations(db, project) {
@@ -592,9 +616,11 @@ function markObservationsStale(db, ids, stale) {
     [stale ? 1 : 0, ...validIds]
   );
 }
+var BM25_WEIGHTS;
 var init_Search = __esm({
   "src/services/sqlite/Search.ts"() {
     "use strict";
+    BM25_WEIGHTS = "10.0, 1.0, 5.0, 3.0";
   }
 });
 
@@ -1106,6 +1132,29 @@ var MigrationRunner = class {
           db.run("CREATE INDEX IF NOT EXISTS idx_checkpoints_project ON checkpoints(project)");
           db.run("CREATE INDEX IF NOT EXISTS idx_checkpoints_epoch ON checkpoints(created_at_epoch)");
         }
+      },
+      {
+        version: 7,
+        up: (db) => {
+          db.run("ALTER TABLE observations ADD COLUMN content_hash TEXT");
+          db.run("CREATE INDEX IF NOT EXISTS idx_observations_hash ON observations(content_hash)");
+        }
+      },
+      {
+        version: 8,
+        up: (db) => {
+          db.run("ALTER TABLE observations ADD COLUMN discovery_tokens INTEGER DEFAULT 0");
+          db.run("ALTER TABLE summaries ADD COLUMN discovery_tokens INTEGER DEFAULT 0");
+        }
+      },
+      {
+        version: 9,
+        up: (db) => {
+          db.run("CREATE INDEX IF NOT EXISTS idx_observations_project_epoch ON observations(project, created_at_epoch DESC)");
+          db.run("CREATE INDEX IF NOT EXISTS idx_observations_project_type ON observations(project, type)");
+          db.run("CREATE INDEX IF NOT EXISTS idx_summaries_project_epoch ON summaries(project, created_at_epoch DESC)");
+          db.run("CREATE INDEX IF NOT EXISTS idx_prompts_project_epoch ON prompts(project, created_at_epoch DESC)");
+        }
       }
     ];
   }
@@ -1350,6 +1399,7 @@ init_Search();
 
 // src/sdk/index.ts
 init_Observations();
+import { createHash } from "crypto";
 init_Search();
 
 // src/services/search/HybridSearch.ts
@@ -1779,31 +1829,71 @@ var KiroMemorySDK = class {
       logger.debug("SDK", `Embedding generation fallita per obs ${observationId}: ${error}`);
     }
   }
+  /**
+   * Genera content hash SHA256 per deduplicazione basata su contenuto.
+   * Usa (project + type + title + narrative) come tupla di identità semantica.
+   * NON include sessionId perché è unico ad ogni invocazione.
+   */
+  generateContentHash(type, title, narrative) {
+    const payload = `${this.project}|${type}|${title}|${narrative || ""}`;
+    return createHash("sha256").update(payload).digest("hex");
+  }
+  /**
+   * Finestre di deduplicazione per tipo (ms).
+   * Tipi con molte ripetizioni hanno finestre più ampie.
+   */
+  getDeduplicationWindow(type) {
+    switch (type) {
+      case "file-read":
+        return 6e4;
+      // 60s — letture frequenti sugli stessi file
+      case "file-write":
+        return 1e4;
+      // 10s — scritture rapide consecutive
+      case "command":
+        return 3e4;
+      // 30s — standard
+      case "research":
+        return 12e4;
+      // 120s — web search e fetch ripetuti
+      case "delegation":
+        return 6e4;
+      // 60s — delegazioni rapide
+      default:
+        return 3e4;
+    }
+  }
   /**
    * Store a new observation
    */
   async storeObservation(data) {
     this.validateObservationInput(data);
+    const sessionId = "sdk-" + Date.now();
+    const contentHash = this.generateContentHash(data.type, data.title, data.narrative);
+    const dedupWindow = this.getDeduplicationWindow(data.type);
+    if (isDuplicateObservation(this.db.db, contentHash, dedupWindow)) {
+      logger.debug("SDK", `Osservazione duplicata scartata (${data.type}, ${dedupWindow}ms): ${data.title}`);
+      return -1;
+    }
+    const filesRead = data.filesRead || (data.type === "file-read" ? data.files : void 0);
+    const filesModified = data.filesModified || (data.type === "file-write" ? data.files : void 0);
+    const discoveryTokens = Math.ceil(data.content.length / 4);
     const observationId = createObservation(
       this.db.db,
-      "sdk-" + Date.now(),
+      sessionId,
       this.project,
       data.type,
       data.title,
-      null,
-      // subtitle
+      data.subtitle || null,
       data.content,
-      null,
-      // narrative
-      null,
-      // facts
+      data.narrative || null,
+      data.facts || null,
       data.concepts?.join(", ") || null,
-      data.files?.join(", ") || null,
-      // files_read
-      data.files?.join(", ") || null,
-      // files_modified
-      0
-      // prompt_number
+      filesRead?.join(", ") || null,
+      filesModified?.join(", ") || null,
+      0,
+      contentHash,
+      discoveryTokens
     );
     this.generateEmbeddingAsync(observationId, data.title, data.content, data.concepts).catch(() => {
     });
@@ -1846,9 +1936,16 @@ var KiroMemorySDK = class {
           };
       }
     })();
+    const sessionId = "sdk-" + Date.now();
+    const contentHash = this.generateContentHash(data.type, data.title);
+    if (isDuplicateObservation(this.db.db, contentHash)) {
+      logger.debug("SDK", `Knowledge duplicata scartata: ${data.title}`);
+      return -1;
+    }
+    const discoveryTokens = Math.ceil(data.content.length / 4);
     const observationId = createObservation(
       this.db.db,
-      "sdk-" + Date.now(),
+      sessionId,
       data.project || this.project,
       data.knowledgeType,
       // type = knowledgeType
@@ -1862,9 +1959,12 @@ var KiroMemorySDK = class {
       // facts = metadati JSON
       data.concepts?.join(", ") || null,
       data.files?.join(", ") || null,
-      data.files?.join(", ") || null,
-      0
+      null,
+      // filesModified: knowledge non modifica file
+      0,
       // prompt_number
+      contentHash,
+      discoveryTokens
     );
     this.generateEmbeddingAsync(observationId, data.title, data.content, data.concepts).catch(() => {
     });
@@ -1880,11 +1980,11 @@ var KiroMemorySDK = class {
       "sdk-" + Date.now(),
       this.project,
       data.request || null,
-      null,
+      data.investigated || null,
       data.learned || null,
       data.completed || null,
       data.nextSteps || null,
-      null
+      data.notes || null
     );
   }
   /**
@@ -2068,7 +2168,14 @@ var KiroMemorySDK = class {
       }));
     } else {
       const observations = getObservationsByProject(this.db.db, this.project, 30);
-      items = observations.map((obs) => {
+      const knowledgeTypes = new Set(KNOWLEDGE_TYPES);
+      const knowledgeObs = [];
+      const normalObs = [];
+      for (const obs of observations) {
+        if (knowledgeTypes.has(obs.type)) knowledgeObs.push(obs);
+        else normalObs.push(obs);
+      }
+      const scoreObs = (obs) => {
         const signals = {
           semantic: 0,
           fts5: 0,
@@ -2076,7 +2183,6 @@ var KiroMemorySDK = class {
           projectMatch: projectMatchScore(obs.project, this.project)
         };
         const baseScore = computeCompositeScore(signals, CONTEXT_WEIGHTS);
-        const boostedScore = Math.min(1, baseScore * knowledgeTypeBoost(obs.type));
         return {
           id: obs.id,
           title: obs.title,
@@ -2085,17 +2191,23 @@ var KiroMemorySDK = class {
           project: obs.project,
           created_at: obs.created_at,
           created_at_epoch: obs.created_at_epoch,
-          score: boostedScore,
+          score: Math.min(1, baseScore * knowledgeTypeBoost(obs.type)),
           signals
         };
-      });
-      items.sort((a, b) => b.score - a.score);
+      };
+      const scoredKnowledge = knowledgeObs.map(scoreObs).sort((a, b) => b.score - a.score);
+      const scoredNormal = normalObs.map(scoreObs).sort((a, b) => b.score - a.score);
+      items = [...scoredKnowledge, ...scoredNormal];
     }
     let tokensUsed = 0;
+    const budgetItems = [];
     for (const item of items) {
-      tokensUsed += Math.ceil((item.title.length + item.content.length) / 4);
-      if (tokensUsed > tokenBudget) break;
+      const itemTokens = Math.ceil((item.title.length + item.content.length) / 4);
+      if (tokensUsed + itemTokens > tokenBudget) break;
+      tokensUsed += itemTokens;
+      budgetItems.push(item);
     }
+    items = budgetItems;
     return {
       project: this.project,
       items,