@betterdb/memory 0.1.2 → 0.4.0

package/src/hooks/session-end.ts

@@ -1,5 +1,6 @@
 import { readRawPayload, runHook } from "./_utils.js";
 import { getValkeyClient } from "../client/valkey.js";
+import { getPluginMemoryStore } from "../client/memory-store.js";
 import { createModelClient } from "../client/model.js";
 import {
   SessionCapture,
@@ -8,7 +9,7 @@ import {
   getCwdProject,
 } from "../memory/capture.js";
 import { SessionEventSchema, type EpisodicMemory } from "../memory/schema.js";
-import { config } from "../config.js";
+import { config, isConfigured } from "../config.js";
 import { unlink } from "node:fs/promises";
 
 /**
@@ -25,6 +26,7 @@ import { unlink } from "node:fs/promises";
  * 3. If model client is unavailable, queue for later processing
  */
 runHook(async () => {
+  if (!isConfigured()) return;
   const payload = await readRawPayload();
   const sessionId = payload["session_id"] as string;
   const cwd = (payload["cwd"] as string) ?? process.cwd();
@@ -77,7 +79,14 @@ runHook(async () => {
       transcript.slice(-half);
   }
 
-  const valkeyClient = await getValkeyClient();
+  let valkeyClient;
+  try {
+    valkeyClient = await getValkeyClient();
+  } catch {
+    await cleanup(eventFilePath);
+    return; // Valkey unreachable — skip silently
+  }
+
   const project = getCwdProject();
   const branch = getGitBranch();
 
@@ -102,7 +111,6 @@ runHook(async () => {
 
   const summary = await modelClient.summarize(transcript);
   const importance = computeInitialImportance(summary);
-  const embedding = await modelClient.embed(summary.oneLineSummary);
 
   const memory: EpisodicMemory = {
     memoryId: crypto.randomUUID(),
@@ -115,7 +123,9 @@ runHook(async () => {
     lastAccessed: new Date().toISOString(),
   };
 
-  await valkeyClient.storeMemory(memory, embedding);
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.storeMemory(memory);
+  await store.close();
   await valkeyClient.quit();
   await cleanup(eventFilePath);
 });

package/src/hooks/session-start.ts

@@ -1,9 +1,10 @@
 import { readRawPayload, runHook } from "./_utils.js";
-import { getValkeyClient } from "../client/valkey.js";
+import { getPluginMemoryStore } from "../client/memory-store.js";
 import { createModelClient } from "../client/model.js";
-import { SessionCapture } from "../memory/capture.js";
-import { MemoryRetriever, formatForInjection } from "../memory/retrieval.js";
-import { config } from "../config.js";
+import { SessionCapture, getGitBranch } from "../memory/capture.js";
+import { formatForInjection } from "../memory/retrieval.js";
+import { escalatingRecall } from "../memory/recall.js";
+import { config, isConfigured } from "../config.js";
 
 /**
  * SessionStart hook: Retrieves relevant memories and injects context.
@@ -14,6 +15,13 @@ import { config } from "../config.js";
  * - Exit 0 for success
  */
 runHook(async () => {
+  if (!isConfigured()) {
+    process.stdout.write(
+      "[BetterDB Memory] Not configured yet. Run /betterdb-memory:setup to connect to Valkey.\n",
+    );
+    return;
+  }
+
   const payload = await readRawPayload();
   const cwd = (payload["cwd"] as string) ?? process.cwd();
 
@@ -21,15 +29,32 @@ runHook(async () => {
     process.chdir(cwd);
   }
 
-  const valkeyClient = await getValkeyClient();
   const modelClient = await createModelClient();
 
+  let store;
+  try {
+    store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  } catch {
+    return; // Valkey unreachable — skip silently
+  }
+
   const capture = new SessionCapture();
   const queryContext = await capture.getQueryContext();
 
-  const retriever = new MemoryRetriever(valkeyClient, modelClient);
   const project = queryContext.split("\n")[0]?.replace("Project: ", "") ?? "unknown";
-  const memories = await retriever.retrieve(queryContext, project);
+  const branch = getGitBranch();
+  // Project+branch-scoped, threshold-gated recall (no cross-project auto-inject
+  // at startup — nothing to consent to yet). Only memories clearing the
+  // relevance bar are injected, so we stop padding context with irrelevant
+  // top-N filler.
+  const result = await escalatingRecall(store, queryContext, {
+    project,
+    ...(branch !== "unknown" ? { branch } : {}),
+    crossProjectRequested: false,
+  });
+  const memories = result.hits
+    .slice(0, config.memory.maxContextMemories)
+    .map((h) => h.memory);
 
   if (memories.length > 0) {
     const formatted = formatForInjection(memories);
@@ -39,5 +64,5 @@ runHook(async () => {
     process.stdout.write(formatted);
   }
 
-  await valkeyClient.quit();
+  await store.close();
 });

package/src/index.ts

@@ -13,7 +13,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 
-const VERSION = "0.1.0";
+const VERSION = "0.4.0";
 const HOME = process.env["HOME"] ?? process.env["USERPROFILE"] ?? "";
 const BETTERDB_DIR = join(HOME, ".betterdb");
 const BIN_DIR = join(BETTERDB_DIR, "bin");
@@ -36,11 +36,19 @@ Usage:
   betterdb-memory <command>
 
 Commands:
-  install     Compile binaries, register hooks + MCP server
-  uninstall   Remove hooks, MCP server, and compiled binaries
-  status      Check health of Valkey and model providers
-  maintain    Run aging/compression pipeline manually
-  version     Print version
+  install          Compile binaries, register hooks + MCP server
+  uninstall        Remove hooks, MCP server, and compiled binaries
+  status           Check health of Valkey and model providers
+  maintain         Run aging/consolidation pipeline manually
+  forget           Bulk-delete memories by scope (dry run; pass --apply)
+                   Flags: --project <name> (default: cwd) | --all-projects
+                          --branch <name> --tags <a,b> --apply
+  migrate          Move legacy betterdb:memory:* memories into the MemoryStore
+                   (dry run; pass --apply to perform)
+  ingest-claude-md Ingest a CLAUDE.md / MEMORY.md file into the store [path]
+  setup-index      Create the episodic vector index (recovery after install)
+  docker-valkey    Manage Docker Valkey container [start|stop|status|remove]
+  version          Print version
 
 Environment:
   BETTERDB_VALKEY_URL   Valkey connection (default: redis://localhost:6379)
@@ -63,6 +71,28 @@ switch (command) {
   case "maintain":
     await runMaintain();
     break;
+  case "forget":
+    await runForget(process.argv.slice(3));
+    break;
+  case "migrate":
+    await runMigrate(process.argv.includes("--apply"));
+    break;
+  case "ingest-claude-md":
+    await runIngestClaudeMd(process.argv[3]);
+    break;
+  case "setup-index":
+    await runSetupIndex();
+    break;
+  case "docker-valkey": {
+    const action = process.argv[3] ?? "start";
+    const port = process.argv[4] ?? "6379";
+    const script = join(PKG_ROOT, "scripts", "docker-valkey.sh");
+    const result = Bun.spawnSync(["bash", script, port, action]);
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
+    break;
+  }
   case "version":
   case "--version":
   case "-v":
@@ -175,12 +205,14 @@ async function runInstall() {
     }
   }
 
-  settings["hooks"] = {
+  const existingHooks = (settings["hooks"] ?? {}) as Record<string, unknown[]>;
+  const betterdbHooks: Record<string, unknown[]> = {
     SessionStart: [{ hooks: [{ type: "command", command: join(BIN_DIR, "session-start") }] }],
     PreToolUse: [{ matcher: "", hooks: [{ type: "command", command: join(BIN_DIR, "pre-tool") }] }],
     PostToolUse: [{ matcher: "", hooks: [{ type: "command", command: join(BIN_DIR, "post-tool") }] }],
     Stop: [{ hooks: [{ type: "command", command: join(BIN_DIR, "session-end") }] }],
   };
+  settings["hooks"] = mergeHooks(existingHooks, betterdbHooks);
 
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   console.log("  Registered 4 hooks in ~/.claude/settings.json");
@@ -202,10 +234,16 @@ async function runInstall() {
   console.log("\nSetting up Valkey index...");
   try {
     const { getValkeyClient } = await import("./client/valkey.js");
-    const embedDim = Number(Bun.env["BETTERDB_EMBED_DIM"] ?? readConfigValue("BETTERDB_EMBED_DIM") ?? "1024");
+    const { getPluginMemoryStore } = await import("./client/memory-store.js");
+    const { createModelClient } = await import("./client/model.js");
     const client = await getValkeyClient();
-    await client.ensureIndex(embedDim);
+    const modelClient = await createModelClient();
+    // Record the active provider/dimension so a later provider swap is caught.
+    await client.assertEmbedDim(modelClient.embedDim, modelClient.preset.embedModel);
+    const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+    await store.ensureIndex();
     console.log("  Valkey index ready");
+    await store.close();
     await client.quit();
   } catch (err) {
     console.log(`  WARNING: Index setup failed (${err instanceof Error ? err.message : String(err)})`);
@@ -318,9 +356,19 @@ async function runStatus() {
   try {
     const { config } = await import("./config.js");
     const { getValkeyClient } = await import("./client/valkey.js");
+    const { getPluginMemoryStore } = await import("./client/memory-store.js");
     const client = await getValkeyClient();
-    const memoryIds = await client.listMemoryIds();
-    console.log(`OK (${memoryIds.length} memories, ${config.valkey.url})`);
+    const store = await getPluginMemoryStore();
+    const stats = await store.stats();
+    console.log(`OK (${stats.itemCount} memories, ${config.valkey.url})`);
+    const w = stats.config.weights;
+    const halfLifeDays = Math.round(stats.config.halfLifeSeconds / 86400);
+    console.log(
+      `  Recall scoring: half-life ${halfLifeDays}d · ` +
+        `weights sim/rec/imp ${w.similarity}/${w.recency}/${w.importance}` +
+        (stats.evictions > 0 ? ` · ${stats.evictions} evictions` : ""),
+    );
+    await store.close();
     await client.quit();
   } catch (err) {
     console.log(`FAILED (${err instanceof Error ? err.message : String(err)})`);
@@ -364,6 +412,30 @@ async function runStatus() {
     console.log("FAILED (could not read settings)");
   }
 
+  // Check Docker container (only if config has "docker": true)
+  const dockerFlag = readConfigValue("docker");
+  if (dockerFlag === "true") {
+    process.stdout.write("Docker container... ");
+    const script = join(PKG_ROOT, "scripts", "docker-valkey.sh");
+    if (existsSync(script)) {
+      const result = Bun.spawnSync(["bash", script, "6379", "status"]);
+      const output = result.stdout.toString().trim();
+      if (output.includes("is running")) {
+        const portMatch = output.match(/port (\d+)/);
+        console.log(`OK (betterdb-valkey, running, port ${portMatch?.[1] ?? "unknown"})`);
+      } else if (output.includes("stopped")) {
+        console.log(`STOPPED (run: bunx @betterdb/memory docker-valkey)`);
+      } else {
+        console.log(`NOT FOUND (run: bunx @betterdb/memory docker-valkey)`);
+      }
+    } else {
+      console.log("SCRIPT MISSING (docker-valkey.sh not found)");
+    }
+  } else {
+    process.stdout.write("Docker container... ");
+    console.log("NOT USED (Valkey managed externally)");
+  }
+
   // Check config file
   process.stdout.write("Config file... ");
   if (existsSync(CONFIG_PATH)) {
@@ -381,30 +453,292 @@ async function runMaintain() {
   console.log("BetterDB Memory for Claude Code — Maintenance\n");
 
   const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
   const { createModelClient } = await import("./client/model.js");
   const { AgingPipeline } = await import("./memory/aging.js");
 
   const valkeyClient = await getValkeyClient();
   const modelClient = await createModelClient();
-  const pipeline = new AgingPipeline(valkeyClient, modelClient);
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  const pipeline = new AgingPipeline(valkeyClient, store, modelClient);
+
+  const memories = await store.listMemories();
+  console.log(`Total memories: ${memories.length}`);
+
+  await pipeline.runFullPipeline();
+
+  console.log("\nAging pipeline complete.");
+  await store.close();
+  await valkeyClient.quit();
+}
+
+// ---------------------------------------------------------------------------
+// forget (bulk delete by scope: project / branch / tags)
+// ---------------------------------------------------------------------------
+
+async function runForget(argv: string[]) {
+  console.log("BetterDB Memory for Claude Code — Forget by scope\n");
+
+  const flag = (name: string): string | undefined => {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const apply = argv.includes("--apply");
+  const allProjects = argv.includes("--all-projects");
+  const branch = flag("branch");
+  const tags = flag("tags")?.split(",").map((t) => t.trim()).filter(Boolean);
+
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { getCwdProject } = await import("./memory/capture.js");
+
+  const project = allProjects ? undefined : (flag("project") ?? getCwdProject());
+
+  // Refuse an unbounded delete: --all-projects must be narrowed by branch/tags.
+  if (project === undefined && branch === undefined && (!tags || tags.length === 0)) {
+    console.error("Refusing to delete every memory. Narrow --all-projects with --branch or --tags.");
+    process.exit(1);
+  }
+
+  const scopeDesc = [
+    project !== undefined ? `project=${project}` : "all projects",
+    branch !== undefined ? `branch=${branch}` : null,
+    tags && tags.length > 0 ? `tags=${tags.join(",")}` : null,
+  ].filter(Boolean).join(", ");
+  console.log(`Scope: ${scopeDesc}`);
+
+  const valkeyClient = await getValkeyClient();
+  const store = await getPluginMemoryStore();
+
+  const scope = {
+    ...(project !== undefined ? { project } : {}),
+    ...(branch !== undefined ? { branch } : {}),
+    ...(tags && tags.length > 0 ? { tags } : {}),
+  };
+
+  // Preview through the SAME native scope filter forgetByScope deletes with, so
+  // the dry-run count is exactly what --apply will remove (older memories
+  // without native tags are matched identically by both paths).
+  const candidates = await store.listByScope(scope);
+
+  console.log(`Matched ${candidates.length} memories.`);
+  for (const m of candidates.slice(0, 5)) {
+    console.log(`  - [${m.branch}] ${m.summary.oneLineSummary.slice(0, 70)}`);
+  }
+  if (candidates.length > 5) console.log(`  ... and ${candidates.length - 5} more`);
+
+  if (!apply) {
+    console.log("\nDry run — re-run with --apply to delete.");
+    await store.close();
+    await valkeyClient.quit();
+    return;
+  }
+
+  const deleted = await store.forgetByScope(scope);
+  console.log(`\nDeleted ${deleted} memories.`);
+
+  await store.close();
+  await valkeyClient.quit();
+}
+
+// ---------------------------------------------------------------------------
+// setup-index (recovery path: build the MemoryStore episodic vector index)
+// ---------------------------------------------------------------------------
+
+async function runSetupIndex() {
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { createModelClient } = await import("./client/model.js");
+
+  const client = await getValkeyClient();
+  const modelClient = await createModelClient();
+  // Record the active provider/dimension so a later provider swap is caught.
+  await client.assertEmbedDim(modelClient.embedDim, modelClient.preset.embedModel);
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.ensureIndex();
+  console.log("Index ready: betterdb:mem:idx");
+
+  await store.close();
+  await client.quit();
+}
+
+// ---------------------------------------------------------------------------
+// migrate (legacy betterdb:memory:* -> MemoryStore betterdb:mem:*)
+// ---------------------------------------------------------------------------
+
+async function runMigrate(apply: boolean) {
+  console.log("BetterDB Memory for Claude Code — Migrate legacy memories\n");
 
-  const memoryIds = await valkeyClient.listMemoryIds();
-  console.log(`Total memories: ${memoryIds.length}`);
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { createModelClient } = await import("./client/model.js");
 
-  // Group by project
+  const valkeyClient = await getValkeyClient();
+  const legacyIds = await valkeyClient.listMemoryIds();
+  console.log(`Found ${legacyIds.length} legacy memories under betterdb:memory:*`);
+
+  if (legacyIds.length === 0) {
+    console.log("Nothing to migrate.");
+    await valkeyClient.quit();
+    return;
+  }
+
+  if (!apply) {
+    console.log("\nDry run — re-run with --apply to migrate.");
+    console.log("Each legacy memory is re-embedded and written to betterdb:mem:*,");
+    console.log("and knowledge entries are re-pointed to the new memory ids.");
+    console.log("The legacy index is dropped only after the new count is verified;");
+    console.log("legacy hashes are left in place for you to delete once satisfied.");
+    await valkeyClient.quit();
+    return;
+  }
+
+  const modelClient = await createModelClient();
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.ensureIndex();
+
+  // Baseline so we can verify the store actually grew by the migrated count,
+  // not just that its total happens to exceed it (pre-existing memories).
+  const beforeCount = (await store.listMemories()).length;
+
+  let migrated = 0;
+  let failed = 0;
+  // MemoryStore.remember mints a fresh id, so track legacy -> new so we can
+  // re-point knowledge entries that reference the old episodic ids.
+  const idMap = new Map<string, string>();
   const projects = new Set<string>();
-  for (const id of memoryIds) {
+  for (const id of legacyIds) {
     const memory = await valkeyClient.getMemory(id);
-    if (memory) projects.add(memory.project);
+    if (!memory) {
+      failed++;
+      continue;
+    }
+    try {
+      const newId = await store.storeMemory(memory);
+      idMap.set(id, newId);
+      projects.add(memory.project);
+      migrated++;
+      if (migrated % 10 === 0) {
+        console.log(`  Migrated ${migrated}/${legacyIds.length}...`);
+      }
+    } catch (err) {
+      console.error(`  Failed to migrate ${id}:`, err instanceof Error ? err.message : String(err));
+      failed++;
+    }
   }
 
+  // Re-point distilled knowledge so sourceMemoryIds keep referencing real
+  // episodic memories under the new ids. storeKnowledge upserts by
+  // project:topic, so re-storing overwrites in place.
+  let remappedKnowledge = 0;
   for (const project of projects) {
-    console.log(`\nRunning decay for project: ${project}`);
-    await pipeline.runDecay(project);
+    for (const entry of await valkeyClient.listKnowledge(project)) {
+      const remapped = entry.sourceMemoryIds.map((sid) => idMap.get(sid) ?? sid);
+      if (remapped.some((sid, i) => sid !== entry.sourceMemoryIds[i])) {
+        await valkeyClient.storeKnowledge({ ...entry, sourceMemoryIds: remapped });
+        remappedKnowledge++;
+      }
+    }
+  }
+  if (remappedKnowledge > 0) {
+    console.log(`Re-pointed ${remappedKnowledge} knowledge entries to new memory ids.`);
   }
 
-  await valkeyClient.setLastAgingRun(new Date());
-  console.log("\nAging pipeline complete.");
+  // Verify before dropping the legacy index: the store must have grown by the
+  // number we successfully migrated (not merely exceed it, which pre-existing
+  // memories would satisfy even if rows failed to copy).
+  const afterCount = (await store.listMemories()).length;
+  const grew = afterCount - beforeCount;
+  console.log(`\nMigrated: ${migrated}, failed: ${failed}, store grew by ${grew} (now ${afterCount}).`);
+
+  if (migrated > 0 && grew >= migrated) {
+    await valkeyClient.dropIndex();
+    console.log("Verified — dropped the legacy index (betterdb-memory-index).");
+    console.log("Legacy hashes (betterdb:memory:*) remain; delete them manually when ready.");
+  } else {
+    console.log("Count mismatch — left the legacy index in place. Re-run after investigating.");
+  }
+
+  await store.close();
+  await valkeyClient.quit();
+}
+
+// ---------------------------------------------------------------------------
+// ingest-claude-md (ingest a CLAUDE.md / MEMORY.md file into the store)
+// ---------------------------------------------------------------------------
+
+async function runIngestClaudeMd(pathArg?: string) {
+  console.log("BetterDB Memory for Claude Code — Ingest markdown memory file\n");
+
+  const candidates = pathArg
+    ? [pathArg]
+    : [
+        join(process.cwd(), "CLAUDE.md"),
+        join(process.cwd(), "MEMORY.md"),
+        join(HOME, ".claude", "CLAUDE.md"),
+      ];
+
+  const filePath = candidates.find((p) => existsSync(p));
+  if (!filePath) {
+    console.error(`No memory file found. Looked in:\n  ${candidates.join("\n  ")}`);
+    process.exit(1);
+  }
+  console.log(`Reading ${filePath}`);
+
+  const content = readFileSync(filePath, "utf-8");
+  // Split into paragraph-sized chunks on blank lines so each becomes an
+  // independently recallable memory; cap length to keep embeddings sane.
+  const MAX_CHUNK = 480;
+  const chunks = content
+    .split(/\n\s*\n/)
+    .map((c) => c.trim())
+    .filter((c) => c.length > 0)
+    .map((c) => (c.length > MAX_CHUNK ? c.slice(0, MAX_CHUNK) : c));
+
+  if (chunks.length === 0) {
+    console.log("File is empty — nothing to ingest.");
+    process.exit(0);
+  }
+
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { createModelClient } = await import("./client/model.js");
+  const { getCwdProject } = await import("./memory/capture.js");
+  const { SessionSummarySchema } = await import("./memory/schema.js");
+
+  const valkeyClient = await getValkeyClient();
+  const modelClient = await createModelClient();
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.ensureIndex();
+
+  const project = getCwdProject();
+  const timestamp = new Date().toISOString();
+  let stored = 0;
+
+  for (const chunk of chunks) {
+    const summary = SessionSummarySchema.parse({
+      decisions: [],
+      patterns: [],
+      problemsSolved: [],
+      openThreads: [],
+      filesChanged: [],
+      oneLineSummary: chunk,
+    });
+    await store.storeMemory({
+      memoryId: crypto.randomUUID(),
+      project,
+      branch: "claude-md",
+      timestamp,
+      summary,
+      importanceScore: 0.6,
+      accessCount: 0,
+      lastAccessed: timestamp,
+    });
+    stored++;
+  }
+
+  console.log(`\nIngested ${stored} chunks from ${filePath} into project "${project}".`);
+  await store.close();
   await valkeyClient.quit();
 }
 
@@ -417,6 +751,29 @@ function commandExists(cmd: string): boolean {
   return result.exitCode === 0;
 }
 
+/**
+ * Merge BetterDB hooks into existing settings hooks without clobbering
+ * entries from other plugins or user-defined hooks. For each event,
+ * removes any previous BetterDB entries (matched by BIN_DIR path)
+ * then appends the new ones.
+ */
+function mergeHooks(
+  existing: Record<string, unknown[]>,
+  ours: Record<string, unknown[]>,
+): Record<string, unknown[]> {
+  const merged = { ...existing };
+  for (const [event, entries] of Object.entries(ours)) {
+    const prev = Array.isArray(merged[event]) ? merged[event] : [];
+    // Filter out previous BetterDB entries (contain our BIN_DIR or betterdb path)
+    const filtered = prev.filter((entry) => {
+      const json = JSON.stringify(entry);
+      return !json.includes(BIN_DIR) && !json.includes("betterdb");
+    });
+    merged[event] = [...filtered, ...entries];
+  }
+  return merged;
+}
+
 function readConfigValue(key: string): string | undefined {
   if (!existsSync(CONFIG_PATH)) return undefined;
   try {
@@ -425,6 +782,7 @@ function readConfigValue(key: string): string | undefined {
     const val = (data as Record<string, unknown>)[key];
     if (typeof val === "string") return val;
     if (typeof val === "number") return String(val);
+    if (typeof val === "boolean") return String(val);
     return undefined;
   } catch {
     return undefined;