@dikolab/kbdb 0.2.2 → 0.3.1

package/README.md

@@ -12,25 +12,31 @@ required.
 
 ## What is kbdb?
 
-Storing and searching documentation shouldn't
-require setting up a database server, tuning
-indexes, or managing infrastructure.
-
-**kbdb** is a knowledge base that stores your docs
-in a plain folder on disk. No server to install.
-No cloud account to create. It handles indexing
-and fast search out of the box -- just point it
-at your files and start searching.
-
-It runs anywhere Node.js or Deno runs. Import your
-Markdown files, and kbdb indexes them automatically.
+**kbdb** stores your docs in a plain folder on
+disk and makes them searchable. No server to
+install. No cloud account. Import your Markdown
+files, and kbdb indexes them automatically.
 Search returns ranked results instantly.
 
-As a bonus, kbdb also works as an MCP server --
-giving AI agents like Claude a searchable second
-brain. Store skills, agent profiles, and
-documentation that your AI can query across
-sessions.
+It runs anywhere Node.js or Deno runs, and also
+works as an [MCP](https://modelcontextprotocol.io/)
+server -- giving AI agents like Claude a searchable
+second brain that persists between sessions.
+
+**How search works:** kbdb uses keyword matching
+with stemming and synonym expansion (lexical
+search, not AI embeddings). This keeps it fast,
+offline, and deterministic. When an exact query
+returns nothing, it automatically retries with
+relaxed matching. Headings carry 2x ranking weight,
+so clear headings improve results.
+
+**Knowledge stays fresh:** Re-learn a file and kbdb
+replaces the old version automatically.
+Near-duplicate detection warns you before content
+drifts. Integrity checks catch contradictions.
+Confidence scores help agents tell strong matches
+from weak ones.
 
 ---
 
@@ -80,7 +86,9 @@ kbdb learn ./docs --db ./my-kb
 
 Point it at a folder of Markdown files. kbdb reads
 them, breaks them into sections, and builds a
-search index.
+search index. Add `--tags design,v2` to tag
+sections for scoping, or `--replace` to supersede
+existing sections from the same source.
 
 **3. Search**
 
@@ -88,9 +96,11 @@ search index.
 kbdb search "how does auth work" --db ./my-kb
 ```
 
-Results are ranked by relevance with snippets
-showing matched terms in context. Use `--offset`
-to page through large result sets.
+Results are ranked by relevance with confidence
+scores and snippets showing matched terms in
+context. Each result includes `matched_fields`
+(heading, body, code) and `created_at` timestamps.
+Use `--offset` to page through large result sets.
 
 **4. Recall context**
 
@@ -109,18 +119,24 @@ referenced sections.
 
 ## What Can It Do?
 
-- **Import** Markdown files and other documents
-- **Search** with ranked results, snippets, and
-  paginated output
+- **Import** Markdown files and other documents,
+  with tags and source tracking
+- **Supersede** outdated sections automatically
+  when re-learning from the same source
+- **Search** with ranked results, confidence
+  scores, snippets, and paginated output
+- **Relaxed fallback** -- automatic OR retry when
+  exact AND queries return nothing
 - **Recall** sections with progressive context --
   from a quick summary to full related content
+- **Export** the database as a portable snapshot
 - **Skills** -- store reusable prompt templates
   with placeholder arguments
 - **Agents** -- create AI agent profiles that
   combine a persona with skills
 - **Manage** documents, sections, and metadata
-- **Verify** database integrity and clean up
-  unused data
+- **Verify** database integrity, detect
+  contradictions, and clean up superseded data
 - **Rebuild** indexes if anything goes wrong
 
 See the [CLI Reference](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/details/cli.md)
@@ -132,10 +148,10 @@ for the full command list and examples.
 
 kbdb runs as an
 [MCP](https://modelcontextprotocol.io/) server
-with 18 tools, so AI agents can search your docs,
-recall context progressively, store reusable
-skills, and build agent profiles -- a second brain
-that persists between sessions.
+with 20 tools, so AI agents can search your docs,
+recall context progressively, export snapshots,
+store reusable skills, and build agent profiles --
+a second brain that persists between sessions.
 
 ### Claude Code (CLI)
 
@@ -230,7 +246,7 @@ const results = await client.search({
    offset: 0,
 });
 
-// results = { items, total, offset, limit, has_more }
+// results = { items, total, offset, limit, has_more, relaxed }
 console.log(results.items);
 client.disconnect();
 ```

package/dist/bench/constants/corpus-defaults.constant.d.ts

@@ -0,0 +1,3 @@
+import type { CorpusConfig } from '../typings/corpus-config.interface.ts';
+/** Default corpus generation settings. */
+export declare const CORPUS_DEFAULTS: CorpusConfig;

package/dist/bench/functions/format-report.function.d.ts

@@ -0,0 +1,11 @@
+import type { BenchSuiteResult } from '../typings/bench-suite-result.interface.ts';
+/**
+ * Formats benchmark results as a Markdown table.
+ *
+ * Renders a header row, a separator, and one data row per
+ * result in the suite.
+ *
+ * @param suite - completed benchmark suite to render
+ * @returns multi-line Markdown table string
+ */
+export declare function formatReport(suite: BenchSuiteResult): string;

package/dist/bench/functions/generate-corpus.function.d.ts

@@ -0,0 +1,12 @@
+import type { CorpusConfig } from '../typings/corpus-config.interface.ts';
+import type { CorpusSection } from '../typings/corpus-section.interface.ts';
+/**
+ * Generates a synthetic corpus of sections.
+ *
+ * Uses Zipfian word frequency distribution for realistic
+ * token patterns. Output is deterministic for the same seed.
+ *
+ * @param config - corpus generation parameters
+ * @returns array of generated corpus sections
+ */
+export declare function generateCorpus(config: CorpusConfig): CorpusSection[];

package/dist/bench/functions/measure-operation.function.d.ts

@@ -0,0 +1,14 @@
+import type { BenchResult } from '../typings/bench-result.interface.ts';
+/**
+ * Measures the duration of an async operation.
+ *
+ * Runs one warmup call then measures N iterations, returning
+ * the median duration. Uses `performance.now()` for timing.
+ *
+ * @param name - label for the operation
+ * @param corpusSize - corpus size associated with this run
+ * @param operation - the function to benchmark
+ * @param iterations - number of measured iterations (default 3)
+ * @returns benchmark result with median timing
+ */
+export declare function measureOperation(name: string, corpusSize: number, operation: () => Promise<void> | void, iterations?: number): Promise<BenchResult>;

package/dist/bench/functions/seeded-rng.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates a deterministic pseudo-random number generator
+ * using a linear congruential algorithm.
+ *
+ * Each call to the returned function advances the internal
+ * state and returns the next value in [0, 1).
+ *
+ * @param seed - initial state for the LCG sequence
+ * @returns a stateful RNG function producing values in [0, 1)
+ */
+export declare function seededRng(seed: number): () => number;

package/dist/bench/functions/zipf-word.function.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Selects a word index using Zipfian distribution.
+ *
+ * Higher-ranked words (lower indices) appear more frequently,
+ * modeling natural language word frequencies. Uses inverse CDF
+ * approximation: `floor(vocabSize * (1 - rng()^(1/s)))` where
+ * s ≈ 1.07 maps uniform random values to rank-biased indices.
+ *
+ * @param rng - stateful random number generator in [0, 1)
+ * @param vocabSize - total vocabulary size (exclusive upper bound)
+ * @returns integer index in [0, vocabSize)
+ */
+export declare function zipfWord(rng: () => number, vocabSize: number): number;

package/dist/bench/index.d.ts

@@ -0,0 +1,10 @@
+export type { CorpusConfig } from './typings/corpus-config.interface.ts';
+export type { CorpusSection } from './typings/corpus-section.interface.ts';
+export type { BenchResult } from './typings/bench-result.interface.ts';
+export type { BenchSuiteResult } from './typings/bench-suite-result.interface.ts';
+export { CORPUS_DEFAULTS } from './constants/corpus-defaults.constant.ts';
+export { seededRng } from './functions/seeded-rng.function.ts';
+export { zipfWord } from './functions/zipf-word.function.ts';
+export { generateCorpus } from './functions/generate-corpus.function.ts';
+export { measureOperation } from './functions/measure-operation.function.ts';
+export { formatReport } from './functions/format-report.function.ts';

package/dist/bench/typings/bench-result.interface.d.ts

@@ -0,0 +1,11 @@
+/** Result of a single benchmark run. */
+export interface BenchResult {
+    /** Operation name. */
+    readonly operation: string;
+    /** Corpus size. */
+    readonly corpusSize: number;
+    /** Duration in milliseconds. */
+    readonly durationMs: number;
+    /** Operations per second. */
+    readonly opsPerSec: number;
+}

package/dist/bench/typings/bench-suite-result.interface.d.ts

@@ -0,0 +1,10 @@
+import type { BenchResult } from './bench-result.interface.ts';
+/** Results from a complete benchmark suite. */
+export interface BenchSuiteResult {
+    /** Individual benchmark results. */
+    readonly results: BenchResult[];
+    /** Timestamp of the run. */
+    readonly timestamp: string;
+    /** System info. */
+    readonly system: string;
+}

package/dist/bench/typings/corpus-config.interface.d.ts

@@ -0,0 +1,11 @@
+/** Configuration for synthetic corpus generation. */
+export interface CorpusConfig {
+    /** Number of sections to generate. */
+    readonly count: number;
+    /** Seed for deterministic RNG. */
+    readonly seed: number;
+    /** Average tokens per section. */
+    readonly avgTokens: number;
+    /** Vocabulary size. */
+    readonly vocabSize: number;
+}

package/dist/bench/typings/corpus-section.interface.d.ts

@@ -0,0 +1,9 @@
+/** A generated section for benchmarking. */
+export interface CorpusSection {
+    /** Section heading. */
+    readonly heading: string;
+    /** Section body text. */
+    readonly body: string;
+    /** Source key for dedup. */
+    readonly sourceKey: string;
+}