@dikolab/kbdb 0.2.1 → 0.3.0

package/dist/cli.mjs

@@ -99,6 +99,19 @@ function parseArgs(argv) {
       case "--skills":
         options.skills = (argv[++i] ?? "").split(",");
         break;
+      case "--tags":
+        options.tags = (argv[++i] ?? "").split(",");
+        break;
+      case "--replace":
+        options.replace = true;
+        break;
+      case "--depth":
+      case "-d":
+        options.depth = Math.min(
+          3,
+          Math.max(0, parseInt(argv[++i] ?? "", 10) || 0)
+        );
+        break;
       case "--content":
       case "-c":
         options.content = true;
@@ -136,9 +149,11 @@ function formatText(paged) {
     const num = paged.offset + i + 1;
     const heading = r.heading ?? "(untitled)";
     const terms = r.matched_terms.join(", ");
-    return `${String(num)}. [${r.kbid}] ${heading} (score: ${r.score.toFixed(4)})
+    const fields = r.matched_fields.join(", ");
+    const confidencePct = (r.confidence * 100).toFixed(0);
+    return `${String(num)}. [${r.kbid}] ${heading} (score: ${r.score.toFixed(4)}, confidence: ${confidencePct}%)
    ${r.snippet || r.preview || "(no snippet)"}
-   type: ${r.type}  terms: ${terms}`;
+   type: ${r.type}  terms: ${terms}` + (fields ? `  fields: ${fields}` : "");
   }).join("\n\n");
   const footer = `
 Showing ${String(start)}-${String(end)} of ${String(paged.total)} results`;
@@ -147,12 +162,32 @@ Use --offset ${String(end)} to see more` : "";
   return lines + footer + hint;
 }
 function formatMcp(paged) {
-  return JSON.stringify({
-    type: "text",
-    text: paged.items.map(
-      (r) => `[${r.kbid}] ${r.heading ?? "(untitled)"} \u2014 ${r.snippet || r.preview}`
-    ).join("\n")
-  });
+  const mcpItems = paged.items.map((r) => ({
+    kbid: r.kbid,
+    heading: r.heading,
+    type: r.type,
+    docids: r.docids,
+    snippet: r.snippet,
+    matched_terms: r.matched_terms,
+    matched_fields: r.matched_fields,
+    created_at: r.created_at
+  }));
+  return JSON.stringify(
+    {
+      type: "text",
+      text: paged.items.map(
+        (r) => `[${r.kbid}] ${r.heading ?? "(untitled)"} \u2014 ${r.snippet || r.preview}`
+      ).join("\n"),
+      items: mcpItems,
+      total: paged.total,
+      offset: paged.offset,
+      limit: paged.limit,
+      has_more: paged.has_more,
+      relaxed: paged.relaxed
+    },
+    null,
+    2
+  );
 }
 
 // src/shared/cli/functions/run-search.function.ts
@@ -164,7 +199,8 @@ async function runSearch(client, options) {
       total: 0,
       offset: 0,
       limit: options.limit,
-      has_more: false
+      has_more: false,
+      relaxed: false
     };
   }
   const results = await client.search({
@@ -180,17 +216,43 @@ async function runSearch(client, options) {
       type: r.type,
       docids: r.docids,
       score: r.score,
+      confidence: r.confidence ?? 0,
       snippet: r.snippet,
       matched_terms: r.matched_terms,
+      matched_fields: r.matched_fields ?? [],
+      created_at: r.created_at ?? "",
       preview: ""
     })),
     total: results.total,
     offset: results.offset,
     limit: results.limit,
-    has_more: results.has_more
+    has_more: results.has_more,
+    relaxed: results.relaxed ?? false
   };
 }
 
+// src/shared/cli/functions/run-recall.function.ts
+var MAX_RECALL_DEPTH = 3;
+async function runRecall(client, options) {
+  if (options.args.length === 0) {
+    return { error: "no kbid provided" };
+  }
+  const depth = Math.min(
+    MAX_RECALL_DEPTH,
+    Math.max(0, options.depth ?? 0)
+  );
+  if (options.args.length === 1) {
+    return client.recall({ kbid: options.args[0], depth });
+  }
+  return client.recall({ kbids: options.args, depth });
+}
+
+// src/shared/cli/functions/run-export.function.ts
+async function runExport(client, options) {
+  const path = options.args[0];
+  return client.export({ path });
+}
+
 // src/shared/cli/functions/run-learn.function.ts
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, extname, join } from "node:path";
@@ -208,14 +270,11 @@ async function runLearn(client, options, io) {
         content,
         title: options.title,
         description: options.description,
-        docid: options.docid
-      });
-      results.push({
-        kbid: result.kbid,
-        path: "-",
-        size: content.length,
-        skipped: false
+        docid: options.docid,
+        tags: options.tags,
+        replace: options.replace
       });
+      results.push(mapAddSectionResult(result, "-", content.length));
       continue;
     }
     const files = collectFiles(target);
@@ -225,18 +284,30 @@ async function runLearn(client, options, io) {
         sectionType: "text",
         content,
         title: options.title,
-        docid: options.docid
-      });
-      results.push({
-        kbid: result.kbid,
-        path: file,
-        size: content.length,
-        skipped: false
+        description: options.description,
+        docid: options.docid,
+        tags: options.tags,
+        replace: options.replace,
+        sourcePath: file
       });
+      results.push(
+        mapAddSectionResult(result, file, content.length)
+      );
     }
   }
   return results;
 }
+function mapAddSectionResult(result, path, size) {
+  return {
+    kbid: result.kbid,
+    path,
+    size,
+    skipped: false,
+    superseded: result.superseded ?? null,
+    warnings: result.warnings ?? [],
+    near_duplicates: result.near_duplicates ?? []
+  };
+}
 function readProcessStdin() {
   return new Promise((resolve4) => {
     const chunks = [];
@@ -301,8 +372,26 @@ async function runContent(client, options) {
 }
 
 // src/shared/cli/functions/run-check.function.ts
+function parseDivergentContent(encoded) {
+  if (!encoded) return [];
+  return encoded.split(";").filter((segment) => segment.includes(":")).map((segment) => {
+    const colonIdx = segment.indexOf(":");
+    const sourceKey = segment.slice(0, colonIdx);
+    const kbids = segment.slice(colonIdx + 1).split(",").filter((k) => k.length > 0);
+    return { sourceKey, kbids };
+  }).filter((entry) => entry.kbids.length > 0);
+}
 async function runCheck(client, _options) {
-  return client.integrityCheck();
+  const raw = await client.integrityCheck();
+  return {
+    ok: raw.ok,
+    errors: raw.errors,
+    sections_checked: raw.sections_checked,
+    documents_checked: raw.documents_checked,
+    references_checked: raw.references_checked,
+    elapsed_ms: raw.elapsed_ms,
+    divergent_content: parseDivergentContent(raw.divergent_content)
+  };
 }
 
 // src/shared/cli/functions/run-gc.function.ts
@@ -325,8 +414,109 @@ function findDb(dbPath) {
 }
 
 // src/shared/cli/functions/run-init.function.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join4, resolve as resolve2 } from "node:path";
+
+// src/shared/cli/functions/install-default-skills.function.ts
+import { createHash } from "node:crypto";
 import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
-import { join as join3, resolve as resolve2 } from "node:path";
+import { join as join3 } from "node:path";
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function base32Encode(bytes) {
+  let result = "";
+  let bits = 0;
+  let value = 0;
+  for (const byte of bytes) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      result += BASE32_ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    result += BASE32_ALPHABET[value << 5 - bits & 31];
+  }
+  return result.toLowerCase();
+}
+function computeSectionKbid(mimeType, content) {
+  const contentBytes = Buffer.from(content, "utf-8");
+  const header = `section ${mimeType} ${contentBytes.length.toString()}\0`;
+  const headerBytes = Buffer.from(header, "utf-8");
+  const input = Buffer.concat([headerBytes, contentBytes]);
+  const hash = createHash("sha256").update(input).digest();
+  const truncated = new Uint8Array(hash.buffer, 0, 16);
+  return base32Encode(truncated);
+}
+function escapeToml(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function serializeSkillSection(kbid, title, description, content) {
+  const size = Buffer.byteLength(content, "utf-8");
+  const header = [
+    `kbid = "${escapeToml(kbid)}"`,
+    `section_type = "text/markdown"`,
+    `type_name = "skill"`,
+    `title = "${escapeToml(title)}"`,
+    `description = "${escapeToml(description)}"`,
+    `size = ${size.toString()}`,
+    `token_count = 0`,
+    `heading_token_count = 0`,
+    `body_token_count = 0`,
+    `code_token_count = 0`,
+    `created_at = 0`,
+    `checksum = "${escapeToml(kbid)}"`,
+    ""
+  ].join("\n");
+  return `${header}
+---
+${content}`;
+}
+function installSkill(sectionsDir, skill) {
+  const content = JSON.stringify({
+    name: skill.name,
+    description: skill.description,
+    arguments: [],
+    body: skill.body
+  });
+  const kbid = computeSectionKbid("text/markdown", content);
+  const prefix = kbid.slice(0, 2);
+  const shardDir = join3(sectionsDir, prefix);
+  const filePath = join3(shardDir, `${kbid}.section`);
+  if (existsSync2(filePath)) {
+    return;
+  }
+  mkdirSync(shardDir, { recursive: true });
+  const fileContent = serializeSkillSection(
+    kbid,
+    skill.name,
+    skill.description,
+    content
+  );
+  writeFileSync(filePath, fileContent, "utf-8");
+}
+var QUERY_GUIDANCE_BODY = 'This knowledge base uses lexical search (stemmed BM25F), not semantic/vector search. Follow these guidelines for effective retrieval:\n\n1. Issue MULTIPLE short keyword queries rather than one long natural-language question. Each query should target 2-3 specific terms.\n\n2. EXPAND SYNONYMS yourself. "login" will not match "sign-in" unless both terms appear in the content. Try alternative phrasings: search for "login", then "sign-in", then "authentication".\n\n3. USE BOOLEAN AND PHRASE SYNTAX:\n   - Exact phrases: "error handling"\n   - Boolean AND: auth AND token\n   - Boolean OR: cache OR redis\n   - Exclusion: auth -oauth\n\n4. LEAN ON HEADINGS. Headings carry 2x weight in ranking. Search for terms that are likely in section titles.\n\n5. STEMMING IS AUTOMATIC. "connections" matches "connect", "running" matches "run". You do not need to try inflected forms.\n\n6. USE RECALL AFTER SEARCH. After finding relevant sections with search, use recall with increasing depth (0-3) to progressively expand context: depth 0 = full content, depth 1 = parent documents + back-references, depth 2 = siblings + forward references, depth 3 = referenced sections.\n\n7. CODE IDENTIFIERS ARE SPLIT. camelCase and snake_case names are decomposed: getUserById becomes searchable as "get", "user", "by", "id".\n\n8. PAGINATION. Default limit is 20 results. Use offset for additional pages if total > limit.';
+var MEMORY_PROTOCOL_BODY = "Follow these guidelines to keep the knowledge base accurate and useful:\n\n1. STORE DURABLE FACTS: decisions, architecture choices, configuration values, corrections to prior knowledge, API contracts, and resolved incidents. These are the facts that matter weeks later.\n\n2. DO NOT STORE: transient conversation context, debugging output, ephemeral task state, raw log dumps, or information that changes every session. The brain should contain knowledge, not activity logs.\n\n3. SEARCH BEFORE STORING. Always search the knowledge base before adding new content. If a section already covers the topic, use learn with --replace to update it rather than creating a duplicate.\n\n4. USE --replace FOR CORRECTIONS. When a fact changes (e.g., rate limit updated from 100 to 200 req/min), re-learn the corrected content with --replace so the old version is superseded. Without --replace, both the old and new versions coexist with equal ranking.\n\n5. ATTACH TAGS for scoping. Use tags like project name, domain, or topic (e.g., --tags auth,api,v2) so queries can be filtered by scope later.\n\n6. PREFER RECENT RESULTS. When search returns multiple sections covering the same topic, prefer the one with the most recent created_at timestamp -- it is more likely to reflect the current state.\n\n7. USE RECALL AFTER SEARCH. After finding relevant sections, use recall with increasing depth (0-3) to expand context progressively before making decisions.\n\n8. INCLUDE HEADINGS. Always provide a descriptive title when storing content. Headings carry 2x ranking weight -- omitting them significantly reduces searchability.";
+var DEFAULT_SKILLS = [
+  {
+    name: "query-guidance",
+    description: "How to effectively search this knowledge base. Read this before issuing search queries.",
+    body: QUERY_GUIDANCE_BODY
+  },
+  {
+    name: "memory-protocol",
+    description: "Guidelines for what to store in this knowledge base and when. Read this before using the learn tool.",
+    body: MEMORY_PROTOCOL_BODY
+  }
+];
+function installDefaultSkills(dbDir) {
+  const sectionsDir = join3(dbDir, "sections");
+  for (const skill of DEFAULT_SKILLS) {
+    installSkill(sectionsDir, skill);
+  }
+}
+
+// src/shared/cli/functions/run-init.function.ts
 var DB_FORMAT_VERSION = 1;
 var CATALOG_TOML = `version = ${DB_FORMAT_VERSION.toString()}
 section_count = 0
@@ -344,21 +534,21 @@ var GITIGNORE = [
   ""
 ].join("\n");
 function createScaffold(dbDir) {
-  mkdirSync(dbDir, { recursive: true });
-  mkdirSync(join3(dbDir, "sections"));
-  mkdirSync(join3(dbDir, "documents"));
-  writeFileSync(join3(dbDir, "catalog.toml"), CATALOG_TOML);
-  writeFileSync(join3(dbDir, "corpus.bin"), "");
-  writeFileSync(join3(dbDir, "inverted.idx"), "");
-  writeFileSync(join3(dbDir, "positional.idx"), "");
-  writeFileSync(join3(dbDir, "worker.toml"), WORKER_TOML);
-  writeFileSync(join3(dbDir, ".gitignore"), GITIGNORE);
+  mkdirSync2(dbDir, { recursive: true });
+  mkdirSync2(join4(dbDir, "sections"));
+  mkdirSync2(join4(dbDir, "documents"));
+  writeFileSync2(join4(dbDir, "catalog.toml"), CATALOG_TOML);
+  writeFileSync2(join4(dbDir, "corpus.bin"), "");
+  writeFileSync2(join4(dbDir, "inverted.idx"), "");
+  writeFileSync2(join4(dbDir, "positional.idx"), "");
+  writeFileSync2(join4(dbDir, "worker.toml"), WORKER_TOML);
+  writeFileSync2(join4(dbDir, ".gitignore"), GITIGNORE);
 }
 function runInit(options) {
   const basePath = options.dbPath ? resolve2(options.dbPath) : process.cwd();
-  const dbDir = join3(basePath, ".kbdb");
+  const dbDir = join4(basePath, ".kbdb");
   try {
-    if (existsSync2(dbDir)) {
+    if (existsSync3(dbDir)) {
       return {
         ok: false,
         targetPath: dbDir,
@@ -366,6 +556,7 @@ function runInit(options) {
       };
     }
     createScaffold(dbDir);
+    installDefaultSkills(dbDir);
     return { ok: true, targetPath: dbDir };
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
@@ -723,6 +914,8 @@ async function dispatchCommand(client, options, io) {
       return handleUnlearn(client, options);
     case "search":
       return handleSearch(client, options);
+    case "recall":
+      return handleRecall(client, options);
     case "content":
       return handleContent(client, options);
     case "check":
@@ -733,6 +926,8 @@ async function dispatchCommand(client, options, io) {
       return handleRebuild(client, options);
     case "status":
       return handleStatus(client, options);
+    case "export":
+      return handleExport(client, options);
     case "db-init":
       return handleDbInit(options);
     case "db-migrate":
@@ -821,6 +1016,40 @@ async function handleSearch(client, options) {
     };
   }
 }
+async function handleRecall(client, options) {
+  try {
+    const result = await runRecall(client, options);
+    if ("error" in result) {
+      return {
+        error: `error: ${result.error}`,
+        exitCode: 1
+      };
+    }
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `recall failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleExport(client, options) {
+  try {
+    const result = await runExport(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `export failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
 async function handleContent(client, options) {
   try {
     const result = await runContent(client, options);
@@ -921,18 +1150,20 @@ async function hydrateSearchPreviews(client, paged) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.2.1";
+var VERSION = "0.2.2";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "learn",
   "unlearn",
   "search",
+  "recall",
   "content",
   "check",
   "gc",
   "rebuild",
   "status",
+  "export",
   "mcp",
   "db",
   "skill",
@@ -995,6 +1226,7 @@ Knowledge Base:
    learn               Import content from files/stdin
    unlearn             Remove sections by kbid
    search              Query the knowledge base
+   recall              Retrieve section context by kbid
    content             Compose rendered content from ids
 
 Database:
@@ -1007,6 +1239,7 @@ Maintenance:
                        sections
    rebuild             Reconstruct all index files
    status              Show database status
+   export              Snapshot database for backup
 
 Skills:
    skill learn         Create a new skill definition
@@ -1079,14 +1312,18 @@ Options:
    --title <title>     Section title
    --description <d>   Section description
    --docid <docid>     Document ID to group under
+   --tags <t,...>      Comma-separated tags
+   --replace           Supersede existing section by source key
    --db <path>         Path to .kbdb directory
 
 Output:
-   JSON array of { kbid, path, size, skipped }
+   JSON array of { kbid, path, size, skipped,
+                   superseded, warnings, near_duplicates }
 
 Examples:
    kbdb learn README.md
    kbdb learn ./docs/
+   kbdb learn --tags auth,api --replace doc.md
    cat notes.txt | kbdb learn -
 `,
   unlearn: `kbdb unlearn - Remove sections by kbid
@@ -1127,6 +1364,25 @@ Examples:
    kbdb search "machine learning"
    kbdb search --limit 5 --format text query
    kbdb search --mode documents --content term
+`,
+  recall: `kbdb recall - Retrieve section context by kbid
+
+Usage: kbdb recall [options] <kbid>...
+
+Arguments:
+   <kbid>              26-character knowledge base identifier
+
+Options:
+   --depth <n>, -d     Expansion depth (0-3, default: 0)
+   --tags <t,...>      Filter by tags
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON RecallResult or RecallResult[]
+
+Examples:
+   kbdb recall abcdef1234567890abcdef1234
+   kbdb recall kbid1 --depth 2
 `,
   content: `kbdb content - Compose rendered content from ids
 
@@ -1200,6 +1456,25 @@ Output:
 Examples:
    kbdb status
    kbdb status --db /path/to/project
+`,
+  export: `kbdb export - Snapshot database for backup
+
+Usage: kbdb export [options] [<path>]
+
+Arguments:
+   <path>              Output directory path
+                       (default: ./kbdb-export/)
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { path, sections_exported, documents_exported }
+
+Examples:
+   kbdb export
+   kbdb export ./my-backup
+   kbdb export --db /path/to/project
 `,
   mcp: `kbdb mcp - Start MCP server mode (stdio)
 
@@ -1870,6 +2145,23 @@ var WorkerClient = class {
       docType
     });
   }
+  /**
+   * Exports the database to a target directory on disk.
+   *
+   * Copies section files, document manifests, and `catalog.toml`
+   * to `params.path`. Index files are not exported because they
+   * are derivable from the section and document data.
+   *
+   * @param params - optional export parameters
+   * @param params.path - target directory path; defaults to
+   *   `./kbdb-export/` when not provided
+   * @returns export report with the resolved path and file counts
+   */
+  async export(params) {
+    return this.call("export", {
+      targetPath: params?.path || void 0
+    });
+  }
   /**
    * Sends a JSON-RPC 2.0 request and awaits the response.
    *
@@ -1927,17 +2219,17 @@ var WorkerClient = class {
 };
 
 // src/shared/worker-client/functions/create-worker-client.function.ts
-import { existsSync as existsSync6, readFileSync as readFileSync3, unlinkSync as unlinkSync2 } from "node:fs";
-import { join as join7 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync3, unlinkSync as unlinkSync2 } from "node:fs";
+import { join as join8 } from "node:path";
 import { tmpdir as tmpdir3 } from "node:os";
 
 // src/shared/worker-client/functions/resolve-db-path.function.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { join as join4, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import { join as join5, resolve as resolve3 } from "node:path";
 function resolveDbPath(targetDir) {
   const base = targetDir ? resolve3(targetDir) : process.cwd();
-  const dbPath = join4(base, ".kbdb");
-  if (!existsSync3(dbPath)) {
+  const dbPath = join5(base, ".kbdb");
+  if (!existsSync4(dbPath)) {
     throw new Error(`database not found: ${dbPath}`);
   }
   return dbPath;
@@ -1950,8 +2242,8 @@ async function computeContextId(absolutePath) {
 }
 
 // src/shared/worker-client/functions/discover-daemon.function.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2, unlinkSync } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync2, unlinkSync } from "node:fs";
+import { join as join6 } from "node:path";
 import { tmpdir } from "node:os";
 
 // src/shared/platform/functions/is-process-alive.function.ts
@@ -1966,8 +2258,8 @@ function isProcessAlive(pid) {
 
 // src/shared/worker-client/functions/discover-daemon.function.ts
 function discoverDaemon(contextId) {
-  const pidPath = join5(tmpdir(), `kbdb-${contextId}.pid`);
-  if (!existsSync4(pidPath)) return null;
+  const pidPath = join6(tmpdir(), `kbdb-${contextId}.pid`);
+  if (!existsSync5(pidPath)) return null;
   const pidStr = readFileSync2(pidPath, "utf-8").trim();
   const pid = parseInt(pidStr, 10);
   if (isNaN(pid) || !isProcessAlive(pid)) {
@@ -1977,8 +2269,8 @@ function discoverDaemon(contextId) {
     }
     return null;
   }
-  const socketPath = join5(tmpdir(), `kbdb-${contextId}.sock`);
-  const crashPath = join5(tmpdir(), `kbdb-${contextId}.crash`);
+  const socketPath = join6(tmpdir(), `kbdb-${contextId}.sock`);
+  const crashPath = join6(tmpdir(), `kbdb-${contextId}.crash`);
   try {
     unlinkSync(crashPath);
   } catch {
@@ -2004,16 +2296,16 @@ function spawnDaemon(contextPath, runtime2, workerScript2) {
 }
 
 // src/shared/worker-client/functions/wait-for-daemon.function.ts
-import { existsSync as existsSync5 } from "node:fs";
-import { join as join6 } from "node:path";
+import { existsSync as existsSync6 } from "node:fs";
+import { join as join7 } from "node:path";
 import { tmpdir as tmpdir2 } from "node:os";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var POLL_INTERVAL_MS = 100;
 async function waitForDaemon(contextId, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  const pidPath = join6(tmpdir2(), `kbdb-${contextId}.pid`);
+  const pidPath = join7(tmpdir2(), `kbdb-${contextId}.pid`);
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    if (existsSync5(pidPath)) return true;
+    if (existsSync6(pidPath)) return true;
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
   }
   return false;
@@ -2041,8 +2333,8 @@ async function createWorkerClient(options) {
   return client;
 }
 function readCrashReason(contextId) {
-  const crashPath = join7(tmpdir3(), `kbdb-${contextId}.crash`);
-  if (!existsSync6(crashPath)) {
+  const crashPath = join8(tmpdir3(), `kbdb-${contextId}.crash`);
+  if (!existsSync7(crashPath)) {
     return "daemon failed to start (no details available)";
   }
   try {
@@ -2063,7 +2355,7 @@ function createToolDefinitions() {
   return [
     {
       name: "search",
-      description: "Search the knowledge base. Returns ranked results with headings and snippets for relevance evaluation. Use `recall` to get full content of specific results.",
+      description: "Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use multiple short keyword queries for best coverage. Use recall to get full content.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2097,7 +2389,7 @@ function createToolDefinitions() {
     },
     {
       name: "learn",
-      description: "Add a text section to the knowledge base.",
+      description: "Import content into the knowledge base. Use for durable facts, decisions, and corrections. Use replace when updating existing knowledge. Attach tags for scoping.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2120,6 +2412,15 @@ function createToolDefinitions() {
           docid: {
             type: "string",
             description: "Document ID to group under"
+          },
+          tags: {
+            type: "array",
+            items: { type: "string" },
+            description: "Tags for scoping and filtering"
+          },
+          replace: {
+            type: "boolean",
+            description: "Replace existing section with same source key (supersession)"
           }
         },
         required: ["content"]
@@ -2288,6 +2589,26 @@ function createToolDefinitions() {
         openWorldHint: false
       }
     },
+    {
+      name: "export",
+      description: "Export the database as a self-contained directory snapshot (sections, documents, catalog -- no indexes).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            description: "Export destination path (default: ./kbdb-export/)"
+          }
+        }
+      },
+      annotations: {
+        title: "Export Snapshot",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     {
       name: "skill-learn",
       description: "Create or update a skill definition. Skills are reusable AI agent capabilities with template placeholders.",
@@ -2667,7 +2988,7 @@ async function handleAgentDelete(client, args) {
 }
 
 // src/shared/mcp/functions/handle-recall.function.ts
-async function handleRecall(client, args) {
+async function handleRecall2(client, args) {
   const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;
   const kbids = Array.isArray(args["kbids"]) && args["kbids"].every((item) => typeof item === "string") ? args["kbids"] : void 0;
   if (!kbid && !kbids) {
@@ -2697,6 +3018,15 @@ async function handleRecall(client, args) {
 function asString2(value, fallback) {
   return typeof value === "string" ? value : fallback;
 }
+function asBooleanOrUndefined(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function asStringArrayOrUndefined(value) {
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  return void 0;
+}
 function asStringArray2(value) {
   if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
     return value;
@@ -2715,7 +3045,7 @@ async function handleToolCall(client, name, args) {
       case "retrieve":
         return await handleRetrieve(client, args);
       case "recall":
-        return await handleRecall(client, args);
+        return await handleRecall2(client, args);
       case "status":
         return await handleStatus2(client);
       case "content":
@@ -2726,6 +3056,8 @@ async function handleToolCall(client, name, args) {
         return await handleGc2(client);
       case "rebuild":
         return await handleRebuild2(client);
+      case "export":
+        return await handleExport2(client, args);
       case "skill-learn":
         return await handleSkillLearn(client, args);
       case "skill-list":
@@ -2774,7 +3106,13 @@ async function handleSearch2(client, args) {
   });
   const stripped = {
     ...results,
-    items: results.items.map(({ score: _score, ...rest }) => rest)
+    items: results.items.map(
+      ({
+        score: _score,
+        confidence: _confidence,
+        ...rest
+      }) => rest
+    )
   };
   return {
     content: [
@@ -2790,6 +3128,8 @@ async function handleLearn2(client, args) {
   const title = typeof args["title"] === "string" ? args["title"] : void 0;
   const description = typeof args["description"] === "string" ? args["description"] : void 0;
   const docid = typeof args["docid"] === "string" ? args["docid"] : void 0;
+  const tags = asStringArrayOrUndefined(args["tags"]);
+  const replace = asBooleanOrUndefined(args["replace"]);
   if (sectionType.startsWith("image/") && !title) {
     return {
       content: [
@@ -2806,13 +3146,26 @@ async function handleLearn2(client, args) {
     content: asString2(args["content"], ""),
     title,
     description,
-    docid
+    docid,
+    tags,
+    replace
   });
+  const normalized = {
+    kbid: result.kbid,
+    indexed_terms_count: result.indexed_terms_count ?? 0,
+    elapsed_ms: result.elapsed_ms ?? 0,
+    superseded: result.superseded ?? null,
+    warnings: result.warnings ?? [],
+    near_duplicates: (result.near_duplicates ?? []).map((d) => ({
+      kbid: d.kbid,
+      similarity: d.similarity
+    }))
+  };
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(result)
+        text: JSON.stringify(normalized)
       }
     ]
   };
@@ -3053,6 +3406,20 @@ async function handleSkillDelete(client, args) {
     ]
   };
 }
+async function handleExport2(client, args) {
+  const path = typeof args["path"] === "string" ? args["path"] : void 0;
+  const result = await client.export(
+    path !== void 0 ? { path } : {}
+  );
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result)
+      }
+    ]
+  };
+}
 
 // src/shared/mcp/functions/handle-resource-read.function.ts
 async function handleResourceRead(client, uri) {
@@ -3424,8 +3791,9 @@ var McpServer = class {
     const request = parsed;
     if (request.id === void 0) {
       if (request.method === "notifications/initialized" || request.method === "notifications/cancelled") {
-        if (request.method === "notifications/initialized") {
+        if (request.method === "notifications/initialized" && !this.initialized) {
           this.initialized = true;
+          void this.runStartupHealthCheck();
         }
       }
       return null;
@@ -3618,6 +3986,27 @@ var McpServer = class {
     const json = JSON.stringify(response);
     process.stdout.write(json + "\n");
   }
+  /**
+   * Runs an integrity check immediately after the MCP handshake
+   * completes. Emits a `notifications/message` warning when the
+   * check detects issues so the connected agent is aware before
+   * making requests. The server continues operating regardless of
+   * the result.
+   */
+  async runStartupHealthCheck() {
+    try {
+      const report = await this.client.integrityCheck();
+      if (!report.ok) {
+        const summary = report.errors.map((e) => `${e.type}: ${e.entity} -- ${e.detail}`).join("; ");
+        this.notify("notifications/message", {
+          level: "warning",
+          logger: "kbdb",
+          data: `Database integrity issues detected: ${summary}`
+        });
+      }
+    } catch {
+    }
+  }
 };
 
 // src/shared/mcp/functions/create-mcp-server.function.ts