@dikolab/kbdb 0.2.2 → 0.3.0

package/docs/modules/rust/query-parser/module.md

@@ -49,8 +49,9 @@ engine/crates/query-parser/
     │   ├── identifiers.rs       # stage 4: camelCase split
     │   ├── case.rs              # stage 5: case folding
     │   ├── stopwords.rs         # stage 6: stop words
-    │   ├── stem.rs              # stage 7: Snowball stemmer
-    │   └── ngram.rs             # stage 8: n-gram extract
+    │   ├── synonyms.rs          # stage 7: synonym expansion
+    │   ├── stem.rs              # stage 8: Snowball stemmer
+    │   └── ngram.rs             # stage 9: n-gram extract
     ├── parse.rs                 # query string → QueryPlan
     ├── extract/
     │   ├── mod.rs               # extraction facade
@@ -78,10 +79,10 @@ engine/crates/query-parser/
 
 ### [functions/](functions/module.md) -- Operations
 
-- **[pipeline](functions/pipeline.md)** -- 8-stage
+- **[pipeline](functions/pipeline.md)** -- 9-stage
   tokenization pipeline. Marker stripping, NFC,
   segmentation, identifier splitting, case folding,
-  stop words, stemming, n-grams.
+  stop words, synonym expansion, stemming, n-grams.
 - **[parse](functions/parse.md)** -- Query string
   parsing into `QueryPlan`.
 - **[extract](functions/extract.md)** -- RAKE

package/docs/modules/rust/query-parser/types/keyphrase.md

@@ -58,3 +58,14 @@ component and per-field corpus average from
 [FieldTokenCounts](../../shared/query/types.md)
 for the per-field token counts used in length
 normalization.
+
+```rust
+pub type SynonymMap = HashMap<String, Vec<String>>;
+```
+
+`SynonymMap` is a type alias for the bidirectional
+synonym lookup used in tokenization pipeline stage 7.
+It is constructed once via `build_synonym_map()` from
+a curated list of synonym pairs and reused across all
+tokenization calls. The map is immutable after
+construction.

package/docs/modules/rust/query-parser/types/module.md

@@ -9,9 +9,9 @@ tokenization, keyword extraction, and ranking.*
   `Ngram`, `NgramType`, `StemResult`. Output types
   from the tokenization pipeline.
 - **[keyphrase](keyphrase.md)** -- `Keyphrase`,
-  `WeightedTerm`, `BM25FParams`, `FieldWeights`.
-  Types for keyword extraction and ranking
-  configuration.
+  `WeightedTerm`, `BM25FParams`, `FieldWeights`,
+  `SynonymMap`. Types for keyword extraction, ranking
+  configuration, and synonym expansion.
 - **[cache](cache.md)** -- `QueryCache`. Short-lived
   cache scoped to a single query or indexing
   operation.

package/docs/modules/typescript/shared/cli/functions.md

@@ -68,14 +68,17 @@ async function dispatchCommand(
 
 `DispatchClient` is the intersection of all per-command
 client interfaces (`SearchClient & LearnClient &
-UnlearnClient & ContentClient & CheckClient &
-GcClient & RebuildClient & SkillClient & AgentClient`).
+UnlearnClient & RecallClient & ContentClient &
+CheckClient & GcClient & RebuildClient & ExportClient &
+SkillClient & AgentClient`).
 
 | Command        | Handler                          |
 |----------------|----------------------------------|
 | `learn`        | `runLearn(client, options, io)`  |
+| `export`       | `runExport(client, options)`     |
 | `unlearn`      | `runUnlearn(client, options)`    |
 | `search`       | `runSearch(client, options)`     |
+| `recall`       | `runRecall(client, options)`     |
 | `content`      | `runContent(client, options)`    |
 | `check`        | `runCheck(client, options)`      |
 | `gc`           | `runGc(client, options)`         |
@@ -222,8 +225,15 @@ async function runLearn(
 - If input is a **text file**: adds that single file.
   `--title` and `--description` are optional.
 - If input is **stdin** (`-`): reads `text/markdown`.
+- `--tags <t,...>` attaches comma-separated tags for
+  scoping and filtering.
+- `--replace` enables supersession by source key:
+  if a section with the same source key exists, the
+  old section is replaced.
 - Returns a `LearnResult[]` with one record per file
-  processed.
+  processed. Each result includes `superseded` (kbid
+  of replaced section or `null`), `warnings` (e.g.
+  `"heading_missing"`), and `near_duplicates`.
 
 ### `runUnlearn`
 
@@ -275,6 +285,36 @@ async function runContent(
 Takes identifiers from `options.args`. Calls
 `client.content(ids)`.
 
+### `runRecall`
+
+**File:** `run-recall.function.ts`
+
+Retrieves full content and progressive context for one
+or more sections by kbid.
+
+```ts
+async function runRecall(
+   client: RecallClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+`RecallClient` interface:
+
+```ts
+interface RecallClient {
+   recall(
+      params: RecallParams,
+   ): Promise<RecallResult | RecallResult[]>;
+}
+```
+
+Takes kbid(s) from `options.args` and depth from
+`options.depth` (default 0, clamped 0-3). When a
+single kbid is provided, returns a `RecallResult`
+JSON object. When multiple kbids are provided, returns
+a `RecallResult[]` JSON array.
+
 ### `runCheck`
 
 **File:** `run-check.function.ts`
@@ -320,6 +360,30 @@ async function runRebuild(
 
 Calls `client.rebuildIndexes()`.
 
+### `runExport`
+
+**File:** `run-export.function.ts`
+
+Exports the knowledge base as a self-contained
+directory snapshot for backup or versioning.
+
+```ts
+async function runExport(
+   client: ExportClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+Copies sections, documents, and catalog (no indexes
+-- they are rebuildable via `rebuild`). The export
+destination defaults to `./kbdb-export/` and can be
+overridden via `options.args[0]`.
+
+Output: JSON `{ "path": "...",
+"sections_exported": number,
+"documents_exported": number,
+"elapsed_ms": number }`.
+
 ### `ensureDb`
 
 **File:** `ensure-db.function.ts`
@@ -608,6 +672,7 @@ src/shared/cli/
 ├── run-db-init.spec.ts
 ├── run-db-migrate.spec.ts
 ├── run-learn.spec.ts
+├── run-export.spec.ts
 ├── run-unlearn.spec.ts
 ├── run-search.spec.ts
 ├── run-content.spec.ts

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@dikolab/kbdb",
-   "version": "0.2.2",
+   "version": "0.3.0",
    "description": "CLI tool and MCP server for a file-based knowledge base database",
    "publishConfig": {
       "access": "public"

package/src/shared/cli/functions/dispatch-command.function.ts

@@ -19,6 +19,8 @@ import type { AgentCreateClient } from './run-agent-create.function.ts';
 import type { AgentListClient } from './run-agent-list.function.ts';
 import type { AgentGetClient } from './run-agent-get.function.ts';
 import type { AgentDeleteClient } from './run-agent-delete.function.ts';
+import type { RecallClient } from './run-recall.function.ts';
+import type { ExportClient } from './run-export.function.ts';
 import { runSearch } from './run-search.function.ts';
 import { runLearn } from './run-learn.function.ts';
 import { runUnlearn } from './run-unlearn.function.ts';
@@ -38,6 +40,8 @@ import { runAgentCreate } from './run-agent-create.function.ts';
 import { runAgentList } from './run-agent-list.function.ts';
 import { runAgentGet } from './run-agent-get.function.ts';
 import { runAgentDelete } from './run-agent-delete.function.ts';
+import { runRecall } from './run-recall.function.ts';
+import { runExport } from './run-export.function.ts';
 import { formatOutput } from './format-output.function.ts';
 import { errorToMessage } from './error-to-message.function.ts';
 
@@ -64,7 +68,9 @@ export type DispatchClient = SearchClient &
    AgentCreateClient &
    AgentListClient &
    AgentGetClient &
-   AgentDeleteClient;
+   AgentDeleteClient &
+   RecallClient &
+   ExportClient;
 
 /**
  * Routes a parsed CLI command to the appropriate handler and
@@ -86,6 +92,8 @@ export async function dispatchCommand(
          return handleUnlearn(client, options);
       case 'search':
          return handleSearch(client, options);
+      case 'recall':
+         return handleRecall(client, options);
       case 'content':
          return handleContent(client, options);
       case 'check':
@@ -96,6 +104,8 @@ export async function dispatchCommand(
          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':
@@ -198,6 +208,48 @@ async function handleSearch(
    }
 }
 
+async function handleRecall(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   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: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   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: DispatchClient,
    options: CliOptions,

package/src/shared/cli/functions/format-output.function.ts

@@ -37,12 +37,16 @@ function formatText(paged: PagedSearchDisplay): string {
          const num = paged.offset + i + 1;
          const heading = r.heading ?? '(untitled)';
          const terms = r.matched_terms.join(', ');
+         const fields = r.matched_fields.join(', ');
+         const confidencePct = (r.confidence * 100).toFixed(0);
          return (
             `${String(num)}. [${r.kbid}] ${heading}` +
-            ` (score: ${r.score.toFixed(4)})\n` +
+            ` (score: ${r.score.toFixed(4)},` +
+            ` confidence: ${confidencePct}%)\n` +
             `   ${r.snippet || r.preview || '(no snippet)'}\n` +
             `   type: ${r.type}` +
-            `  terms: ${terms}`
+            `  terms: ${terms}` +
+            (fields ? `  fields: ${fields}` : '')
          );
       })
       .join('\n\n');
@@ -58,14 +62,34 @@ function formatText(paged: PagedSearchDisplay): string {
 }
 
 function formatMcp(paged: PagedSearchDisplay): string {
-   return JSON.stringify({
-      type: 'text',
-      text: paged.items
-         .map(
-            (r) =>
-               `[${r.kbid}] ${r.heading ?? '(untitled)'}` +
-               ` — ${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)'}` +
+                  ` — ${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,
+   );
 }

package/src/shared/cli/functions/generate-help.function.ts

@@ -8,11 +8,13 @@ const KNOWN_COMMANDS = new Set([
    'learn',
    'unlearn',
    'search',
+   'recall',
    'content',
    'check',
    'gc',
    'rebuild',
    'status',
+   'export',
    'mcp',
    'db',
    'skill',
@@ -125,6 +127,8 @@ function generateGlobalHelp(): string {
       ` files/stdin\n` +
       `   unlearn             Remove sections by kbid\n` +
       `   search              Query the knowledge base\n` +
+      `   recall              Retrieve section context` +
+      ` by kbid\n` +
       `   content             Compose rendered content` +
       ` from ids\n` +
       `\n` +
@@ -142,6 +146,8 @@ function generateGlobalHelp(): string {
       `   rebuild             Reconstruct all index` +
       ` files\n` +
       `   status              Show database status\n` +
+      `   export              Snapshot database for` +
+      ` backup\n` +
       `\n` +
       `Skills:\n` +
       `   skill learn         Create a new skill` +
@@ -238,14 +244,20 @@ const LEAF_HELP: Readonly<Record<string, string>> = {
       `   --description <d>   Section description\n` +
       `   --docid <docid>     Document ID to group` +
       ` under\n` +
+      `   --tags <t,...>      Comma-separated tags\n` +
+      `   --replace           Supersede existing section` +
+      ` by source key\n` +
       `   --db <path>         Path to .kbdb directory\n` +
       `\n` +
       `Output:\n` +
-      `   JSON array of { kbid, path, size, skipped }\n` +
+      `   JSON array of { kbid, path, size, skipped,\n` +
+      `                   superseded, warnings,` +
+      ` near_duplicates }\n` +
       `\n` +
       `Examples:\n` +
       `   kbdb learn README.md\n` +
       `   kbdb learn ./docs/\n` +
+      `   kbdb learn --tags auth,api --replace doc.md\n` +
       `   cat notes.txt | kbdb learn -\n`,
 
    unlearn:
@@ -294,6 +306,28 @@ const LEAF_HELP: Readonly<Record<string, string>> = {
       `   kbdb search --limit 5 --format text query\n` +
       `   kbdb search --mode documents --content term\n`,
 
+   recall:
+      `kbdb recall - Retrieve section context by kbid\n` +
+      `\n` +
+      `Usage: kbdb recall [options] <kbid>...\n` +
+      `\n` +
+      `Arguments:\n` +
+      `   <kbid>              26-character knowledge` +
+      ` base identifier\n` +
+      `\n` +
+      `Options:\n` +
+      `   --depth <n>, -d     Expansion depth (0-3,` +
+      ` default: 0)\n` +
+      `   --tags <t,...>      Filter by tags\n` +
+      `   --db <path>         Path to .kbdb directory\n` +
+      `\n` +
+      `Output:\n` +
+      `   JSON RecallResult or RecallResult[]\n` +
+      `\n` +
+      `Examples:\n` +
+      `   kbdb recall abcdef1234567890abcdef1234\n` +
+      `   kbdb recall kbid1 --depth 2\n`,
+
    content:
       `kbdb content - Compose rendered content from ids\n` +
       `\n` +
@@ -372,6 +406,27 @@ const LEAF_HELP: Readonly<Record<string, string>> = {
       `   kbdb status\n` +
       `   kbdb status --db /path/to/project\n`,
 
+   export:
+      `kbdb export - Snapshot database for backup\n` +
+      `\n` +
+      `Usage: kbdb export [options] [<path>]\n` +
+      `\n` +
+      `Arguments:\n` +
+      `   <path>              Output directory path\n` +
+      `                       (default: ./kbdb-export/)\n` +
+      `\n` +
+      `Options:\n` +
+      `   --db <path>         Path to .kbdb directory\n` +
+      `\n` +
+      `Output:\n` +
+      `   JSON { path, sections_exported,` +
+      ` documents_exported }\n` +
+      `\n` +
+      `Examples:\n` +
+      `   kbdb export\n` +
+      `   kbdb export ./my-backup\n` +
+      `   kbdb export --db /path/to/project\n`,
+
    mcp:
       `kbdb mcp - Start MCP server mode (stdio)\n` +
       `\n` +