@diegoaltoworks/chatter 0.62.0 → 0.64.0

package/dist/index.mjs

@@ -393,6 +393,119 @@ var init_retrieval = __esm({
   }
 });
 
+// src/core/knowledgeHealth.ts
+var knowledgeHealth_exports = {};
+__export(knowledgeHealth_exports, {
+  DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS: () => DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS,
+  checkKnowledgeHealth: () => checkKnowledgeHealth,
+  scheduleKnowledgeHealthChecks: () => scheduleKnowledgeHealthChecks
+});
+async function checkKnowledgeHealth(db, logger) {
+  const [byBucket, totalChunksRes, totalEmbeddingsRes, orphanedRes, missingRes] = await Promise.all(
+    [
+      db.execute("SELECT bucket, COUNT(*) as count FROM chunks GROUP BY bucket"),
+      db.execute("SELECT COUNT(*) as count FROM chunks"),
+      db.execute("SELECT COUNT(*) as count FROM embeddings"),
+      db.execute(
+        "SELECT COUNT(*) as count FROM embeddings e LEFT JOIN chunks c ON c.id = e.id WHERE c.id IS NULL"
+      ),
+      db.execute(
+        "SELECT COUNT(*) as count FROM chunks c LEFT JOIN embeddings e ON e.id = c.id WHERE e.id IS NULL"
+      )
+    ]
+  );
+  const chunksByBucket = {};
+  for (const row of byBucket.rows) {
+    chunksByBucket[String(row.bucket)] = Number(row.count ?? 0);
+  }
+  const health = {
+    chunksByBucket,
+    totalChunks: Number(totalChunksRes.rows[0]?.count ?? 0),
+    totalEmbeddings: Number(totalEmbeddingsRes.rows[0]?.count ?? 0),
+    orphanedEmbeddings: Number(orphanedRes.rows[0]?.count ?? 0),
+    missingEmbeddings: Number(missingRes.rows[0]?.count ?? 0)
+  };
+  const summary = `chunksByBucket=${JSON.stringify(health.chunksByBucket)} totalChunks=${health.totalChunks} totalEmbeddings=${health.totalEmbeddings} orphanedEmbeddings=${health.orphanedEmbeddings} missingEmbeddings=${health.missingEmbeddings}`;
+  if (health.totalChunks === 0 || health.orphanedEmbeddings > 0) {
+    logger.warn(`Knowledge base health check: ${summary}`);
+  } else {
+    logger.info(`Knowledge base health check: ${summary}`);
+  }
+  return health;
+}
+async function cleanOrphanedEmbeddings(db, buildLock, instanceId, logger) {
+  const acquired = await buildLock.tryAcquire(
+    BUILD_LOCK_KEY,
+    instanceId,
+    Date.now(),
+    BUILD_LOCK_STALE_MS
+  );
+  if (!acquired) {
+    logger.warn(
+      "Knowledge health: skipping orphaned-embeddings cleanup - the build lock is held by another instance."
+    );
+    return;
+  }
+  try {
+    const result = await db.execute(
+      "DELETE FROM embeddings WHERE id NOT IN (SELECT id FROM chunks)"
+    );
+    if (result.rowsAffected > 0) {
+      logger.warn(`Knowledge health: deleted ${result.rowsAffected} orphaned embedding row(s).`);
+    }
+  } finally {
+    await buildLock.release(BUILD_LOCK_KEY, instanceId);
+  }
+}
+async function scheduleKnowledgeHealthChecks(options) {
+  const logger = options.logger ?? createConsoleLogger();
+  const enabled = options.config?.enabled !== false;
+  const intervalMs = options.config?.intervalMs ?? DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS;
+  const autoClean = options.config?.autoCleanOrphanedEmbeddings === true;
+  const buildLock = options.buildLock ?? createTursoBuildLock(options.db);
+  const instanceId = options.instanceId ?? crypto.randomUUID();
+  const schedule = options.schedule ?? defaultSchedule;
+  async function runOnce() {
+    const health = await checkKnowledgeHealth(options.db, logger);
+    if (autoClean && health.orphanedEmbeddings > 0) {
+      await cleanOrphanedEmbeddings(options.db, buildLock, instanceId, logger);
+    }
+    return health;
+  }
+  let handle;
+  if (enabled) {
+    await runOnce();
+    if (intervalMs > 0) {
+      let ticking = false;
+      handle = schedule(() => {
+        if (ticking) return;
+        ticking = true;
+        runOnce().catch((error) => logger.error("Knowledge health check failed:", error)).finally(() => {
+          ticking = false;
+        });
+      }, intervalMs);
+    }
+  }
+  return {
+    runOnce,
+    stop: () => handle?.stop()
+  };
+}
+var DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS, defaultSchedule;
+var init_knowledgeHealth = __esm({
+  "src/core/knowledgeHealth.ts"() {
+    "use strict";
+    init_buildLock();
+    init_logger();
+    DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS = 30 * 6e4;
+    defaultSchedule = (fn, ms) => {
+      const timer = setInterval(fn, ms);
+      if (typeof timer === "object" && "unref" in timer) timer.unref();
+      return { stop: () => clearInterval(timer) };
+    };
+  }
+});
+
 // src/auth/apikeys.ts
 import { randomUUID } from "node:crypto";
 import { jwtVerify, SignJWT } from "jose";
@@ -1146,6 +1259,7 @@ async function createMCPServer(config) {
   });
   const model = config.openai.model || DEFAULT_MODEL;
   let store;
+  let db;
   if (config.retriever) {
     store = config.retriever;
   } else {
@@ -1153,7 +1267,7 @@ async function createMCPServer(config) {
       throw new Error(DATABASE_CONFIG_REQUIRED_MESSAGE);
     }
     const { DEFAULT_KNOWLEDGE_DIR: DEFAULT_KNOWLEDGE_DIR2, VectorStore: VectorStore2, createOpenAIEmbedder: createOpenAIEmbedder2, openLibsqlClient: openLibsqlClient2 } = await Promise.resolve().then(() => (init_retrieval(), retrieval_exports));
-    const db = await openLibsqlClient2(config.database);
+    db = await openLibsqlClient2(config.database);
     store = new VectorStore2(createOpenAIEmbedder2(client), {
       databaseClient: db,
       knowledgeDir: config.knowledgeDir || DEFAULT_KNOWLEDGE_DIR2,
@@ -1162,6 +1276,15 @@ async function createMCPServer(config) {
   }
   await store.build?.();
   log.info("\u2705 Knowledge base ready");
+  let knowledgeHealth;
+  if (db) {
+    const { scheduleKnowledgeHealthChecks: scheduleKnowledgeHealthChecks2 } = await Promise.resolve().then(() => (init_knowledgeHealth(), knowledgeHealth_exports));
+    knowledgeHealth = await scheduleKnowledgeHealthChecks2({
+      db,
+      config: config.knowledgeHealthCheck,
+      logger: log
+    });
+  }
   const prompts = new PromptLoader(promptsDir, config.bot);
   const server = new McpServer({
     name: config.bot.name,
@@ -1358,7 +1481,9 @@ async function createMCPServer(config) {
   log.info(
     `\u2705 ${config.bot.name} MCP Server ready (transport: ${transportMode}, tools: ${enabledTools.join(", ") || "none"})`
   );
-  return server;
+  return Object.assign(server, {
+    stopKnowledgeHealthChecks: () => knowledgeHealth?.stop()
+  });
 }
 
 // src/middleware/apiKey.ts
@@ -2340,6 +2465,15 @@ async function createServer(config) {
   }
   await store.build?.();
   logger.info("\u2705 Knowledge base ready");
+  let knowledgeHealth;
+  if (db && !config.retriever) {
+    const { scheduleKnowledgeHealthChecks: scheduleKnowledgeHealthChecks2 } = await Promise.resolve().then(() => (init_knowledgeHealth(), knowledgeHealth_exports));
+    knowledgeHealth = await scheduleKnowledgeHealthChecks2({
+      db,
+      config: config.knowledgeHealthCheck,
+      logger
+    });
+  }
   const prompts = new PromptLoader(promptsDir, config.bot);
   let apiKeyManager;
   const secret = config.auth?.secret || process.env.CHATTER_SECRET;
@@ -2470,6 +2604,7 @@ async function createServer(config) {
     // (sync or async) is caught per-channel so one misbehaving channel can't
     // stop the rest from cleaning up.
     stopChannels: async () => {
+      knowledgeHealth?.stop();
       await Promise.allSettled(
         started.map(async (channel) => {
           try {

package/dist/mcp-server.d.ts

@@ -31,5 +31,7 @@ import type { MCPServerOptions } from "./mcp-server/types";
  * await server.connect(transport);
  * ```
  */
-export declare function createMCPServer(config: MCPServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+export declare function createMCPServer(config: MCPServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer & {
+    stopKnowledgeHealthChecks: () => void;
+}>;
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH,YAAY,EACV,WAAW,EACX,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,gBAAgB,qEA0T7D"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH,YAAY,EACV,WAAW,EACX,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,gBAAgB;qCA4U3B,IAAI;GAEtC"}

package/dist/mcp-server.js

@@ -411,6 +411,119 @@ var init_retrieval = __esm({
   }
 });
 
+// src/core/knowledgeHealth.ts
+var knowledgeHealth_exports = {};
+__export(knowledgeHealth_exports, {
+  DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS: () => DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS,
+  checkKnowledgeHealth: () => checkKnowledgeHealth,
+  scheduleKnowledgeHealthChecks: () => scheduleKnowledgeHealthChecks
+});
+async function checkKnowledgeHealth(db, logger) {
+  const [byBucket, totalChunksRes, totalEmbeddingsRes, orphanedRes, missingRes] = await Promise.all(
+    [
+      db.execute("SELECT bucket, COUNT(*) as count FROM chunks GROUP BY bucket"),
+      db.execute("SELECT COUNT(*) as count FROM chunks"),
+      db.execute("SELECT COUNT(*) as count FROM embeddings"),
+      db.execute(
+        "SELECT COUNT(*) as count FROM embeddings e LEFT JOIN chunks c ON c.id = e.id WHERE c.id IS NULL"
+      ),
+      db.execute(
+        "SELECT COUNT(*) as count FROM chunks c LEFT JOIN embeddings e ON e.id = c.id WHERE e.id IS NULL"
+      )
+    ]
+  );
+  const chunksByBucket = {};
+  for (const row of byBucket.rows) {
+    chunksByBucket[String(row.bucket)] = Number(row.count ?? 0);
+  }
+  const health = {
+    chunksByBucket,
+    totalChunks: Number(totalChunksRes.rows[0]?.count ?? 0),
+    totalEmbeddings: Number(totalEmbeddingsRes.rows[0]?.count ?? 0),
+    orphanedEmbeddings: Number(orphanedRes.rows[0]?.count ?? 0),
+    missingEmbeddings: Number(missingRes.rows[0]?.count ?? 0)
+  };
+  const summary = `chunksByBucket=${JSON.stringify(health.chunksByBucket)} totalChunks=${health.totalChunks} totalEmbeddings=${health.totalEmbeddings} orphanedEmbeddings=${health.orphanedEmbeddings} missingEmbeddings=${health.missingEmbeddings}`;
+  if (health.totalChunks === 0 || health.orphanedEmbeddings > 0) {
+    logger.warn(`Knowledge base health check: ${summary}`);
+  } else {
+    logger.info(`Knowledge base health check: ${summary}`);
+  }
+  return health;
+}
+async function cleanOrphanedEmbeddings(db, buildLock, instanceId, logger) {
+  const acquired = await buildLock.tryAcquire(
+    BUILD_LOCK_KEY,
+    instanceId,
+    Date.now(),
+    BUILD_LOCK_STALE_MS
+  );
+  if (!acquired) {
+    logger.warn(
+      "Knowledge health: skipping orphaned-embeddings cleanup - the build lock is held by another instance."
+    );
+    return;
+  }
+  try {
+    const result = await db.execute(
+      "DELETE FROM embeddings WHERE id NOT IN (SELECT id FROM chunks)"
+    );
+    if (result.rowsAffected > 0) {
+      logger.warn(`Knowledge health: deleted ${result.rowsAffected} orphaned embedding row(s).`);
+    }
+  } finally {
+    await buildLock.release(BUILD_LOCK_KEY, instanceId);
+  }
+}
+async function scheduleKnowledgeHealthChecks(options) {
+  const logger = options.logger ?? createConsoleLogger();
+  const enabled = options.config?.enabled !== false;
+  const intervalMs = options.config?.intervalMs ?? DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS;
+  const autoClean = options.config?.autoCleanOrphanedEmbeddings === true;
+  const buildLock = options.buildLock ?? createTursoBuildLock(options.db);
+  const instanceId = options.instanceId ?? crypto.randomUUID();
+  const schedule = options.schedule ?? defaultSchedule;
+  async function runOnce() {
+    const health = await checkKnowledgeHealth(options.db, logger);
+    if (autoClean && health.orphanedEmbeddings > 0) {
+      await cleanOrphanedEmbeddings(options.db, buildLock, instanceId, logger);
+    }
+    return health;
+  }
+  let handle;
+  if (enabled) {
+    await runOnce();
+    if (intervalMs > 0) {
+      let ticking = false;
+      handle = schedule(() => {
+        if (ticking) return;
+        ticking = true;
+        runOnce().catch((error) => logger.error("Knowledge health check failed:", error)).finally(() => {
+          ticking = false;
+        });
+      }, intervalMs);
+    }
+  }
+  return {
+    runOnce,
+    stop: () => handle?.stop()
+  };
+}
+var DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS, defaultSchedule;
+var init_knowledgeHealth = __esm({
+  "src/core/knowledgeHealth.ts"() {
+    "use strict";
+    init_buildLock();
+    init_logger();
+    DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS = 30 * 6e4;
+    defaultSchedule = (fn, ms) => {
+      const timer = setInterval(fn, ms);
+      if (typeof timer === "object" && "unref" in timer) timer.unref();
+      return { stop: () => clearInterval(timer) };
+    };
+  }
+});
+
 // src/mcp-server.ts
 var mcp_server_exports = {};
 __export(mcp_server_exports, {
@@ -899,6 +1012,7 @@ async function createMCPServer(config) {
   });
   const model = config.openai.model || DEFAULT_MODEL;
   let store;
+  let db;
   if (config.retriever) {
     store = config.retriever;
   } else {
@@ -906,7 +1020,7 @@ async function createMCPServer(config) {
       throw new Error(DATABASE_CONFIG_REQUIRED_MESSAGE);
     }
     const { DEFAULT_KNOWLEDGE_DIR: DEFAULT_KNOWLEDGE_DIR2, VectorStore: VectorStore2, createOpenAIEmbedder: createOpenAIEmbedder2, openLibsqlClient: openLibsqlClient2 } = await Promise.resolve().then(() => (init_retrieval(), retrieval_exports));
-    const db = await openLibsqlClient2(config.database);
+    db = await openLibsqlClient2(config.database);
     store = new VectorStore2(createOpenAIEmbedder2(client), {
       databaseClient: db,
       knowledgeDir: config.knowledgeDir || DEFAULT_KNOWLEDGE_DIR2,
@@ -915,6 +1029,15 @@ async function createMCPServer(config) {
   }
   await store.build?.();
   log.info("\u2705 Knowledge base ready");
+  let knowledgeHealth;
+  if (db) {
+    const { scheduleKnowledgeHealthChecks: scheduleKnowledgeHealthChecks2 } = await Promise.resolve().then(() => (init_knowledgeHealth(), knowledgeHealth_exports));
+    knowledgeHealth = await scheduleKnowledgeHealthChecks2({
+      db,
+      config: config.knowledgeHealthCheck,
+      logger: log
+    });
+  }
   const prompts = new PromptLoader(promptsDir, config.bot);
   const server = new McpServer({
     name: config.bot.name,
@@ -1111,7 +1234,9 @@ async function createMCPServer(config) {
   log.info(
     `\u2705 ${config.bot.name} MCP Server ready (transport: ${transportMode}, tools: ${enabledTools.join(", ") || "none"})`
   );
-  return server;
+  return Object.assign(server, {
+    stopKnowledgeHealthChecks: () => knowledgeHealth?.stop()
+  });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/mcp-server.mjs

@@ -388,6 +388,119 @@ var init_retrieval = __esm({
   }
 });
 
+// src/core/knowledgeHealth.ts
+var knowledgeHealth_exports = {};
+__export(knowledgeHealth_exports, {
+  DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS: () => DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS,
+  checkKnowledgeHealth: () => checkKnowledgeHealth,
+  scheduleKnowledgeHealthChecks: () => scheduleKnowledgeHealthChecks
+});
+async function checkKnowledgeHealth(db, logger) {
+  const [byBucket, totalChunksRes, totalEmbeddingsRes, orphanedRes, missingRes] = await Promise.all(
+    [
+      db.execute("SELECT bucket, COUNT(*) as count FROM chunks GROUP BY bucket"),
+      db.execute("SELECT COUNT(*) as count FROM chunks"),
+      db.execute("SELECT COUNT(*) as count FROM embeddings"),
+      db.execute(
+        "SELECT COUNT(*) as count FROM embeddings e LEFT JOIN chunks c ON c.id = e.id WHERE c.id IS NULL"
+      ),
+      db.execute(
+        "SELECT COUNT(*) as count FROM chunks c LEFT JOIN embeddings e ON e.id = c.id WHERE e.id IS NULL"
+      )
+    ]
+  );
+  const chunksByBucket = {};
+  for (const row of byBucket.rows) {
+    chunksByBucket[String(row.bucket)] = Number(row.count ?? 0);
+  }
+  const health = {
+    chunksByBucket,
+    totalChunks: Number(totalChunksRes.rows[0]?.count ?? 0),
+    totalEmbeddings: Number(totalEmbeddingsRes.rows[0]?.count ?? 0),
+    orphanedEmbeddings: Number(orphanedRes.rows[0]?.count ?? 0),
+    missingEmbeddings: Number(missingRes.rows[0]?.count ?? 0)
+  };
+  const summary = `chunksByBucket=${JSON.stringify(health.chunksByBucket)} totalChunks=${health.totalChunks} totalEmbeddings=${health.totalEmbeddings} orphanedEmbeddings=${health.orphanedEmbeddings} missingEmbeddings=${health.missingEmbeddings}`;
+  if (health.totalChunks === 0 || health.orphanedEmbeddings > 0) {
+    logger.warn(`Knowledge base health check: ${summary}`);
+  } else {
+    logger.info(`Knowledge base health check: ${summary}`);
+  }
+  return health;
+}
+async function cleanOrphanedEmbeddings(db, buildLock, instanceId, logger) {
+  const acquired = await buildLock.tryAcquire(
+    BUILD_LOCK_KEY,
+    instanceId,
+    Date.now(),
+    BUILD_LOCK_STALE_MS
+  );
+  if (!acquired) {
+    logger.warn(
+      "Knowledge health: skipping orphaned-embeddings cleanup - the build lock is held by another instance."
+    );
+    return;
+  }
+  try {
+    const result = await db.execute(
+      "DELETE FROM embeddings WHERE id NOT IN (SELECT id FROM chunks)"
+    );
+    if (result.rowsAffected > 0) {
+      logger.warn(`Knowledge health: deleted ${result.rowsAffected} orphaned embedding row(s).`);
+    }
+  } finally {
+    await buildLock.release(BUILD_LOCK_KEY, instanceId);
+  }
+}
+async function scheduleKnowledgeHealthChecks(options) {
+  const logger = options.logger ?? createConsoleLogger();
+  const enabled = options.config?.enabled !== false;
+  const intervalMs = options.config?.intervalMs ?? DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS;
+  const autoClean = options.config?.autoCleanOrphanedEmbeddings === true;
+  const buildLock = options.buildLock ?? createTursoBuildLock(options.db);
+  const instanceId = options.instanceId ?? crypto.randomUUID();
+  const schedule = options.schedule ?? defaultSchedule;
+  async function runOnce() {
+    const health = await checkKnowledgeHealth(options.db, logger);
+    if (autoClean && health.orphanedEmbeddings > 0) {
+      await cleanOrphanedEmbeddings(options.db, buildLock, instanceId, logger);
+    }
+    return health;
+  }
+  let handle;
+  if (enabled) {
+    await runOnce();
+    if (intervalMs > 0) {
+      let ticking = false;
+      handle = schedule(() => {
+        if (ticking) return;
+        ticking = true;
+        runOnce().catch((error) => logger.error("Knowledge health check failed:", error)).finally(() => {
+          ticking = false;
+        });
+      }, intervalMs);
+    }
+  }
+  return {
+    runOnce,
+    stop: () => handle?.stop()
+  };
+}
+var DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS, defaultSchedule;
+var init_knowledgeHealth = __esm({
+  "src/core/knowledgeHealth.ts"() {
+    "use strict";
+    init_buildLock();
+    init_logger();
+    DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS = 30 * 6e4;
+    defaultSchedule = (fn, ms) => {
+      const timer = setInterval(fn, ms);
+      if (typeof timer === "object" && "unref" in timer) timer.unref();
+      return { stop: () => clearInterval(timer) };
+    };
+  }
+});
+
 // src/mcp-server.ts
 import OpenAI from "openai";
 
@@ -871,6 +984,7 @@ async function createMCPServer(config) {
   });
   const model = config.openai.model || DEFAULT_MODEL;
   let store;
+  let db;
   if (config.retriever) {
     store = config.retriever;
   } else {
@@ -878,7 +992,7 @@ async function createMCPServer(config) {
       throw new Error(DATABASE_CONFIG_REQUIRED_MESSAGE);
     }
     const { DEFAULT_KNOWLEDGE_DIR: DEFAULT_KNOWLEDGE_DIR2, VectorStore: VectorStore2, createOpenAIEmbedder: createOpenAIEmbedder2, openLibsqlClient: openLibsqlClient2 } = await Promise.resolve().then(() => (init_retrieval(), retrieval_exports));
-    const db = await openLibsqlClient2(config.database);
+    db = await openLibsqlClient2(config.database);
     store = new VectorStore2(createOpenAIEmbedder2(client), {
       databaseClient: db,
       knowledgeDir: config.knowledgeDir || DEFAULT_KNOWLEDGE_DIR2,
@@ -887,6 +1001,15 @@ async function createMCPServer(config) {
   }
   await store.build?.();
   log.info("\u2705 Knowledge base ready");
+  let knowledgeHealth;
+  if (db) {
+    const { scheduleKnowledgeHealthChecks: scheduleKnowledgeHealthChecks2 } = await Promise.resolve().then(() => (init_knowledgeHealth(), knowledgeHealth_exports));
+    knowledgeHealth = await scheduleKnowledgeHealthChecks2({
+      db,
+      config: config.knowledgeHealthCheck,
+      logger: log
+    });
+  }
   const prompts = new PromptLoader(promptsDir, config.bot);
   const server = new McpServer({
     name: config.bot.name,
@@ -1083,7 +1206,9 @@ async function createMCPServer(config) {
   log.info(
     `\u2705 ${config.bot.name} MCP Server ready (transport: ${transportMode}, tools: ${enabledTools.join(", ") || "none"})`
   );
-  return server;
+  return Object.assign(server, {
+    stopKnowledgeHealthChecks: () => knowledgeHealth?.stop()
+  });
 }
 export {
   createMCPServer

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAgB5B,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,SAAS,CAAC;AAEjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG;IAAE,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAEtE;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAiP7E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAiB5B,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,SAAS,CAAC;AAEjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG;IAAE,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAEtE;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CA+P7E"}

package/dist/server.js

@@ -411,6 +411,119 @@ var init_retrieval = __esm({
   }
 });
 
+// src/core/knowledgeHealth.ts
+var knowledgeHealth_exports = {};
+__export(knowledgeHealth_exports, {
+  DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS: () => DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS,
+  checkKnowledgeHealth: () => checkKnowledgeHealth,
+  scheduleKnowledgeHealthChecks: () => scheduleKnowledgeHealthChecks
+});
+async function checkKnowledgeHealth(db, logger) {
+  const [byBucket, totalChunksRes, totalEmbeddingsRes, orphanedRes, missingRes] = await Promise.all(
+    [
+      db.execute("SELECT bucket, COUNT(*) as count FROM chunks GROUP BY bucket"),
+      db.execute("SELECT COUNT(*) as count FROM chunks"),
+      db.execute("SELECT COUNT(*) as count FROM embeddings"),
+      db.execute(
+        "SELECT COUNT(*) as count FROM embeddings e LEFT JOIN chunks c ON c.id = e.id WHERE c.id IS NULL"
+      ),
+      db.execute(
+        "SELECT COUNT(*) as count FROM chunks c LEFT JOIN embeddings e ON e.id = c.id WHERE e.id IS NULL"
+      )
+    ]
+  );
+  const chunksByBucket = {};
+  for (const row of byBucket.rows) {
+    chunksByBucket[String(row.bucket)] = Number(row.count ?? 0);
+  }
+  const health = {
+    chunksByBucket,
+    totalChunks: Number(totalChunksRes.rows[0]?.count ?? 0),
+    totalEmbeddings: Number(totalEmbeddingsRes.rows[0]?.count ?? 0),
+    orphanedEmbeddings: Number(orphanedRes.rows[0]?.count ?? 0),
+    missingEmbeddings: Number(missingRes.rows[0]?.count ?? 0)
+  };
+  const summary = `chunksByBucket=${JSON.stringify(health.chunksByBucket)} totalChunks=${health.totalChunks} totalEmbeddings=${health.totalEmbeddings} orphanedEmbeddings=${health.orphanedEmbeddings} missingEmbeddings=${health.missingEmbeddings}`;
+  if (health.totalChunks === 0 || health.orphanedEmbeddings > 0) {
+    logger.warn(`Knowledge base health check: ${summary}`);
+  } else {
+    logger.info(`Knowledge base health check: ${summary}`);
+  }
+  return health;
+}
+async function cleanOrphanedEmbeddings(db, buildLock, instanceId, logger) {
+  const acquired = await buildLock.tryAcquire(
+    BUILD_LOCK_KEY,
+    instanceId,
+    Date.now(),
+    BUILD_LOCK_STALE_MS
+  );
+  if (!acquired) {
+    logger.warn(
+      "Knowledge health: skipping orphaned-embeddings cleanup - the build lock is held by another instance."
+    );
+    return;
+  }
+  try {
+    const result = await db.execute(
+      "DELETE FROM embeddings WHERE id NOT IN (SELECT id FROM chunks)"
+    );
+    if (result.rowsAffected > 0) {
+      logger.warn(`Knowledge health: deleted ${result.rowsAffected} orphaned embedding row(s).`);
+    }
+  } finally {
+    await buildLock.release(BUILD_LOCK_KEY, instanceId);
+  }
+}
+async function scheduleKnowledgeHealthChecks(options) {
+  const logger = options.logger ?? createConsoleLogger();
+  const enabled = options.config?.enabled !== false;
+  const intervalMs = options.config?.intervalMs ?? DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS;
+  const autoClean = options.config?.autoCleanOrphanedEmbeddings === true;
+  const buildLock = options.buildLock ?? createTursoBuildLock(options.db);
+  const instanceId = options.instanceId ?? crypto.randomUUID();
+  const schedule = options.schedule ?? defaultSchedule;
+  async function runOnce() {
+    const health = await checkKnowledgeHealth(options.db, logger);
+    if (autoClean && health.orphanedEmbeddings > 0) {
+      await cleanOrphanedEmbeddings(options.db, buildLock, instanceId, logger);
+    }
+    return health;
+  }
+  let handle;
+  if (enabled) {
+    await runOnce();
+    if (intervalMs > 0) {
+      let ticking = false;
+      handle = schedule(() => {
+        if (ticking) return;
+        ticking = true;
+        runOnce().catch((error) => logger.error("Knowledge health check failed:", error)).finally(() => {
+          ticking = false;
+        });
+      }, intervalMs);
+    }
+  }
+  return {
+    runOnce,
+    stop: () => handle?.stop()
+  };
+}
+var DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS, defaultSchedule;
+var init_knowledgeHealth = __esm({
+  "src/core/knowledgeHealth.ts"() {
+    "use strict";
+    init_buildLock();
+    init_logger();
+    DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS = 30 * 6e4;
+    defaultSchedule = (fn, ms) => {
+      const timer = setInterval(fn, ms);
+      if (typeof timer === "object" && "unref" in timer) timer.unref();
+      return { stop: () => clearInterval(timer) };
+    };
+  }
+});
+
 // src/server.ts
 var server_exports = {};
 __export(server_exports, {
@@ -1891,6 +2004,15 @@ async function createServer(config) {
   }
   await store.build?.();
   logger.info("\u2705 Knowledge base ready");
+  let knowledgeHealth;
+  if (db && !config.retriever) {
+    const { scheduleKnowledgeHealthChecks: scheduleKnowledgeHealthChecks2 } = await Promise.resolve().then(() => (init_knowledgeHealth(), knowledgeHealth_exports));
+    knowledgeHealth = await scheduleKnowledgeHealthChecks2({
+      db,
+      config: config.knowledgeHealthCheck,
+      logger
+    });
+  }
   const prompts = new PromptLoader(promptsDir, config.bot);
   let apiKeyManager;
   const secret = config.auth?.secret || process.env.CHATTER_SECRET;
@@ -2021,6 +2143,7 @@ async function createServer(config) {
     // (sync or async) is caught per-channel so one misbehaving channel can't
     // stop the rest from cleaning up.
     stopChannels: async () => {
+      knowledgeHealth?.stop();
       await Promise.allSettled(
         started.map(async (channel) => {
           try {