@dikolab/kbdb 0.2.1 → 0.3.0

package/src/shared/cli/functions/run-recall.function.ts

@@ -0,0 +1,66 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { RecallResult } from '../../worker-client/typings/recall-result.model.ts';
+
+/** Maximum allowed expansion depth for recall operations. */
+const MAX_RECALL_DEPTH = 3;
+
+/**
+ * Minimal client interface required by `runRecall`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface RecallClient {
+   /**
+    * Retrieves full content and context for one or more sections
+    * by their knowledge-base identifiers.
+    *
+    * @param params - section identifier(s) and optional expansion
+    *   depth (0--3)
+    * @returns a single `RecallResult` when `kbid` is supplied, or
+    *   a `RecallResult[]` when `kbids` is supplied
+    */
+   recall(params: {
+      kbid?: string;
+      kbids?: string[];
+      depth?: number;
+   }): Promise<RecallResult | RecallResult[]>;
+}
+
+/**
+ * Retrieves full content and progressive context for one or more
+ * sections by kbid via the provided client.
+ *
+ * Returns an error result when no kbids are provided in
+ * `options.args`. For a single kbid, calls `client.recall` with the
+ * `kbid` parameter and returns the single `RecallResult`. For
+ * multiple kbids, calls `client.recall` with the `kbids` array.
+ *
+ * The `depth` option is read from `options.depth`, defaulting to 0
+ * and clamped to the range 0--3.
+ *
+ * @param client - recall client to delegate to
+ * @param options - parsed CLI options supplying kbids in `args` and
+ *   expansion depth in `depth`
+ * @returns the `RecallResult` or `RecallResult[]` from the client,
+ *   or an error object when no kbids are provided
+ */
+export async function runRecall(
+   client: RecallClient,
+   options: CliOptions,
+): Promise<RecallResult | RecallResult[] | { error: string }> {
+   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 });
+}

package/src/shared/cli/functions/run-search.function.ts

@@ -1,6 +1,58 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
 
+/** A single raw search result item returned by the daemon. */
+interface RawSearchItem {
+   /** Knowledge-base identifier of the matched section. */
+   readonly kbid: string;
+   /** Section heading, or null when untitled. */
+   readonly heading: string | null;
+   /** MIME type of the section content. */
+   readonly type: string;
+   /** Document IDs this section belongs to. */
+   readonly docids: readonly string[];
+   /** Relevance score from the ranking engine. */
+   readonly score: number;
+   /** KWIC excerpt centered on the highest-scoring matched term. */
+   readonly snippet: string;
+   /** Query terms that matched within this section. */
+   readonly matched_terms: readonly string[];
+   /**
+    * Fields that contained at least one match.
+    * May be absent from older daemon versions.
+    */
+   readonly matched_fields?: readonly string[];
+   /**
+    * Normalised confidence score (0.0-1.0) relative to the top result.
+    * May be absent from older daemon versions.
+    */
+   readonly confidence?: number;
+   /**
+    * ISO 8601 creation timestamp of the section.
+    * May be absent from older daemon versions.
+    */
+   readonly created_at?: string;
+}
+
+/** Raw paginated search response from the daemon. */
+interface RawSearchResponse {
+   /** Result items for the current page. */
+   readonly items: readonly RawSearchItem[];
+   /** Total number of matches across all pages. */
+   readonly total: number;
+   /** Number of results skipped. */
+   readonly offset: number;
+   /** Maximum results per page. */
+   readonly limit: number;
+   /** Whether more results exist beyond this page. */
+   readonly has_more: boolean;
+   /**
+    * When `true`, the engine relaxed the query to produce results.
+    * May be absent from older daemon versions.
+    */
+   readonly relaxed?: boolean;
+}
+
 /**
  * Minimal client interface required by `runSearch`.
  *
@@ -18,21 +70,7 @@ export interface SearchClient {
       mode?: string;
       limit?: number;
       offset?: number;
-   }): Promise<{
-      readonly items: readonly {
-         readonly kbid: string;
-         readonly heading: string | null;
-         readonly type: string;
-         readonly docids: readonly string[];
-         readonly score: number;
-         readonly snippet: string;
-         readonly matched_terms: readonly string[];
-      }[];
-      readonly total: number;
-      readonly offset: number;
-      readonly limit: number;
-      readonly has_more: boolean;
-   }>;
+   }): Promise<RawSearchResponse>;
 }
 
 /**
@@ -59,6 +97,7 @@ export async function runSearch(
          offset: 0,
          limit: options.limit,
          has_more: false,
+         relaxed: false,
       };
    }
 
@@ -76,13 +115,17 @@ export async function runSearch(
          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,
+      relaxed: results.relaxed ?? false,
    };
 }

package/src/shared/cli/index.ts

@@ -1,6 +1,8 @@
 export { parseArgs } from './functions/parse-args.function.ts';
 export { formatOutput } from './functions/format-output.function.ts';
 export { runSearch } from './functions/run-search.function.ts';
+export { runRecall } from './functions/run-recall.function.ts';
+export { runExport } from './functions/run-export.function.ts';
 export { runLearn } from './functions/run-learn.function.ts';
 export { runUnlearn } from './functions/run-unlearn.function.ts';
 export { runContent } from './functions/run-content.function.ts';
@@ -28,6 +30,8 @@ export type {
    PagedSearchDisplay,
 } from './typings/search-display.model.ts';
 export type { SearchClient } from './functions/run-search.function.ts';
+export type { RecallClient } from './functions/run-recall.function.ts';
+export type { ExportClient } from './functions/run-export.function.ts';
 export type { LearnClient } from './functions/run-learn.function.ts';
 export type {
    UnlearnClient,

package/src/shared/cli/typings/cli-options.interface.ts

@@ -52,6 +52,19 @@ export interface CliOptions {
    body?: string;
    /** Comma-separated skill kbids for agent create. */
    skills?: string[];
+   /**
+    * Recall expansion depth (0-3). Clamped to 3.
+    * Defaults to 0.
+    */
+   depth?: number;
+   /** Comma-separated tags for scoping (learn, recall). */
+   tags?: string[];
+   /**
+    * When `true`, enables supersession by source key (learn).
+    * Re-learning edited content replaces the original section
+    * instead of creating a sibling.
+    */
+   replace?: boolean;
    /** Positional arguments following the sub-command. */
    args: string[];
 }

package/src/shared/cli/typings/learn-result.model.ts

@@ -8,4 +8,20 @@ export interface LearnResult {
    size: number;
    /** `true` when the file was skipped without being ingested. */
    skipped: boolean;
+   /**
+    * Kbid of the section that was superseded via `--replace`,
+    * or `null` when no supersession occurred.
+    */
+   superseded: string | null;
+   /**
+    * Advisory warning strings returned by the engine
+    * (e.g. `"heading_missing"` when no title is provided).
+    */
+   warnings: string[];
+   /**
+    * Sections with content similarity >= 0.85 to this section.
+    * Each entry identifies a near-duplicate section and its
+    * similarity score.
+    */
+   near_duplicates: { kbid: string; similarity: number }[];
 }

package/src/shared/cli/typings/search-display.model.ts

@@ -10,10 +10,22 @@ export interface SearchDisplay {
    docids: readonly string[];
    /** Relevance score assigned by the ranking engine. */
    score: number;
+   /**
+    * Normalised confidence score (0.0-1.0) relative to the
+    * top result in this result set.
+    */
+   confidence: number;
    /** KWIC snippet from the WASM engine (~150 chars). */
    snippet: string;
    /** Query terms that matched within this section. */
    matched_terms: readonly string[];
+   /**
+    * Fields that contained at least one match:
+    * subset of `["heading", "body", "code"]`.
+    */
+   matched_fields: readonly string[];
+   /** ISO 8601 creation timestamp of the section. */
+   created_at: string;
    /**
     * CLI-side truncated content preview for terminal display.
     * Populated when `--content` / `-c` is used.
@@ -33,4 +45,10 @@ export interface PagedSearchDisplay {
    limit: number;
    /** Whether more results exist beyond this page. */
    has_more: boolean;
+   /**
+    * When `true`, the engine relaxed the query (e.g. dropped
+    * rare terms) to return results that would otherwise be
+    * empty.
+    */
+   relaxed: boolean;
 }

package/src/shared/mcp/classes/mcp-server.class.ts

@@ -207,8 +207,12 @@ export class McpServer {
             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;
@@ -445,4 +449,29 @@ export class McpServer {
       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.
+    */
+   private async runStartupHealthCheck(): Promise<void> {
+      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 {
+         // Health check failure is non-fatal -- server continues
+      }
+   }
 }

package/src/shared/mcp/functions/create-tool-definitions.function.ts

@@ -10,10 +10,11 @@ export function createToolDefinitions(): McpToolDefinition[] {
       {
          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.',
+            '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: {
@@ -49,7 +50,11 @@ export function createToolDefinitions(): McpToolDefinition[] {
       },
       {
          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: {
@@ -76,6 +81,17 @@ export function createToolDefinitions(): McpToolDefinition[] {
                   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'],
          },
@@ -268,6 +284,31 @@ export function createToolDefinitions(): McpToolDefinition[] {
             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:

package/src/shared/mcp/functions/handle-tool-call.function.ts

@@ -32,6 +32,30 @@ function asString(value: unknown, fallback: string): string {
    return typeof value === 'string' ? value : fallback;
 }
 
+/**
+ * Narrows an `unknown` value to a boolean, returning `undefined`
+ * when the value is not a boolean.
+ */
+function asBooleanOrUndefined(value: unknown): boolean | undefined {
+   return typeof value === 'boolean' ? value : undefined;
+}
+
+/**
+ * Narrows an `unknown` value to a `string[]`, returning `undefined`
+ * when the value is not an array of strings.
+ */
+function asStringArrayOrUndefined(
+   value: unknown,
+): string[] | undefined {
+   if (
+      Array.isArray(value) &&
+      value.every((item) => typeof item === 'string')
+   ) {
+      return value;
+   }
+   return undefined;
+}
+
 /**
  * Narrows an `unknown` value to a `string[]`, returning an empty
  * array when the value is not an array of strings.
@@ -82,6 +106,8 @@ export async function handleToolCall(
             return await handleGc(client);
          case 'rebuild':
             return await handleRebuild(client);
+         case 'export':
+            return await handleExport(client, args);
          case 'skill-learn':
             return await handleSkillLearn(client, args);
          case 'skill-list':
@@ -135,7 +161,15 @@ async function handleSearch(
 
    const stripped = {
       ...results,
-      items: results.items.map(({ score: _score, ...rest }) => rest),
+      items: results.items.map(
+         ({
+            score: _score,
+            confidence: _confidence,
+            ...rest
+         }: (typeof results.items)[number] & {
+            confidence?: number;
+         }) => rest,
+      ),
    };
 
    return {
@@ -161,6 +195,8 @@ async function handleLearn(
          : undefined;
    const docid =
       typeof args['docid'] === 'string' ? args['docid'] : undefined;
+   const tags = asStringArrayOrUndefined(args['tags']);
+   const replace = asBooleanOrUndefined(args['replace']);
    if (sectionType.startsWith('image/') && !title) {
       return {
          content: [
@@ -178,12 +214,25 @@ async function handleLearn(
       title,
       description,
       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),
          },
       ],
    };
@@ -472,3 +521,22 @@ async function handleSkillDelete(
       ],
    };
 }
+
+async function handleExport(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const path =
+      typeof args['path'] === 'string' ? args['path'] : undefined;
+   const result = await client.export(
+      path !== undefined ? { path } : {},
+   );
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify(result),
+         },
+      ],
+   };
+}

package/src/shared/mcp/typings/mcp-client.interface.ts

@@ -45,6 +45,18 @@ export interface McpIntegrityCheckResult {
    readonly elapsed_ms: number;
 }
 
+/** Export report returned by the daemon. */
+export interface McpExportResult {
+   /** Absolute path to the directory where files were written. */
+   readonly path: string;
+   /** Number of section files copied to the export directory. */
+   readonly sections_exported: number;
+   /** Number of document manifest files copied. */
+   readonly documents_exported: number;
+   /** Time taken to complete the export, in milliseconds. */
+   readonly elapsed_ms: number;
+}
+
 /** Garbage collection report returned by the daemon. */
 export interface McpGcResult {
    /** Number of unreferenced sections removed. */
@@ -53,6 +65,12 @@ export interface McpGcResult {
    readonly removed_bytes: number;
    /** Time taken to complete garbage collection, in milliseconds. */
    readonly elapsed_ms: number;
+   /**
+    * Number of sections whose source_path file no longer contains
+    * their heading text. Advisory; not auto-removed by gc.
+    * Absent on older daemon versions.
+    */
+   readonly stale_sources?: number;
 }
 
 /** Index rebuild report returned by the daemon. */
@@ -96,11 +114,20 @@ export interface McpWorkerClient {
          readonly score: number;
          readonly snippet: string;
          readonly matched_terms: readonly string[];
+         /** Fields that contained matches (heading, body, code). */
+         readonly matched_fields?: readonly string[];
+         /** ISO 8601 creation timestamp of the section. */
+         readonly created_at?: string;
       }[];
       readonly total: number;
       readonly offset: number;
       readonly limit: number;
       readonly has_more: boolean;
+      /**
+       * `true` when results came from an automatic AND-to-OR
+       * fallback query relaxation.
+       */
+      readonly relaxed?: boolean;
    }>;
 
    /**
@@ -120,6 +147,13 @@ export interface McpWorkerClient {
       readonly description?: string;
       /** Optional document ID to group this section under. */
       readonly docid?: string;
+      /** Optional tags for scoping and filtering. */
+      readonly tags?: string[];
+      /**
+       * When `true`, replaces an existing section that has the same
+       * source key (supersession).
+       */
+      readonly replace?: boolean;
    }): Promise<AddSectionResult>;
 
    /**
@@ -263,6 +297,17 @@ export interface McpWorkerClient {
       readonly depth?: number;
    }): Promise<unknown>;
 
+   /**
+    * Exports the database to a target directory as a self-contained
+    * snapshot (sections, documents, catalog -- no indexes).
+    *
+    * @param params - optional export parameters
+    * @returns export report with the resolved path and file counts
+    */
+   export(params?: {
+      readonly path?: string;
+   }): Promise<McpExportResult>;
+
    /** Destroys the IPC socket and clears the connection state. */
    disconnect(): void;
 }

package/src/shared/version/constants/version.constant.ts

@@ -1,2 +1,2 @@
 /** Current package version, kept in sync with package.json. */
-export const VERSION = '0.2.1';
+export const VERSION = '0.2.2';