@dikolab/kbdb 0.3.1 → 0.4.0

package/src/shared/auto-capture/constants/auto-capture-defaults.constant.ts

@@ -1,15 +0,0 @@
-import type { AutoCaptureConfig } from '../typings/auto-capture-config.interface.ts';
-
-/**
- * Default configuration for the auto-capture feature.
- *
- * Auto-capture is disabled by default. Enable it in
- * `worker.toml` under `[auto_capture]`.
- */
-export const AUTO_CAPTURE_DEFAULTS: AutoCaptureConfig = {
-   enabled: false,
-   triggerAfterToolCalls: 5,
-   minIntervalMs: 60_000,
-   maxCapturesPerSession: 10,
-   dryRun: false,
-};

package/src/shared/auto-capture/functions/build-capture-prompt.function.ts

@@ -1,27 +0,0 @@
-/**
- * Builds the MCP sampling prompt for knowledge extraction.
- *
- * Instructs the host LLM to identify durable factual knowledge
- * from the recent conversation context, filter out ephemeral or
- * task-specific information, and format the result for storage
- * following memory-protocol criteria.
- *
- * @param recentContext - the conversation excerpt to analyse
- */
-export function buildCapturePrompt(recentContext: string): string {
-   return (
-      'Review the following conversation context and identify' +
-      ' factual knowledge worth storing in the knowledge base.\n\n' +
-      'Rules:\n' +
-      '- Include durable facts, decisions, preferences, and' +
-      ' corrections that would be useful in future sessions.\n' +
-      '- Exclude ephemeral, task-specific, or temporary information' +
-      ' that has no lasting value.\n' +
-      '- Format each piece of extracted knowledge as a concise' +
-      ' statement suitable for direct storage.\n' +
-      '- If no durable knowledge is found, respond with an empty' +
-      ' list.\n\n' +
-      'Conversation context:\n' +
-      recentContext
-   );
-}

package/src/shared/auto-capture/functions/evaluate-trigger.function.ts

@@ -1,50 +0,0 @@
-import type { AutoCaptureConfig } from '../typings/auto-capture-config.interface.ts';
-import type { AutoCaptureState } from '../typings/auto-capture-state.interface.ts';
-import type { AutoCaptureTrigger } from '../typings/auto-capture-trigger.interface.ts';
-
-/**
- * Evaluates whether auto-capture should fire given the current
- * configuration and runtime state.
- *
- * Checks (in order): feature flag, session cap, rate limit,
- * and tool-call count threshold. Returns the first failing
- * condition as the reason.
- */
-export function evaluateTrigger(
-   config: AutoCaptureConfig,
-   state: AutoCaptureState,
-): AutoCaptureTrigger {
-   if (!config.enabled) {
-      return {
-         shouldCapture: false,
-         reason: 'auto-capture is disabled',
-      };
-   }
-
-   if (state.totalCapturesThisSession >= config.maxCapturesPerSession) {
-      return {
-         shouldCapture: false,
-         reason: 'session capture limit reached',
-      };
-   }
-
-   const elapsed = state.lastCaptureTimestamp
-      ? Date.now() - state.lastCaptureTimestamp
-      : Infinity;
-
-   if (elapsed < config.minIntervalMs) {
-      return {
-         shouldCapture: false,
-         reason: 'within minimum interval',
-      };
-   }
-
-   if (state.toolCallsSinceLastCapture < config.triggerAfterToolCalls) {
-      return {
-         shouldCapture: false,
-         reason: 'tool call threshold not yet reached',
-      };
-   }
-
-   return { shouldCapture: true, reason: 'trigger threshold met' };
-}

package/src/shared/auto-capture/index.ts

@@ -1,7 +0,0 @@
-export { AutoCaptureController } from './classes/auto-capture-controller.class.ts';
-export { AUTO_CAPTURE_DEFAULTS } from './constants/auto-capture-defaults.constant.ts';
-export { evaluateTrigger } from './functions/evaluate-trigger.function.ts';
-export { buildCapturePrompt } from './functions/build-capture-prompt.function.ts';
-export type { AutoCaptureConfig } from './typings/auto-capture-config.interface.ts';
-export type { AutoCaptureTrigger } from './typings/auto-capture-trigger.interface.ts';
-export type { AutoCaptureState } from './typings/auto-capture-state.interface.ts';

package/src/shared/auto-capture/typings/auto-capture-config.interface.ts

@@ -1,13 +0,0 @@
-/** Configuration for auto-capture behavior. */
-export interface AutoCaptureConfig {
-   /** Enable or disable auto-capture. */
-   readonly enabled: boolean;
-   /** Trigger a capture after this many tool calls. */
-   readonly triggerAfterToolCalls: number;
-   /** Minimum time in milliseconds between captures. */
-   readonly minIntervalMs: number;
-   /** Maximum number of captures allowed per session. */
-   readonly maxCapturesPerSession: number;
-   /** Log without writing when true. */
-   readonly dryRun: boolean;
-}

package/src/shared/auto-capture/typings/auto-capture-state.interface.ts

@@ -1,13 +0,0 @@
-/** Runtime state tracked by the auto-capture controller. */
-export interface AutoCaptureState {
-   /** Tool calls recorded since the last successful capture. */
-   readonly toolCallsSinceLastCapture: number;
-   /**
-    * Unix epoch milliseconds of the most recent capture.
-    *
-    * Zero when no capture has occurred this session.
-    */
-   readonly lastCaptureTimestamp: number;
-   /** Total captures completed during the current session. */
-   readonly totalCapturesThisSession: number;
-}

package/src/shared/auto-capture/typings/auto-capture-trigger.interface.ts

@@ -1,7 +0,0 @@
-/** Result of evaluating whether auto-capture should fire. */
-export interface AutoCaptureTrigger {
-   /** Whether a capture should be triggered. */
-   readonly shouldCapture: boolean;
-   /** Human-readable reason for the decision. */
-   readonly reason: string;
-}

package/src/shared/cli/constants/defaults.constant.ts

@@ -1,19 +0,0 @@
-/** Default maximum number of search results returned per query. */
-export const DEFAULT_LIMIT = 20;
-
-/** Default output format when `--format` is not specified. */
-export const DEFAULT_FORMAT = 'json' as const;
-
-/** Default search mode when `--mode` is not specified. */
-export const DEFAULT_MODE = 'sections' as const;
-
-/**
- * File extensions recognised as importable documents by the learn
- * command. Extensions are lowercase and include the leading dot.
- */
-export const SUPPORTED_EXTENSIONS = [
-   '.md',
-   '.txt',
-   '.rst',
-   '.adoc',
-] as const;

package/src/shared/cli/constants/global-help.constant.ts

@@ -1,73 +0,0 @@
-import { VERSION } from '../../version/index.ts';
-
-/**
- * Top-level help text displayed when no command is given or when
- * `--help` is passed without a command name.
- *
- * Lists all available commands grouped by category and describes
- * global options.
- */
-export const GLOBAL_HELP =
-   `kbdb v${VERSION} - File-based knowledge base` +
-   ` database for AI agents\n` +
-   `\n` +
-   `Usage: kbdb [options]\n` +
-   `       kbdb <command> [options] ...[parameters]\n` +
-   `       kbdb <command> <subcommand> [options]` +
-   ` ...[params]\n` +
-   `\n` +
-   `Knowledge Base:\n` +
-   `   learn               Import content from` +
-   ` 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` +
-   `Database:\n` +
-   `   db init             Initialise a new .kbdb` +
-   ` directory\n` +
-   `   db migrate          Migrate database to current` +
-   ` format\n` +
-   `\n` +
-   `Maintenance:\n` +
-   `   check               Verify knowledge base` +
-   ` integrity\n` +
-   `   gc                  Garbage collect unreferenced\n` +
-   `                       sections\n` +
-   `   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` +
-   ` definition\n` +
-   `   skill list          List all skills\n` +
-   `   skill get           Retrieve a skill by name` +
-   ` or kbid\n` +
-   `   skill delete        Remove a skill\n` +
-   `\n` +
-   `Agents:\n` +
-   `   agent create        Create an agent with skill` +
-   ` refs\n` +
-   `   agent list          List all agents\n` +
-   `   agent get           Retrieve an agent by docid\n` +
-   `   agent delete        Remove an agent\n` +
-   `\n` +
-   `Server:\n` +
-   `   mcp                 Start MCP server mode` +
-   ` (stdio)\n` +
-   `\n` +
-   `Global Options:\n` +
-   `   -h, --help          Show this help message\n` +
-   `   -v, --version       Show version information\n` +
-   `   --db <path>         Path to .kbdb directory\n` +
-   `   --format <fmt>      Output format` +
-   ` (json|text|mcp)\n` +
-   `\n` +
-   `Run "kbdb <command> --help" for detailed` +
-   ` information.\n`;

package/src/shared/cli/constants/help-text.constant.ts

@@ -1,4 +0,0 @@
-import { generateHelp } from '../functions/generate-help.function.ts';
-
-/** Global help text for the kbdb CLI. */
-export const HELP_TEXT = generateHelp();

package/src/shared/cli/constants/leaf-help.constant.ts

@@ -1,219 +0,0 @@
-/**
- * Help text strings keyed by top-level command name.
- *
- * Used by `generateHelp` to display per-command documentation
- * when the user runs `kbdb <command> --help`.
- */
-export const LEAF_HELP: Readonly<Record<string, string>> = {
-   learn:
-      `kbdb learn - Import content from files or stdin\n` +
-      `\n` +
-      `Usage: kbdb learn [options] <path | ->...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <path | ->          File path, directory,` +
-      ` or - for stdin\n` +
-      `\n` +
-      `Options:\n` +
-      `   --title <title>     Section title\n` +
-      `   --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` +
-      `                   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:
-      `kbdb unlearn - Remove sections by kbid\n` +
-      `\n` +
-      `Usage: kbdb unlearn [options] <kbid>...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <kbid>              26-character knowledge` +
-      ` base identifier\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON array of { kbid, removed }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb unlearn abcdef1234567890abcdef1234\n` +
-      `   kbdb unlearn id1 id2 id3\n`,
-
-   search:
-      `kbdb search - Query the knowledge base\n` +
-      `\n` +
-      `Usage: kbdb search [options] <query>...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <query>             One or more query terms\n` +
-      `\n` +
-      `Options:\n` +
-      `   --mode <mode>       Result granularity` +
-      ` (sections|documents|stats)\n` +
-      `   --limit <n>         Max results (default: 20)\n` +
-      `   --format <fmt>      Output format` +
-      ` (json|text|mcp)\n` +
-      `   --content, -c       Hydrate results with` +
-      ` section content\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON array of { kbid, score, preview,` +
-      ` matches }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb search "machine learning"\n` +
-      `   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` +
-      `Usage: kbdb content [options] <id>...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <id>                kbid or docid identifier\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { type, data, total }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb content abcdef1234567890abcdef1234\n` +
-      `   kbdb content id1 id2\n`,
-
-   check:
-      `kbdb check - Verify knowledge base integrity\n` +
-      `\n` +
-      `Usage: kbdb check [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { ok, errors }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb check\n` +
-      `   kbdb check --db /path/to/project\n`,
-
-   gc:
-      `kbdb gc - Garbage collect unreferenced sections\n` +
-      `\n` +
-      `Usage: kbdb gc [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { removed_sections, removed_bytes }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb gc\n` +
-      `   kbdb gc --db /path/to/project\n`,
-
-   rebuild:
-      `kbdb rebuild - Reconstruct all index files\n` +
-      `\n` +
-      `Usage: kbdb rebuild [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { sections_reindexed, terms_indexed }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb rebuild\n` +
-      `   kbdb rebuild --db /path/to/project\n`,
-
-   status:
-      `kbdb status - Show database status\n` +
-      `\n` +
-      `Usage: kbdb status [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON database status object\n` +
-      `\n` +
-      `Examples:\n` +
-      `   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` +
-      `Usage: kbdb mcp [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Environment:\n` +
-      `   KBDB_DIR            Fallback database path\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb mcp --db /path/to/project\n` +
-      `   KBDB_DIR=/path/to/project kbdb mcp\n`,
-};

package/src/shared/cli/constants/memory-protocol-body.constant.ts

@@ -1,39 +0,0 @@
-/**
- * Body text for the `memory-protocol` default skill.
- *
- * Teaches AI agents when and what to store in the knowledge base
- * to keep it accurate and useful.
- */
-export const MEMORY_PROTOCOL_BODY =
-   'Follow these guidelines to keep the knowledge base accurate' +
-   ' and useful:\n\n' +
-   '1. 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\n' +
-   '2. 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\n' +
-   '3. 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\n' +
-   '4. 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\n' +
-   '5. 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\n' +
-   '6. 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\n' +
-   '7. USE RECALL AFTER SEARCH. After finding relevant sections,' +
-   ' use recall with increasing depth (0-3) to expand context' +
-   ' progressively before making decisions.\n\n' +
-   '8. INCLUDE HEADINGS. Always provide a descriptive title when' +
-   ' storing content. Headings carry 2x ranking weight -- omitting' +
-   ' them significantly reduces searchability.';

package/src/shared/cli/constants/query-guidance-body.constant.ts

@@ -1,37 +0,0 @@
-/**
- * Body text for the `query-guidance` default skill.
- *
- * Teaches AI agents how to effectively search the knowledge base
- * using lexical BM25F queries.
- */
-export const QUERY_GUIDANCE_BODY =
-   'This knowledge base uses lexical search (stemmed BM25F), not' +
-   ' semantic/vector search. Follow these guidelines for effective' +
-   ' retrieval:\n\n' +
-   '1. Issue MULTIPLE short keyword queries rather than one long' +
-   ' natural-language question. Each query should target 2-3' +
-   ' specific terms.\n\n' +
-   '2. 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\n' +
-   '3. 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\n' +
-   '4. LEAN ON HEADINGS. Headings carry 2x weight in ranking.' +
-   ' Search for terms that are likely in section titles.\n\n' +
-   '5. STEMMING IS AUTOMATIC. "connections" matches "connect",' +
-   ' "running" matches "run". You do not need to try inflected' +
-   ' forms.\n\n' +
-   '6. 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\n' +
-   '7. CODE IDENTIFIERS ARE SPLIT. camelCase and snake_case names' +
-   ' are decomposed: getUserById becomes searchable as "get",' +
-   ' "user", "by", "id".\n\n' +
-   '8. PAGINATION. Default limit is 20 results. Use offset for' +
-   ' additional pages if total > limit.';