@hanhnd/agent-kit 1.0.38 → 1.0.40

package/dist/server.js

@@ -3222,8 +3222,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path15) {
-      let input = path15;
+    function removeDotSegments(path16) {
+      let input = path16;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3422,8 +3422,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path15, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path15 && path15 !== "/" ? path15 : void 0;
+        const [path16, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path16 && path16 !== "/" ? path16 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -22164,8 +22164,8 @@ function getErrorMap() {
 
 // ../node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path15, errorMaps, issueData } = params;
-  const fullPath = [...path15, ...issueData.path || []];
+  const { data, path: path16, errorMaps, issueData } = params;
+  const fullPath = [...path16, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -22281,11 +22281,11 @@ var errorUtil;
 
 // ../node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path15, key) {
+  constructor(parent, value, path16, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path15;
+    this._path = path16;
     this._key = key;
   }
   get path() {
@@ -25923,15 +25923,15 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path15) {
-  if (!path15)
+function getElementAtPath(obj, path16) {
+  if (!path16)
     return obj;
-  return path15.reduce((acc, key) => acc?.[key], obj);
+  return path16.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
-  const promises = keys.map((key) => promisesObj[key]);
-  return Promise.all(promises).then((results) => {
+  const promises3 = keys.map((key) => promisesObj[key]);
+  return Promise.all(promises3).then((results) => {
     const resolvedObj = {};
     for (let i = 0; i < keys.length; i++) {
       resolvedObj[keys[i]] = results[i];
@@ -26246,11 +26246,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path15, issues) {
+function prefixIssues(path16, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path15);
+    iss.path.unshift(path16);
     return iss;
   });
 }
@@ -36777,7 +36777,10 @@ ${ticket.fields.labels?.join(", ") || "None"}`;
 
 // src/mcp/memory.ts
 import * as fs11 from "fs";
-import * as path14 from "path";
+import * as path15 from "path";
+
+// src/services/memory/subsystem.ts
+import * as path10 from "path";
 
 // src/services/memory/embedder.ts
 var EmbedderError = class extends Error {
@@ -36993,6 +36996,37 @@ ${sectionText}` : sectionText;
   return chunks;
 }
 
+// src/utils/async.ts
+async function withTimeout(promise, timeoutMs, createError) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(createError());
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function mapLimit(items, limit, worker) {
+  if (items.length === 0) return [];
+  const concurrency = Math.max(1, Math.floor(limit));
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  async function runWorker() {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex;
+      nextIndex++;
+      results[currentIndex] = await worker(items[currentIndex], currentIndex);
+    }
+  }
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, () => runWorker());
+  await Promise.all(runners);
+  return results;
+}
+
 // src/services/memory/indexer.ts
 function deriveSourceType(source) {
   if (source.startsWith("compiled/provisional/conversation-digests/")) return "digest";
@@ -37009,21 +37043,31 @@ var MemoryIndexer = class {
   }
   _ready = false;
   async indexFile(absolutePath) {
-    return this.indexFileRelativeTo(absolutePath, this.config.wikiDir);
+    const mutation = await this.prepareIndexFileRelativeTo(absolutePath, this.config.wikiDir);
+    return this.commitPreparedMutation(mutation);
+  }
+  makeSkippedMutation(source, skipped) {
+    return {
+      source,
+      chunksToUpsert: [],
+      embeddings: [],
+      idsToDelete: [],
+      stats: { indexed: 0, deleted: 0, skipped }
+    };
   }
-  async indexFileRelativeTo(absolutePath, sourceRoot) {
+  async prepareIndexFileRelativeTo(absolutePath, sourceRoot) {
     const source = path8.relative(sourceRoot, absolutePath);
     const existingChunkIds = this.store.hashesBySource(source);
     let text;
     try {
-      text = fs6.readFileSync(absolutePath, "utf8");
+      text = await fs6.promises.readFile(absolutePath, "utf8");
     } catch (err) {
       console.warn(`[memory-indexer] Cannot read file ${absolutePath}:`, err);
-      return { indexed: 0, deleted: 0, skipped: existingChunkIds.size };
+      return this.makeSkippedMutation(source, existingChunkIds.size);
     }
     let fileMtimeAt;
     try {
-      fileMtimeAt = fs6.statSync(absolutePath).mtimeMs;
+      fileMtimeAt = (await fs6.promises.stat(absolutePath)).mtimeMs;
     } catch (err) {
       console.warn(`[memory-indexer] Cannot stat file ${absolutePath}:`, err);
       fileMtimeAt = Date.now();
@@ -37039,39 +37083,56 @@ var MemoryIndexer = class {
         embeddings = await this.embedder.embed(toIndex.map((c) => c.content));
       } catch (err) {
         console.warn(`[memory-indexer] Embedding failed for ${absolutePath}:`, err);
-        return { indexed: 0, deleted: 0, skipped: existingChunkIds.size };
+        return this.makeSkippedMutation(source, existingChunkIds.size);
       }
     }
-    if (toIndex.length > 0) {
-      this.store.upsert(toIndex, embeddings);
-    }
-    if (toDelete.length > 0) {
-      this.store.deleteByIds(toDelete);
-    }
     return {
-      indexed: toIndex.length,
-      deleted: toDelete.length,
-      skipped: allChunks.length - toIndex.length
+      source,
+      chunksToUpsert: toIndex,
+      embeddings,
+      idsToDelete: toDelete,
+      stats: {
+        indexed: toIndex.length,
+        deleted: toDelete.length,
+        skipped: allChunks.length - toIndex.length
+      }
     };
   }
+  commitPreparedMutation(mutation) {
+    if (mutation.chunksToUpsert.length > 0) {
+      this.store.upsert(mutation.chunksToUpsert, mutation.embeddings);
+    }
+    if (mutation.idsToDelete.length > 0) {
+      this.store.deleteByIds(mutation.idsToDelete);
+    }
+    return mutation.stats;
+  }
   async indexDirectory(rootDir, opts = {}) {
     const totals = { indexed: 0, deleted: 0, skipped: 0 };
-    if (!fs6.existsSync(rootDir)) return totals;
+    let rootExists;
+    try {
+      await fs6.promises.stat(rootDir);
+      rootExists = true;
+    } catch {
+      rootExists = false;
+    }
+    if (!rootExists) return totals;
     const relativeBase = opts.relativeBase ?? this.config.wikiDir;
     const excludeFiles = new Set(opts.excludeFiles ?? []);
     const files = [];
-    const walk = (dirPath) => {
+    const walk = async (dirPath) => {
       let entries;
       try {
-        entries = fs6.readdirSync(dirPath, { withFileTypes: true });
+        entries = await fs6.promises.readdir(dirPath, { withFileTypes: true });
       } catch (err) {
         console.warn(`[memory-indexer] Cannot scan directory ${dirPath}:`, err);
         return;
       }
+      entries.sort((a, b) => a.name.localeCompare(b.name));
       for (const entry of entries) {
         const entryPath = path8.join(dirPath, entry.name);
         if (entry.isDirectory()) {
-          walk(entryPath);
+          await walk(entryPath);
           continue;
         }
         if (entry.isFile() && /\.md$/i.test(entry.name) && !excludeFiles.has(entry.name)) {
@@ -37079,7 +37140,7 @@ var MemoryIndexer = class {
         }
       }
     };
-    walk(rootDir);
+    await walk(rootDir);
     const currentSources = new Set(files.map((file) => path8.relative(relativeBase, file)));
     for (const stale of this.store.indexedSources()) {
       if (!currentSources.has(stale)) {
@@ -37087,8 +37148,13 @@ var MemoryIndexer = class {
         totals.deleted += 1;
       }
     }
-    for (const file of files) {
-      const stats = await this.indexFileRelativeTo(file, relativeBase);
+    const preparedMutations = await mapLimit(
+      files,
+      opts.fileConcurrency ?? 2,
+      (file) => this.prepareIndexFileRelativeTo(file, relativeBase)
+    );
+    for (const mutation of preparedMutations) {
+      const stats = this.commitPreparedMutation(mutation);
       totals.indexed += stats.indexed;
       totals.deleted += stats.deleted;
       totals.skipped += stats.skipped;
@@ -37097,77 +37163,34 @@ var MemoryIndexer = class {
   }
   async search(query, topK) {
     const fetchLimit = topK * FETCH_MULTIPLIER;
-    let denseResults = [];
+    let embedding;
     if (this.store.vecAvailable) {
       try {
-        const queryEmbedding = await this.embedder.embed([query]);
-        denseResults = this.store.searchDense(queryEmbedding[0], fetchLimit);
+        const embeddings = await this.embedder.embed([query]);
+        embedding = embeddings[0];
       } catch (err) {
         console.warn("[memory-indexer] Dense search embedding failed:", err);
       }
     }
-    const bm25Results = this.store.searchBm25(query, fetchLimit);
-    const denseIds = new Set(denseResults.map((r) => r.id));
-    const bm25Ids = new Set(bm25Results.map((r) => r.id));
-    const unionIds = /* @__PURE__ */ new Set([...denseIds, ...bm25Ids]);
-    const denseRetrievalScore = new Map(denseResults.map((r) => [r.id, r.score]));
-    const unionArray = [...unionIds];
-    const chunks = this.store.getChunksByIds(unionArray);
-    const chunkMap = new Map(chunks.map((c) => [c.id, c]));
-    const unionIndexOf = new Map(unionArray.map((id, idx) => [id, idx]));
-    const recencyOrdered = [...unionArray].sort((a, b) => {
-      const mtimeA = chunkMap.get(a)?.fileMtimeAt ?? 0;
-      const mtimeB = chunkMap.get(b)?.fileMtimeAt ?? 0;
-      if (mtimeB !== mtimeA) return mtimeB - mtimeA;
-      return (unionIndexOf.get(a) ?? 0) - (unionIndexOf.get(b) ?? 0);
+    const rows = this.store.searchHybrid({
+      query,
+      embedding,
+      topK,
+      fetchLimit,
+      denseScoreFloor: DENSE_SCORE_FLOOR,
+      recencyWeight: RECENCY_WEIGHT,
+      rrfK: RRF_K
     });
-    const scoreMap = /* @__PURE__ */ new Map();
-    denseResults.forEach((r, rank) => {
-      scoreMap.set(r.id, { dense: 1 / (RRF_K + rank + 1), bm25: 0, recency: 0 });
-    });
-    bm25Results.forEach((r, rank) => {
-      const entry = scoreMap.get(r.id) ?? { dense: 0, bm25: 0, recency: 0 };
-      entry.bm25 = 1 / (RRF_K + rank + 1);
-      scoreMap.set(r.id, entry);
-    });
-    recencyOrdered.forEach((id, rank) => {
-      const entry = scoreMap.get(id);
-      if (!entry) return;
-      entry.recency = RECENCY_WEIGHT * (1 / (RRF_K + rank + 1));
-    });
-    const denseActive = denseResults.length > 0;
-    const bm25Active = bm25Results.length > 0;
-    const recencyActive = unionIds.size > 0;
-    const maxScore = ((denseActive ? 1 : 0) + (bm25Active ? 1 : 0) + (recencyActive ? RECENCY_WEIGHT : 0)) / (RRF_K + 1);
-    const ranked = [...scoreMap.entries()].map(([id, scores]) => ({
-      id,
-      totalScore: scores.dense + scores.bm25 + scores.recency,
-      hasDense: scores.dense > 0,
-      hasBm25: scores.bm25 > 0,
-      isDenseOnly: denseIds.has(id) && !bm25Ids.has(id)
-    })).filter((candidate) => {
-      if (!candidate.isDenseOnly) return true;
-      const retrieval = denseRetrievalScore.get(candidate.id);
-      if (retrieval === void 0) return true;
-      return retrieval >= DENSE_SCORE_FLOOR;
-    }).sort((a, b) => b.totalScore - a.totalScore);
+    if (rows.length === 0) return [];
     const results = [];
-    const seenSources = /* @__PURE__ */ new Set();
-    for (const r of ranked) {
-      if (results.length >= topK) break;
-      const chunk = chunkMap.get(r.id);
-      if (!chunk) continue;
-      if (seenSources.has(chunk.source)) continue;
-      seenSources.add(chunk.source);
-      const normalizedScore = maxScore > 0 ? r.totalScore / maxScore : 0;
-      const retriever = r.hasDense && r.hasBm25 ? "both" : r.hasDense ? "dense" : "bm25";
+    for (const row of rows) {
       let contentSource = "file";
       try {
-        chunk.content = fs6.readFileSync(path8.join(this.config.wikiDir, chunk.source), "utf8");
+        row.chunk.content = await fs6.promises.readFile(path8.join(this.config.wikiDir, row.chunk.source), "utf8");
       } catch {
         contentSource = "fallback";
       }
-      results.push({ chunk, score: normalizedScore, retriever, contentSource });
+      results.push({ chunk: row.chunk, score: row.score, retriever: row.retriever, contentSource });
     }
     return results;
   }
@@ -37176,13 +37199,13 @@ var MemoryIndexer = class {
     const rawDir = path8.join(this.config.wikiDir, "raw");
     const savePath = path8.join(rawDir, `conv_save_${datePart}.md`);
     const lockPath = `${savePath}.lock`;
-    fs6.mkdirSync(rawDir, { recursive: true });
+    await fs6.promises.mkdir(rawDir, { recursive: true });
     const acquired = await acquireLock(lockPath, LOCK_TIMEOUT_MS, LOCK_RETRY_MS);
     if (!acquired) {
       console.warn("[memory-indexer] Could not acquire write lock, writing anyway (fail-open)");
     }
     try {
-      fs6.appendFileSync(savePath, `
+      await fs6.promises.appendFile(savePath, `
 ${content}
 `, "utf8");
     } finally {
@@ -37389,10 +37412,6 @@ var MemoryStore = class {
     }
     return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
   }
-  normalizeVectorDistance(distance) {
-    if (distance <= 0) return 1;
-    return Math.max(0, Math.min(1, 1 - distance));
-  }
   hashesBySource(source) {
     const rows = this.db.prepare(`SELECT id FROM memory_chunks WHERE source = ?`).all(source);
     return new Set(rows.map((r) => r.id));
@@ -37429,61 +37448,12 @@ var MemoryStore = class {
     });
     deleteAll();
   }
-  searchDense(embedding, limit) {
-    try {
-      const queryVector = this.toVectorBinding(embedding);
-      const rows = this.db.prepare(
-        `SELECT mc.id, vector_distance_cos(mc.embedding, vector32(?)) AS distance
-           FROM vector_top_k('idx_memory_chunks_embedding', vector32(?), ?) AS vector_matches
-           JOIN memory_chunks mc ON mc.rowid = vector_matches.id
-           ORDER BY distance
-           LIMIT ?`
-      ).all(queryVector, queryVector, limit, limit);
-      return rows.map((r) => ({
-        id: r.id,
-        score: this.normalizeVectorDistance(r.distance)
-      }));
-    } catch (err) {
-      console.warn("[memory-store] Dense search failed:", err);
-      return [];
-    }
-  }
-  searchBm25(query, limit) {
-    if (!query.trim()) return [];
+  buildFtsQuery(query) {
     const tokens = query.trim().split(/\s+/).map((t) => t.replace(/[^a-zA-Z0-9_]/g, "").toLowerCase()).filter((t) => t.length > 1);
-    const ftsQuery = (0, import_stopword.removeStopwords)(tokens, import_stopword.eng).map((t) => `${t.replace(/s$/, "")}*`).join(" OR ");
-    if (!ftsQuery) return [];
-    try {
-      const rows = this.db.prepare(
-        `SELECT mc.id, bm25(memory_fts, 0.2, 2.0, 5.0) AS rank
-           FROM memory_fts
-           JOIN memory_chunks mc ON mc.rowid = memory_fts.rowid
-           WHERE memory_fts MATCH ?
-           ORDER BY rank
-           LIMIT ?`
-      ).all(ftsQuery, limit);
-      if (rows.length === 0) return [];
-      const ranks = rows.map((r) => r.rank);
-      const minRank = Math.min(...ranks);
-      const maxRank = Math.max(...ranks);
-      const range = maxRank - minRank;
-      return rows.map((r) => ({
-        id: r.id,
-        score: range > 0 ? (maxRank - r.rank) / range : 1
-      }));
-    } catch (err) {
-      console.warn("[memory-store] BM25 search failed:", err);
-      return [];
-    }
+    return (0, import_stopword.removeStopwords)(tokens, import_stopword.eng).map((t) => `${t.replace(/s$/, "")}*`).join(" OR ");
   }
-  getChunksByIds(ids) {
-    if (ids.length === 0) return [];
-    const placeholders = ids.map(() => "?").join(", ");
-    const rows = this.db.prepare(
-      `SELECT id, source, source_type, heading, heading_level, content, line_start, line_end, file_mtime_at
-         FROM memory_chunks WHERE id IN (${placeholders})`
-    ).all(...ids);
-    return rows.map((r) => ({
+  mapMemoryChunkRow(r) {
+    return {
       id: r.id,
       source: r.source,
       sourceType: r.source_type,
@@ -37493,7 +37463,201 @@ var MemoryStore = class {
       lineStart: r.line_start,
       lineEnd: r.line_end,
       fileMtimeAt: r.file_mtime_at
-    }));
+    };
+  }
+  searchHybrid(options) {
+    const {
+      query,
+      embedding,
+      topK,
+      fetchLimit,
+      denseScoreFloor,
+      recencyWeight,
+      rrfK,
+      sourceType,
+      sinceMtimeAt,
+      includeDebug
+    } = options;
+    const ftsQuery = this.buildFtsQuery(query);
+    const hasDense = embedding !== void 0;
+    const hasBm25 = ftsQuery.length > 0;
+    if (!hasDense && !hasBm25) return [];
+    const hasFilters = sourceType !== void 0 || sinceMtimeAt !== void 0;
+    try {
+      const params = [];
+      let denseCte = "";
+      let denseRankedCte = "";
+      if (hasDense) {
+        const queryBuf = this.toVectorBinding(embedding);
+        if (hasFilters) {
+          const filterClauses = [];
+          if (sourceType) {
+            filterClauses.push("mc.source_type = ?");
+            params.push(sourceType);
+          }
+          if (sinceMtimeAt !== void 0) {
+            filterClauses.push("mc.file_mtime_at >= ?");
+            params.push(sinceMtimeAt);
+          }
+          const whereClause = filterClauses.length > 0 ? `WHERE ${filterClauses.join(" AND ")}` : "";
+          params.push(queryBuf);
+          params.push(fetchLimit);
+          denseCte = `dense_data AS (
+            SELECT mc.id, mc.source, mc.source_type, mc.file_mtime_at,
+                   mc.heading, mc.heading_level, mc.content, mc.line_start, mc.line_end,
+                   vector_distance_cos(mc.embedding, vector32(?)) AS dense_dist
+            FROM memory_chunks mc
+            ${whereClause}
+            ORDER BY dense_dist
+            LIMIT ?
+          )`;
+        } else {
+          params.push(queryBuf);
+          params.push(queryBuf);
+          params.push(fetchLimit);
+          denseCte = `dense_data AS (
+            SELECT mc.id, mc.source, mc.source_type, mc.file_mtime_at,
+                   mc.heading, mc.heading_level, mc.content, mc.line_start, mc.line_end,
+                   vector_distance_cos(mc.embedding, vector32(?)) AS dense_dist
+            FROM vector_top_k('idx_memory_chunks_embedding', vector32(?), ?) AS vtk
+            JOIN memory_chunks mc ON mc.rowid = vtk.id
+          )`;
+        }
+        denseRankedCte = `dense_ranked AS (
+          SELECT *, ROW_NUMBER() OVER (ORDER BY dense_dist, id) AS dense_rank
+          FROM dense_data
+        )`;
+      }
+      let bm25Cte = "";
+      let bm25RankedCte = "";
+      if (hasBm25) {
+        const bm25FilterClauses = [];
+        if (sourceType) bm25FilterClauses.push("mc.source_type = ?");
+        if (sinceMtimeAt !== void 0) bm25FilterClauses.push("mc.file_mtime_at >= ?");
+        const bm25WhereExtra = bm25FilterClauses.length > 0 ? ` AND ${bm25FilterClauses.join(" AND ")}` : "";
+        params.push(ftsQuery);
+        if (sourceType) params.push(sourceType);
+        if (sinceMtimeAt !== void 0) params.push(sinceMtimeAt);
+        params.push(fetchLimit);
+        bm25Cte = `bm25_data AS (
+          SELECT mc.id, mc.source, mc.source_type, mc.file_mtime_at,
+                 mc.heading, mc.heading_level, mc.content, mc.line_start, mc.line_end,
+                 bm25(memory_fts, 0.2, 2.0, 5.0) AS bm25_neg
+          FROM memory_fts
+          JOIN memory_chunks mc ON mc.rowid = memory_fts.rowid
+          WHERE memory_fts MATCH ?${bm25WhereExtra}
+          LIMIT ?
+        )`;
+        bm25RankedCte = `bm25_ranked AS (
+          SELECT *, ROW_NUMBER() OVER (ORDER BY bm25_neg, id) AS bm25_rank
+          FROM bm25_data
+        )`;
+      }
+      let candidatesCte = "";
+      if (hasDense && hasBm25) {
+        candidatesCte = `all_candidates AS (
+          SELECT d.id, d.source, d.source_type, d.file_mtime_at,
+                 d.heading, d.heading_level, d.content, d.line_start, d.line_end,
+                 CAST(d.dense_rank AS INTEGER) AS dense_rank, d.dense_dist,
+                 b.bm25_rank,
+                 CASE WHEN b.id IS NOT NULL THEN 'both' ELSE 'dense' END AS retriever
+          FROM dense_ranked d
+          LEFT JOIN bm25_ranked b ON b.id = d.id
+          UNION ALL
+          SELECT b.id, b.source, b.source_type, b.file_mtime_at,
+                 b.heading, b.heading_level, b.content, b.line_start, b.line_end,
+                 NULL AS dense_rank, NULL AS dense_dist,
+                 CAST(b.bm25_rank AS INTEGER) AS bm25_rank,
+                 'bm25' AS retriever
+          FROM bm25_ranked b
+          LEFT JOIN dense_ranked d ON d.id = b.id
+          WHERE d.id IS NULL
+        )`;
+      } else if (hasDense) {
+        candidatesCte = `all_candidates AS (
+          SELECT id, source, source_type, file_mtime_at,
+                 heading, heading_level, content, line_start, line_end,
+                 CAST(dense_rank AS INTEGER) AS dense_rank, dense_dist,
+                 NULL AS bm25_rank, 'dense' AS retriever
+          FROM dense_ranked
+        )`;
+      } else {
+        candidatesCte = `all_candidates AS (
+          SELECT id, source, source_type, file_mtime_at,
+                 heading, heading_level, content, line_start, line_end,
+                 NULL AS dense_rank, NULL AS dense_dist,
+                 CAST(bm25_rank AS INTEGER) AS bm25_rank, 'bm25' AS retriever
+          FROM bm25_ranked
+        )`;
+      }
+      params.push(rrfK, rrfK, recencyWeight, rrfK, denseScoreFloor, topK);
+      const sql = `
+        WITH
+          ${[denseCte, denseRankedCte, bm25Cte, bm25RankedCte, candidatesCte].filter(Boolean).join(",\n")}
+        ,
+        recency_ranked AS (
+          SELECT id, ROW_NUMBER() OVER (ORDER BY file_mtime_at DESC, source, id) AS recency_rank
+          FROM all_candidates
+        ),
+        scored AS (
+          SELECT c.id, c.source, c.source_type, c.file_mtime_at,
+                 c.heading, c.heading_level, c.content, c.line_start, c.line_end,
+                 c.dense_rank, c.dense_dist, c.bm25_rank, r.recency_rank,
+                 c.retriever,
+                 COALESCE(1.0 / (? + c.dense_rank), 0.0) +
+                 COALESCE(1.0 / (? + c.bm25_rank), 0.0) +
+                 ? * (1.0 / (? + r.recency_rank)) AS total_score
+          FROM all_candidates c
+          JOIN recency_ranked r ON r.id = c.id
+          WHERE c.retriever != 'dense' OR (1.0 - c.dense_dist) >= ?
+        ),
+        best_per_source AS (
+          SELECT *,
+                 ROW_NUMBER() OVER (PARTITION BY source ORDER BY total_score DESC, source, id) AS source_rank
+          FROM scored
+        )
+        SELECT id, source, source_type, file_mtime_at, heading, heading_level, content, line_start, line_end,
+               dense_rank, dense_dist, bm25_rank, recency_rank, total_score, retriever
+        FROM best_per_source
+        WHERE source_rank = 1
+        ORDER BY total_score DESC, source, id
+        LIMIT ?
+      `;
+      const rows = this.db.prepare(sql).all(...params);
+      if (rows.length === 0) return [];
+      const denseActive = hasDense;
+      const bm25Active = hasBm25;
+      const recencyActive = rows.length > 0;
+      const maxScore = ((denseActive ? 1 : 0) + (bm25Active ? 1 : 0) + (recencyActive ? recencyWeight : 0)) / (rrfK + 1);
+      return rows.map((r) => {
+        const chunk = this.mapMemoryChunkRow(r);
+        const normalizedScore = maxScore > 0 ? r.total_score / maxScore : 0;
+        const row = {
+          chunk,
+          score: normalizedScore,
+          retriever: r.retriever
+        };
+        if (includeDebug) {
+          const denseScore = r.dense_dist !== null ? Math.max(0, Math.min(1, 1 - r.dense_dist)) : void 0;
+          const bm25Score = r.bm25_rank !== null ? 1 / (rrfK + r.bm25_rank) : void 0;
+          const recencyScore = recencyWeight * (1 / (rrfK + r.recency_rank));
+          const debug = {
+            denseRank: r.dense_rank ?? void 0,
+            denseScore,
+            bm25Rank: r.bm25_rank ?? void 0,
+            bm25Score,
+            recencyRank: r.recency_rank,
+            recencyScore,
+            totalScore: r.total_score
+          };
+          row.debug = debug;
+        }
+        return row;
+      });
+    } catch (err) {
+      console.warn("[memory-store] Hybrid search failed:", err);
+      return [];
+    }
   }
   get vecAvailable() {
     return true;
@@ -37503,45 +37667,103 @@ var MemoryStore = class {
   }
 };
 
+// src/services/memory/subsystem.ts
+var DefaultMemorySubsystem = class {
+  constructor(config2, indexer, store, initialState, initialError) {
+    this.config = config2;
+    this.indexer = indexer;
+    this.store = store;
+    this.lifecycleStatus = makeStatus(initialState, initialError);
+  }
+  lifecycleStatus;
+  get status() {
+    return this.lifecycleStatus;
+  }
+  async startWarmup() {
+    if (!this.indexer) {
+      this.lifecycleStatus = makeStatus("failed", this.lifecycleStatus.error ?? "Memory indexer is unavailable");
+      return;
+    }
+    this.lifecycleStatus = makeStatus("warming");
+    try {
+      await this.indexer.startupIndex();
+      this.lifecycleStatus = makeStatus("ready");
+    } catch (err) {
+      this.lifecycleStatus = makeStatus(this.store ? "degraded" : "failed", formatError3(err));
+    }
+  }
+  close() {
+    this.store?.close();
+  }
+};
+function makeStatus(state, error2) {
+  return {
+    state,
+    ready: state === "ready",
+    warming: state === "initializing" || state === "warming",
+    degraded: state === "degraded" || state === "failed",
+    error: error2
+  };
+}
+function formatError3(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function createMemorySubsystem(workspaceRoot2, overrides = {}) {
+  const config2 = overrides.config ?? resolveMemoryConfig(overrides.settings ?? {}, workspaceRoot2);
+  if (config2.enabled !== true) return null;
+  let store = overrides.store ?? null;
+  let indexer = overrides.indexer ?? null;
+  try {
+    store = store ?? new MemoryStore(path10.join(config2.wikiDir, "index.db"), config2);
+    if (!indexer) {
+      const embedder = new Embedder(config2.embeddingModel);
+      indexer = new MemoryIndexer(store, embedder, config2);
+    }
+    return new DefaultMemorySubsystem(config2, indexer, store, "initializing");
+  } catch (err) {
+    return new DefaultMemorySubsystem(config2, indexer, store, "failed", formatError3(err));
+  }
+}
+
 // src/services/digest/processor.ts
 import * as fs10 from "node:fs";
-import * as path13 from "node:path";
+import * as path14 from "node:path";
 
 // src/services/digest/constants.ts
-import * as path10 from "node:path";
+import * as path11 from "node:path";
 var DEFAULT_DIGEST_MODEL_ID = "base" /* BASE */;
 var DEFAULT_DIGEST_MAX_INPUT_CHARS = 1e4;
 var DEFAULT_DIGEST_TIMEOUT_MS = 12e4;
 var KIT_DIR = ".agent-kit";
-var WIKI_DIR = path10.join(KIT_DIR, "wiki");
-var WIKI_RAW_DIR = path10.join(WIKI_DIR, "raw");
-var PROVISIONAL_DIGEST_DIR = path10.join(WIKI_DIR, "compiled", "provisional", "conversation-digests");
-var DIGEST_WORKER_DIR = path10.join(WIKI_DIR, "digest");
-var DIGEST_LOCKFILE_REL_PATH = path10.join(DIGEST_WORKER_DIR, "digest-worker.lock");
-var DIGEST_WORKER_STATUS_REL_PATH = path10.join(DIGEST_WORKER_DIR, "digest-worker.status.json");
-var DIGEST_WORKER_LOG_REL_PATH = path10.join(DIGEST_WORKER_DIR, "digest-worker.log");
+var WIKI_DIR = path11.join(KIT_DIR, "wiki");
+var WIKI_RAW_DIR = path11.join(WIKI_DIR, "raw");
+var PROVISIONAL_DIGEST_DIR = path11.join(WIKI_DIR, "compiled", "provisional", "conversation-digests");
+var DIGEST_WORKER_DIR = path11.join(WIKI_DIR, "digest");
+var DIGEST_LOCKFILE_REL_PATH = path11.join(DIGEST_WORKER_DIR, "digest-worker.lock");
+var DIGEST_WORKER_STATUS_REL_PATH = path11.join(DIGEST_WORKER_DIR, "digest-worker.status.json");
+var DIGEST_WORKER_LOG_REL_PATH = path11.join(DIGEST_WORKER_DIR, "digest-worker.log");
 var LLAMA_CONTEXT_SIZE = 8192;
 var LLAMA_MAX_GENERATED_TOKENS = 512;
 var LLAMA_TEMPERATURE = 0.1;
 
 // src/services/digest/files.ts
 import * as fs8 from "node:fs";
-import * as path11 from "node:path";
+import * as path12 from "node:path";
 function defaultProvisionalDigestDir(workspaceRoot2) {
-  return path11.join(workspaceRoot2, PROVISIONAL_DIGEST_DIR);
+  return path12.join(workspaceRoot2, PROVISIONAL_DIGEST_DIR);
 }
 function readConversationDigestInput(workspaceRoot2, inputPath) {
-  const absoluteInput = path11.isAbsolute(inputPath) ? inputPath : path11.resolve(workspaceRoot2, inputPath);
+  const absoluteInput = path12.isAbsolute(inputPath) ? inputPath : path12.resolve(workspaceRoot2, inputPath);
   const content = fs8.readFileSync(absoluteInput, "utf8");
   return {
-    sourcePath: path11.relative(workspaceRoot2, absoluteInput),
+    sourcePath: path12.relative(workspaceRoot2, absoluteInput),
     content,
     contentHash: sha256Hex(content)
   };
 }
 function provisionalDigestPath(outDir, input) {
-  const safeName = path11.basename(input.sourcePath).replace(/\.[^.]+$/, "").replace(/[^a-z0-9._-]+/gi, "-");
-  return path11.join(outDir, `${input.contentHash.slice(0, 16)}-${safeName}.md`);
+  const safeName = path12.basename(input.sourcePath).replace(/\.[^.]+$/, "").replace(/[^a-z0-9._-]+/gi, "-");
+  return path12.join(outDir, `${input.contentHash.slice(0, 16)}-${safeName}.md`);
 }
 function findExistingProvisionalDigest(outDir, input) {
   const markdownPath = provisionalDigestPath(outDir, input);
@@ -37616,25 +37838,8 @@ function getDigestModelSpec(modelId) {
 
 // src/services/digest/providers/llama-local.ts
 import * as fs9 from "node:fs";
-import * as path12 from "node:path";
+import * as path13 from "node:path";
 import { getLlama, LlamaChatSession, createModelDownloader } from "node-llama-cpp";
-
-// src/utils/async.ts
-async function withTimeout(promise, timeoutMs, createError) {
-  let timer;
-  const timeout = new Promise((_resolve, reject) => {
-    timer = setTimeout(() => {
-      reject(createError());
-    }, timeoutMs);
-  });
-  try {
-    return await Promise.race([promise, timeout]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-
-// src/services/digest/providers/llama-local.ts
 var LlamaLocalDigestProviderError = class extends Error {
   constructor(message) {
     super(message);
@@ -37642,7 +37847,7 @@ var LlamaLocalDigestProviderError = class extends Error {
   }
 };
 function titleFromSource(sourcePath) {
-  return path12.basename(sourcePath).replace(/\.[^.]+$/, "").replace(/[_-]+/g, " ");
+  return path13.basename(sourcePath).replace(/\.[^.]+$/, "").replace(/[_-]+/g, " ");
 }
 function trimConversationExport(content, maxInputChars) {
   const trimmed = content.trim();
@@ -37685,7 +37890,7 @@ function sanitizeConversationDigestMarkdown(generatedText) {
 }
 async function createLlamaLocalDigestProvider(modelId) {
   const spec = getDigestModelSpec(modelId);
-  const modelCacheDir = path12.join(MODEL_CACHE_DIR, "llama");
+  const modelCacheDir = path13.join(MODEL_CACHE_DIR, "llama");
   fs9.mkdirSync(modelCacheDir, { recursive: true });
   let modelFilePath;
   try {
@@ -37754,13 +37959,13 @@ ${sanitized}`;
 
 // src/services/digest/processor.ts
 function digestLockPath(workspaceRoot2) {
-  return path13.join(workspaceRoot2, DIGEST_LOCKFILE_REL_PATH);
+  return path14.join(workspaceRoot2, DIGEST_LOCKFILE_REL_PATH);
 }
 function discoverPendingConversationFiles(workspaceRoot2) {
-  const rawDir = path13.join(workspaceRoot2, WIKI_RAW_DIR);
+  const rawDir = path14.join(workspaceRoot2, WIKI_RAW_DIR);
   let files;
   try {
-    files = fs10.readdirSync(rawDir).filter((f) => f.startsWith("conv_") && f.endsWith(".md")).map((f) => path13.join(rawDir, f)).sort((a, b) => fs10.statSync(a).mtimeMs - fs10.statSync(b).mtimeMs);
+    files = fs10.readdirSync(rawDir).filter((f) => f.startsWith("conv_") && f.endsWith(".md")).map((f) => path14.join(rawDir, f)).sort((a, b) => fs10.statSync(a).mtimeMs - fs10.statSync(b).mtimeMs);
   } catch (err) {
     if (err.code === "ENOENT") {
       files = [];
@@ -37788,7 +37993,7 @@ async function indexProvisionalDigestFile(workspaceRoot2, markdownPath, indexer)
     const settings = loadGlobalSettings();
     const config2 = resolveMemoryConfig(settings, workspaceRoot2);
     if (config2.enabled !== true) return { indexed: false };
-    store = new MemoryStore(path13.join(config2.wikiDir, "index.db"), config2);
+    store = new MemoryStore(path14.join(config2.wikiDir, "index.db"), config2);
     const embedder = new Embedder(config2.embeddingModel);
     await embedder.initialize();
     await new MemoryIndexer(store, embedder, config2).indexFile(markdownPath);
@@ -37800,7 +38005,7 @@ async function indexProvisionalDigestFile(workspaceRoot2, markdownPath, indexer)
   }
 }
 async function digestConversationFile(options) {
-  const outDir = options.outDir ? path13.resolve(options.workspaceRoot, options.outDir) : defaultProvisionalDigestDir(options.workspaceRoot);
+  const outDir = options.outDir ? path14.resolve(options.workspaceRoot, options.outDir) : defaultProvisionalDigestDir(options.workspaceRoot);
   const input = readConversationDigestInput(options.workspaceRoot, options.inputPath);
   const existingPath = findExistingProvisionalDigest(outDir, input);
   if (existingPath) {
@@ -37855,7 +38060,7 @@ async function digestPendingConversations({
     let indexer;
     const memoryConfig = resolveMemoryConfig(loadGlobalSettings(), workspaceRoot2);
     if (memoryConfig.enabled === true) {
-      const store = new MemoryStore(path13.join(memoryConfig.wikiDir, "index.db"), memoryConfig);
+      const store = new MemoryStore(path14.join(memoryConfig.wikiDir, "index.db"), memoryConfig);
       const embedder = new Embedder(memoryConfig.embeddingModel);
       indexer = new MemoryIndexer(store, embedder, memoryConfig);
       closeIndexer = () => store.close();
@@ -37936,7 +38141,8 @@ async function initializeConversationDigestModel(input) {
 }
 
 // src/mcp/memory.ts
-function registerMemoryToolHandlers(server2, indexer, store, config2, workspaceRoot2 = process.cwd()) {
+function registerMemoryToolHandlers(server2, subsystem, workspaceRoot2 = process.cwd()) {
+  const { config: config2 } = subsystem;
   server2.tool(
     "kit_memory_search",
     "Search persistent memory for factual or semantic matches (decisions, concepts, entities). Extract concise keywords only, removing stopwords and filler words from the user request before querying. Use kit_memory_recent for temporal or recency questions.",
@@ -37946,10 +38152,15 @@ function registerMemoryToolHandlers(server2, indexer, store, config2, workspaceR
     },
     async ({ query, top_k }) => {
       try {
+        if (!subsystem.indexer || !subsystem.store) {
+          return mcpText(formatInitializationFailure(subsystem));
+        }
+        const { indexer, store } = subsystem;
         const results = await indexer.search(query, top_k ?? config2.topK);
+        const lifecycleNote = formatLifecycleNote(subsystem);
         const degradedNote = !store.vecAvailable ? "\u26A0\uFE0F Vector search unavailable \u2014 showing keyword-only results.\n\n" : "";
         if (results.length === 0) {
-          return mcpText(`${degradedNote}No memories found for query: "${query}"`);
+          return mcpText(`${lifecycleNote}${degradedNote}No memories found for query: "${query}"`);
         }
         const formatted = results.map((r) => {
           const displaySource = r.chunk.source.replace(/^compiled\//, "");
@@ -37958,7 +38169,7 @@ ${r.chunk.content}` : r.chunk.content;
           return `### ${displaySource} (score: ${r.score.toFixed(3)})
 ${content}`;
         }).join("\n\n---\n\n");
-        return mcpText(`${degradedNote}${formatted}`);
+        return mcpText(`${lifecycleNote}${degradedNote}${formatted}`);
       } catch (err) {
         return mcpText(`kit_memory_search failed: ${formatError2(err)}`);
       }
@@ -37973,12 +38184,16 @@ ${content}`;
     },
     async ({ n, source_type }) => {
       try {
+        if (!subsystem.store) {
+          return mcpText(formatInitializationFailure(subsystem));
+        }
+        const store = subsystem.store;
         const rows = store.getRecentSources({ limit: n ?? 5, sourceType: source_type });
         if (rows.length === 0) return mcpText("No recent sources found.");
         const blocks = [];
         for (const row of rows) {
           try {
-            const content = fs11.readFileSync(path14.join(config2.wikiDir, row.source), "utf8");
+            const content = await fs11.promises.readFile(path15.join(config2.wikiDir, row.source), "utf8");
             const displaySource = row.source.replace(/^compiled\//, "");
             blocks.push(`### ${displaySource}
 ${content}`);
@@ -38001,6 +38216,13 @@ ${content}`);
     },
     async ({ content }) => {
       try {
+        if (!subsystem.indexer) {
+          return mcpJson({
+            saved: false,
+            error: formatInitializationFailure(subsystem)
+          });
+        }
+        const indexer = subsystem.indexer;
         await indexer.save(content);
         return mcpJson({
           saved: true,
@@ -38043,17 +38265,28 @@ ${content}`);
     }
   );
 }
+function formatLifecycleNote(subsystem) {
+  if (subsystem.status.state === "warming" || subsystem.status.state === "initializing") {
+    return "\u26A0\uFE0F Memory index is warming \u2014 results may be stale until startup indexing completes.\n\n";
+  }
+  if (subsystem.status.state === "degraded") {
+    return `\u26A0\uFE0F Memory index is degraded${subsystem.status.error ? `: ${subsystem.status.error}` : ""}.
+
+`;
+  }
+  return "";
+}
+function formatInitializationFailure(subsystem) {
+  const detail = subsystem.status.error ? `: ${subsystem.status.error}` : "";
+  return `Memory initialization failed${detail}`;
+}
 function registerMemoryTools(server2, workspaceRoot2, overrides) {
   const settings = overrides?.settings ?? loadGlobalSettings();
   if (settings.memory?.enabled !== true) return null;
-  const config2 = overrides?.config ?? resolveMemoryConfig(settings, workspaceRoot2);
-  const store = overrides?.store ?? new MemoryStore(path14.join(config2.wikiDir, "index.db"), config2);
-  const indexer = overrides?.indexer ?? (() => {
-    const embedder = new Embedder(config2.embeddingModel);
-    return new MemoryIndexer(store, embedder, config2);
-  })();
-  registerMemoryToolHandlers(server2, indexer, store, config2, workspaceRoot2);
-  return indexer;
+  const subsystem = createMemorySubsystem(workspaceRoot2, { ...overrides, settings });
+  if (!subsystem) return null;
+  registerMemoryToolHandlers(server2, subsystem, workspaceRoot2);
+  return subsystem;
 }
 
 // src/entrypoints/server.ts
@@ -38065,9 +38298,9 @@ registerIntegrationTools(server);
 registerCoreTools(server);
 registerAgentTools(server);
 var workspaceRoot = getWorkspaceRoot();
-var memoryIndexer = registerMemoryTools(server, workspaceRoot);
+var memorySubsystem = registerMemoryTools(server, workspaceRoot);
 var transport = new StdioServerTransport();
 await server.connect(transport);
-if (memoryIndexer) {
-  void memoryIndexer.startupIndex();
+if (memorySubsystem) {
+  void memorySubsystem.startWarmup();
 }