@dikolab/kbdb 0.3.0 → 0.3.1

package/docs/release-notes/0.3.0.md

@@ -0,0 +1,89 @@
+# 0.3.0
+
+*Minor release -- 2026-06-23*
+
+Adds supersession, relaxed queries, database export,
+tags, and confidence scoring. The Rust engine gains
+source tracking, near-duplicate detection, and
+synonym expansion.
+
+---
+
+## New Features
+
+- **Supersession** -- Re-learning from the same
+  source automatically replaces outdated sections
+  instead of duplicating them. Source key identity
+  tracked via SHA-256.
+
+- **Relaxed OR fallback** -- When an exact AND
+  query returns no results, kbdb automatically
+  retries with relaxed OR matching so you always
+  get the best available results.
+
+- **Database export** -- New `export` CLI command
+  and MCP tool. Copies sections, documents, and
+  catalog as a self-contained directory snapshot.
+
+- **Tags and replace on learn** -- `--tags` attaches
+  labels to imported sections for scoped queries.
+  `--replace` supersedes existing sections from the
+  same source in one step.
+
+- **Confidence scoring** -- Search results include
+  a normalized BM25F confidence score and
+  `matched_fields` (heading, body, code) so agents
+  can tell strong matches from weak ones.
+
+- **Near-duplicate detection** -- Jaccard similarity
+  warns when imported content closely matches an
+  existing section, preventing silent drift.
+
+- **Default skills** -- `db init` installs
+  `query-guidance` and `memory-protocol` skills
+  that teach agents how to search and what to store.
+
+---
+
+## Improvements
+
+- **Synonym expansion pipeline** in the Rust engine
+  broadens keyword coverage automatically.
+
+- **Matched field tracking** -- Results show which
+  fields (heading, body, code) matched the query.
+
+- **`created_at` timestamps** in search results.
+
+- **Divergent content detection** via integrity
+  check catches contradictions between versions.
+
+- **GC fix** -- Garbage collection now only removes
+  superseded sections, not active ones.
+
+- **Reference graph rebuild** included in `rebuild`
+  command.
+
+- **Writer lock** prevents concurrent WASM writes.
+
+- **Worker daemon startup health check** verifies
+  WASM modules load correctly.
+
+---
+
+## Testing
+
+- **517 e2e assertions (Node.js), 514 (Deno)** --
+  all pass with 0 failures.
+
+---
+
+## Upgrade
+
+```sh
+# Node.js
+npm install -g @dikolab/kbdb@0.3.0
+
+# Deno
+deno install -Agf jsr:@dikolab/kbdb/cli
+```

package/docs/release-notes/0.3.1.md

@@ -0,0 +1,111 @@
+# 0.3.1
+
+*Patch release -- 2026-06-23*
+
+Fixes MCP request processing reliability, agent
+document persistence, WASM memory safety, and
+eliminates all e2e test skips. Adds the 20th MCP
+tool (`auto-capture-review`).
+
+---
+
+## Bug Fixes
+
+- **MCP sequential request processing** -- The MCP
+  server previously dispatched JSON-RPC requests
+  concurrently (fire-and-forget). When multiple
+  requests arrived in a batch, later requests could
+  execute before earlier ones finished -- for
+  example, reading an agent document before it was
+  fully written. Requests are now processed
+  sequentially via a promise chain, ensuring each
+  completes before the next begins.
+
+- **Agent document type persistence** -- Agent
+  documents created via `agent-create` were missing
+  their `doc_type` field, so `listDocumentsByType`
+  could not find them. `handleAgentCreate` now
+  passes `'agent'` as the document type.
+
+- **Agent prompt lookup** -- `prompts/get` for
+  agent prompts treated the agent title as a
+  document ID, which failed because document IDs
+  are content hashes. Now looks up agents by title
+  via `listDocumentsByType('agent')`.
+
+- **WASM `worker_remove_grouping` double-free** --
+  The WASM export returned success without calling
+  `set_return`, leaving stale memory in the return
+  slot. The next `readReturnSlot` call freed
+  already-freed memory, causing a WASM trap. Now
+  sets the return slot to null before returning.
+
+- **WASM defensive `set_return` calls** -- Added
+  null return slot initialization to `worker_init`
+  and `worker_init_directory` to prevent the same
+  stale-memory pattern from surfacing in edge cases.
+
+---
+
+## New Features
+
+- **`auto-capture-review` MCP tool** -- Review and
+  approve pending auto-captured knowledge before
+  storage. Accepts `action` parameter with values
+  `list`, `approve`, or `reject`. This brings the
+  MCP server to 20 tools.
+
+---
+
+## Testing
+
+- **548 e2e assertions** on both Node.js and Deno,
+  all passing with **0 failures and 0 skips** (up
+  from 517/514 with some skips in 0.3.0).
+
+- **E2E test restructuring** -- Test databases
+  isolated by category (CLI, MCP, Worker) instead
+  of sharing a flat directory. Worker recall tests
+  now seed their own cross-reference data instead
+  of depending on CLI test data.
+
+- **Pre-built WASM in Docker** -- E2E test
+  container caches WASM binaries at build time,
+  reducing test startup from ~30 seconds to
+  sub-second.
+
+---
+
+## Documentation
+
+- **README.md** reorganized for clarity -- shorter
+  intro, labeled paragraphs ("How search works",
+  "Knowledge stays fresh"), accessible to both
+  technical and non-technical readers.
+
+- **Architecture overview** rewritten -- simplified
+  prose, ASCII architecture diagram, removed stale
+  "Remaining" section (WASM host I/O is fully
+  implemented).
+
+- **MCP server guide** updated with
+  `auto-capture-review` tool in reference tables
+  and annotations summary.
+
+- **Tool counts corrected** across all docs
+  (19 -> 20).
+
+- **Assertion counts updated** across all docs
+  (380+/383 -> 548).
+
+---
+
+## Upgrade
+
+```sh
+# Node.js
+npm install -g @dikolab/kbdb@0.3.1
+
+# Deno
+deno install -Agf jsr:@dikolab/kbdb/cli
+```

package/docs/release-notes/README.md

@@ -2,6 +2,8 @@
 
 ## Releases
 
+- [0.3.1](0.3.1.md) -- MCP reliability fixes, 20 tools, zero test skips
+- [0.3.0](0.3.0.md) -- Supersession, relaxed queries, export, tags, confidence
 - [0.2.0](0.2.0.md) -- Recall, paginated search, reference graph
 - [0.1.3](0.1.3.md) -- Include WASM binaries in JSR package
 - [0.1.2](0.1.2.md) -- Fix WASM loading from JSR

package/package.json

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

package/src/shared/auto-capture/classes/auto-capture-controller.class.ts

@@ -0,0 +1,62 @@
+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';
+import { evaluateTrigger } from '../functions/evaluate-trigger.function.ts';
+
+/**
+ * Controls the auto-capture lifecycle.
+ *
+ * Tracks tool call counts, evaluates trigger conditions, and
+ * advances session state when a capture fires. Reset state on
+ * disconnect or session end via `reset()`.
+ */
+export class AutoCaptureController {
+   private toolCallsSinceLastCapture = 0;
+   private lastCaptureTimestamp = 0;
+   private totalCapturesThisSession = 0;
+   private readonly config: AutoCaptureConfig;
+
+   /** @param config - the auto-capture configuration to use */
+   constructor(config: AutoCaptureConfig) {
+      this.config = config;
+   }
+
+   /** Record one tool call for trigger counting. */
+   recordToolCall(): void {
+      this.toolCallsSinceLastCapture += 1;
+   }
+
+   /**
+    * Evaluates the current state against the trigger criteria.
+    *
+    * When the trigger fires, advances the session counters so the
+    * next evaluation respects rate limiting and the session cap.
+    *
+    * @returns the trigger decision with a human-readable reason
+    */
+   evaluate(): AutoCaptureTrigger {
+      const trigger = evaluateTrigger(this.config, this.state());
+      if (trigger.shouldCapture) {
+         this.totalCapturesThisSession += 1;
+         this.lastCaptureTimestamp = Date.now();
+         this.toolCallsSinceLastCapture = 0;
+      }
+      return trigger;
+   }
+
+   /** Reset all counters, e.g. on client disconnect. */
+   reset(): void {
+      this.toolCallsSinceLastCapture = 0;
+      this.lastCaptureTimestamp = 0;
+      this.totalCapturesThisSession = 0;
+   }
+
+   /** Returns a snapshot of the current controller state. */
+   state(): AutoCaptureState {
+      return {
+         toolCallsSinceLastCapture: this.toolCallsSinceLastCapture,
+         lastCaptureTimestamp: this.lastCaptureTimestamp,
+         totalCapturesThisSession: this.totalCapturesThisSession,
+      };
+   }
+}

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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,27 @@
+/**
+ * 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

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,13 @@
+/** 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

@@ -0,0 +1,13 @@
+/** 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

@@ -0,0 +1,7 @@
+/** 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/global-help.constant.ts

@@ -0,0 +1,73 @@
+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`;