@dikolab/kbdb 0.4.3 → 0.6.0

package/docs/modules/typescript/shared/worker-daemon/typings.md

@@ -1,132 +0,0 @@
-# worker-daemon/typings -- Daemon Type Definitions
-
-*Interfaces and type aliases for daemon configuration,
-IPC message shapes, and WASM module references.*
-
-## Source
-
-`src/shared/worker-daemon/typings/`
-
-## Typings
-
-### `DaemonConfig`
-
-**File:** `daemon-config.interface.ts`
-
-Parsed contents of `worker.toml`. Missing keys use
-defaults from
-[daemon-defaults.constant.ts](constants.md).
-
-```ts
-interface DaemonConfig {
-   readonly contextPath: string;
-   readonly itemLimit: number;
-   readonly indexLimit: number;
-   readonly timeoutMs: number;
-   readonly itemTtlMs: number;
-}
-```
-
-| Property      | Type     | Default  | Description       |
-|---------------|----------|----------|-------------------|
-| `contextPath` | `string` | --       | Absolute path to  |
-|               |          |          | the context dir   |
-| `itemLimit`   | `number` | `1000`   | Max content items |
-|               |          |          | in cache          |
-| `indexLimit`  | `number` | `100`    | Max index entries |
-|               |          |          | in cache          |
-| `timeoutMs`   | `number` | `300000` | Daemon idle       |
-|               |          |          | timeout (ms)      |
-| `itemTtlMs`   | `number` | `60000`  | Per-item cache    |
-|               |          |          | TTL (ms)          |
-
-### `IpcRequest`
-
-**File:** `ipc-handler.interface.ts`
-
-A JSON-RPC 2.0 request sent to the daemon over IPC.
-
-```ts
-interface IpcRequest {
-   readonly jsonrpc: '2.0';
-   readonly id: number | string;
-   readonly method: string;
-   readonly params?: unknown;
-}
-```
-
-### `IpcErrorDetail`
-
-**File:** `ipc-handler.interface.ts`
-
-Error detail included in a failed JSON-RPC response.
-
-```ts
-interface IpcErrorDetail {
-   readonly code: number;
-   readonly message: string;
-   readonly data?: unknown;
-}
-```
-
-### `IpcResponse`
-
-**File:** `ipc-handler.interface.ts`
-
-A JSON-RPC 2.0 response returned by the daemon.
-
-```ts
-interface IpcResponse {
-   readonly jsonrpc: '2.0';
-   readonly id: number | string;
-   readonly result?: unknown;
-   readonly error?: IpcErrorDetail;
-}
-```
-
-### `IpcHandler`
-
-**File:** `ipc-handler.interface.ts`
-
-Function type for handling a single IPC request and
-returning a JSON-RPC response.
-
-```ts
-type IpcHandler = (
-   request: IpcRequest,
-) => Promise<IpcResponse>;
-```
-
-The `WorkerDaemon.handleRequest` method satisfies this
-type and is passed to `createIpcServer`.
-
-### `WasmModules`
-
-**File:** `wasm-modules.interface.ts`
-
-References to the compiled and instantiated WASM
-modules and their shared exported memory.
-
-```ts
-interface WasmModules {
-   readonly memory: WebAssembly.Memory;
-   readonly kbWorker: WebAssembly.Instance;
-   readonly embedding?: WebAssembly.Instance;
-}
-```
-
-| Property    | Type                   | Description            |
-|-------------|------------------------|------------------------|
-| `memory`    | `WebAssembly.Memory`   | Linear memory exported |
-|             |                        | by `kb-worker.wasm`    |
-| `kbWorker`  | `WebAssembly.Instance` | Instantiated           |
-|             |                        | `kb-worker.wasm`       |
-| `embedding` | `WebAssembly.Instance?`| Instantiated           |
-|             |                        | `default-embedding.wasm`. |
-|             |                        | Optional -- absent only |
-|             |                        | when build omits the   |
-|             |                        | embedding crate.       |
-
-Returned by `loadWasmModules()`.
-
-No spec -- typings are compile-time only.

package/docs/overview.md

@@ -1,191 +0,0 @@
-# @dikolab/kbdb -- Knowledge Base Database
-
-*A file-based knowledge store and MCP server for
-AI agents -- your second brain, on disk.*
-
-## What Is kbdb?
-
-AI agents forget everything between sessions. kbdb
-gives them a searchable, persistent memory.
-
-Import your documents, and kbdb indexes them
-automatically. Search returns ranked results
-instantly. No database server to install, no cloud
-account to create -- your knowledge base is just a
-folder on disk.
-
-kbdb works as both a command-line tool and an
-[MCP](https://modelcontextprotocol.io/) server.
-Humans use it from the terminal; AI agents connect
-to it as a tool.
-
-## Who Is This For?
-
-- **AI agent developers** -- persistent, searchable
-  knowledge across agent sessions
-- **MCP tool authors** -- a local knowledge backend
-  for Model Context Protocol servers
-- **Knowledge workers** -- a second brain your AI
-  assistant can search across conversations
-- **Vibe coders** -- a searchable doc store for
-  your AI-assisted projects
-- **CLI-first developers** -- composable commands
-  for managing knowledge from the terminal
-
-## What Can It Do?
-
-- **Import** Markdown files with automatic keyword
-  extraction and indexing
-- **Search** three ways: keyword (default),
-  hybrid, or AI similarity via `--algo`
-- **Auto-fallback** -- loosens your query when
-  exact matches return nothing
-- **Recall** sections with progressive context
-  (depth 0--3)
-- **Smart updates** -- re-learning a file replaces
-  the old version, not duplicates it
-- **Near-duplicate detection** -- warns when
-  imported content closely matches existing data
-- **Skills** -- reusable prompt templates with
-  fill-in-the-blank arguments
-- **Agents** -- AI profiles combining a persona
-  with skills
-- **Auto-capture** -- MCP server proactively
-  suggests knowledge to store from conversations
-- **Export and sync** -- snapshot your knowledge
-  base for backup or sharing across machines
-- **Verify** database integrity and clean up stale
-  data
-- **MCP server** with 20 tools, prompts, resources,
-  and completions
-
-### Install
-
-```sh
-# Node.js
-npm install -g @dikolab/kbdb
-
-# Deno
-deno add @dikolab/kbdb
-```
-
-## Architecture
-
-Five layers, top to bottom:
-
-```
-User / AI Agent
-  -> kbdb command (CLI or MCP mode)
-    -> Worker Client (TypeScript IPC)
-      -> Worker Daemon (background process)
-        -> Rust/WASM Engine
-          -> File Database (folder on disk)
-```
-
-**kbdb command** -- One executable, two modes. CLI
-mode runs short-lived commands (`learn`, `search`,
-`recall`). MCP mode starts a long-lived server for
-AI agents over stdio.
-
-**Worker Client** -- Connects to the background
-daemon and gives your code a typed API.
-
-**Worker Daemon** -- Background process that loads
-the search engine, caches data in memory, and
-handles requests.
-
-**Search Engine** -- Compiled from Rust to
-WebAssembly for speed. Three modules handle
-tokenization, indexing, ranking, and file I/O.
-
-**File Database** -- Structured folder on disk.
-No server process. Portable, version-controllable,
-and human-readable.
-
-### Technology Stack
-
-| Layer | Technology | What it does |
-|-------|-----------|--------------|
-| Runtime | Node.js, Deno | Runs the tools |
-| Language | TypeScript | CLI, MCP server, I/O |
-| Engine | Rust -> WebAssembly | Fast indexing and search |
-| Protocol | MCP | AI agent integration |
-| Distribution | NPM, JSR | Install from either |
-| Storage | File database | Your data, in a folder |
-
-## Design Principles
-
-1. **No server needed** -- A folder is your whole
-   database. Works anywhere.
-2. **Built for AI agents** -- Commands and output
-   are optimized for machine use.
-3. **MCP-first** -- The MCP server is a primary
-   interface, not an add-on.
-4. **Fast** -- Heavy work runs in compiled Rust
-   via WebAssembly.
-5. **Portable** -- Runs on Node.js or Deno. The
-   database is a plain directory.
-6. **Section-level search** -- Returns the specific
-   passage that matters, not a whole document.
-
-## Design Documents
-
-Deeper docs for each part of the system. You don't
-need to read these to use kbdb -- they're here for
-contributors and anyone curious about internals.
-
-- **[Database](goals/database.md)** -- File storage
-  engine, directory structure, section and document
-  operations
-- **[Query Parser](goals/query-parser.md)** --
-  Tokenization, query parsing, keyword extraction,
-  ranking
-- **[Hybrid Search](goals/hybrid-search.md)** --
-  Lexical + vector retrieval with score fusion
-- **[Document](goals/document.md)** -- Content format
-  with markers and cross-references
-- **[Content Parser](goals/content-parser.md)** --
-  Marker extraction from section content
-- **[Content Composer](goals/content-composer.md)** --
-  Rendered Markdown composition from identifiers
-- **[CLI](goals/cli.md)** -- Commands, run modes,
-  output formats
-- **[MCP](goals/mcp.md)** -- MCP server, tools,
-  resources, agent wiring
-- **[Auto-Capture](goals/auto-capture.md)** --
-  Proactive knowledge capture via MCP sampling
-- **[Sync](goals/sync.md)** -- Cross-machine export
-  and import
-- **[Worker Daemon](goals/worker-daemon.md)** --
-  Background daemon, WASM loading, caching, IPC
-- **[Worker Client](goals/worker-client.md)** --
-  Client module, daemon discovery, typed API
-
-## Project Status
-
-All layers are wired and working end-to-end. Every
-core operation -- learn, search, recall, content
-retrieval, skills, agents, export, and maintenance
--- runs through the full stack.
-
-**548 e2e assertions** pass on both Node.js and Deno
-with zero failures and zero skips.
-
-- 18 CLI commands across 6 groups
-- 20 MCP tools with prompts, resources, completions
-- Three search algorithms: lexical, vector, hybrid
-- Sequential MCP request processing
-- Worker daemon with fully implemented WASM host I/O
-- Paginated search with rich metadata
-- Progressive recall at depths 0--3
-- Bidirectional reference graph
-- Skills and agent document management
-- Auto-capture hooks via MCP sampling
-- Export/import sync primitives
-- esbuild bundling (ESM + CJS + .d.ts)
-- Docker build containers
-- npm and JSR packages with documentation
-
-## Links
-
-- **Repository**: https://gitlab.com/tech-slaves/knowledge-base-db

package/docs/release-notes/0.1.0.md

@@ -1,189 +0,0 @@
-# 0.1.0
-
-*Initial release -- 2026-06-19*
-
-The first public release of **@dikolab/kbdb**, a
-file-based knowledge base database that stores,
-indexes, and searches documentation without needing
-a database server.
-
----
-
-## Highlights
-
-- Store documentation in a plain folder on disk --
-  no server, no cloud account, no infrastructure
-- Ranked search powered by a Rust/WASM engine
-- CLI with 17 commands for managing documents,
-  skills, and agents
-- MCP server that gives AI agents a searchable
-  second brain
-- Runs on both Node.js (>= 20) and Deno (>= 2)
-
----
-
-## Installation
-
-```sh
-# Node.js
-npm install -g @dikolab/kbdb
-
-# Deno
-deno install -Agf jsr:@dikolab/kbdb/cli
-```
-
----
-
-## CLI
-
-The `kbdb` command organises 17 commands across
-6 groups:
-
-| Group | Commands |
-|-------|----------|
-| Knowledge Base | `learn`, `unlearn`, `search`, `content` |
-| Database | `db init`, `db migrate` |
-| Maintenance | `status`, `check`, `gc`, `rebuild` |
-| Skills | `skill learn`, `skill list`, `skill get`, `skill delete` |
-| Agents | `agent create`, `agent list`, `agent get`, `agent delete` |
-| Server | `mcp` |
-
-See the [CLI Reference](../details/cli.md) for
-options and examples.
-
----
-
-## Search and Ranking
-
-Search uses **BM25F** field-weighted ranking with
-three indexed fields per section:
-
-| Field | Weight | Description |
-|-------|--------|-------------|
-| Heading | 2.0x | Titles and headings |
-| Body | 1.0x | Main text content |
-| Code | 1.5x | Code blocks and inline code |
-
-Queries support keywords, exact phrases
-(`"error handling"`), boolean operators
-(`auth AND token`, `cache OR redis`), and term
-exclusions (`auth -oauth`).
-
-See [How Search Works](../details/search-and-ranking.md)
-for internals.
-
----
-
-## MCP Server
-
-The `kbdb mcp` command starts an MCP server over
-stdio using JSON-RPC 2.0 (MCP Protocol 2025-11-25).
-
-**17 tools** available to AI agents:
-
-- **Knowledge Base**: `search`, `learn`, `unlearn`,
-  `retrieve`, `content`
-- **Database**: `status`, `check`, `gc`, `rebuild`
-- **Skills**: `skill-learn`, `skill-list`,
-  `skill-get`, `skill-delete`
-- **Agents**: `agent-create`, `agent-list`,
-  `agent-get`, `agent-delete`
-
-Works with Claude Code, Claude for VS Code,
-Claude Desktop, and any MCP-compatible agent.
-See the [MCP Server Guide](../details/mcp-server.md)
-for setup instructions.
-
----
-
-## Skills and Agents
-
-**Skills** are reusable templates with placeholder
-arguments. Store common prompts or instructions
-once and reference them by name.
-
-**Agents** are AI agent profiles that combine a
-persona with a set of skills. Create named agent
-configurations that persist across sessions.
-
----
-
-## Storage
-
-All data lives in a `.kbdb` directory on disk:
-
-```
-.kbdb/
-   catalog.toml       -- version and stats
-   corpus.bin          -- term frequencies
-   sections/           -- indexed content
-   documents/          -- document groupings
-```
-
-Content is identified by **kbid** -- a content-
-addressed ID derived from SHA-256 (128-bit
-truncation, base32-encoded). Identical content
-always produces the same kbid.
-
-See [Storage Architecture](../details/storage.md)
-for file formats and design details.
-
----
-
-## Rust/WASM Engine
-
-The search engine is written in Rust and compiled
-to WebAssembly. Four crates handle different
-responsibilities:
-
-| Crate | Role |
-|-------|------|
-| `kbdb-shared` | Memory management, encoding, error types |
-| `kbdb-fs-database` | Storage, indexing, search |
-| `kbdb-query-parser` | Query tokenization and parsing |
-| `kbdb-worker` | IPC request dispatch |
-
-WASM modules load at runtime -- no native
-compilation needed on the user's machine.
-
----
-
-## Build Pipeline
-
-Development uses a Docker-based build pipeline
-that includes Node.js, Deno, Rust, and wasm-pack:
-
-```sh
-make build       # Full pipeline: lint, test, wasm, bundle
-make test-node   # E2E smoke tests (Node.js)
-make test-deno   # E2E smoke tests (Deno)
-make lint        # Rust + TypeScript linting
-```
-
-See the [Makefile](../../Makefile) for all targets.
-
----
-
-## Platforms
-
-| Runtime | Minimum version |
-|---------|----------------|
-| Node.js | 20.0.0 |
-| Deno | 2.0.0 |
-
-Published to:
-
-- [npm](https://www.npmjs.com/package/@dikolab/kbdb)
-  as `@dikolab/kbdb`
-- [JSR](https://jsr.io/@dikolab/kbdb) as
-  `@dikolab/kbdb`
-
----
-
-## Documentation
-
-- [CLI Reference](../details/cli.md)
-- [MCP Server Guide](../details/mcp-server.md)
-- [Search and Ranking](../details/search-and-ranking.md)
-- [Storage Architecture](../details/storage.md)
-- [Library API](../details/library-api.md)

package/docs/release-notes/0.1.1.md

@@ -1,46 +0,0 @@
-# 0.1.1
-
-*Patch release -- 2026-06-20*
-
-Fixes a Deno type-checking error that blocked
-`deno publish`, and improves the build pipeline.
-
----
-
-## Fixes
-
-- **Deno type error in WASM memory buffer** --
-  `WebAssembly.Memory.buffer` returns
-  `ArrayBuffer | SharedArrayBuffer` under Deno's
-  type system but `ArrayBuffer` under Node.js.
-  Added explicit cast to satisfy both type-checkers.
-
-## Improvements
-
-- **WASM directory resolution** -- `resolveBaseDir`
-  now supports three fallback strategies for
-  locating WASM files:
-  1. `__dirname` (Node.js CJS)
-  2. `import.meta.dirname` (Deno local, Node.js
-     ESM v21.2+)
-  3. URL-based derivation (JSR remote modules)
-
-- **Build pipeline cleanup** -- `build-wasm.sh`
-  and `build-ts.sh` now remove stale output
-  directories (`src/wasm/`, `dist/`) before
-  building, ensuring fresh builds every time.
-
-- **Rust test stability** -- Added
-  `--test-threads=1` to Rust integration tests
-  to prevent race conditions on shared WASM
-  return-slot globals.
-
----
-
-## Upgrade
-
-```sh
-npm install -g @dikolab/kbdb@0.1.1
-```
-
-No breaking changes from 0.1.0.

package/docs/release-notes/0.1.2.md

@@ -1,38 +0,0 @@
-# 0.1.2
-
-*Patch release -- 2026-06-20*
-
-Fixes WASM loading failure when installed from JSR
-(`deno install -Agf jsr:@dikolab/kbdb/cli`).
-
----
-
-## Fixes
-
-- **WASM loading from JSR remote URLs** -- When
-  installed from JSR, module URLs use `https://`
-  instead of filesystem paths. `path.join` mangled
-  these URLs by stripping the `//` in `https://`,
-  and `readFileSync` cannot open URLs. Added
-  URL-aware path joining (`joinPath`) and async
-  WASM loading via `fetch()` for remote URLs.
-
-- **Worker script resolution for JSR** --
-  `resolveWorkerScript` now preserves URL format
-  when the script directory is a remote URL, so
-  `deno run` receives a valid URL instead of a
-  mangled path.
-
----
-
-## Upgrade
-
-```sh
-# Node.js
-npm install -g @dikolab/kbdb@0.1.2
-
-# Deno
-deno install -Agf jsr:@dikolab/kbdb/cli
-```
-
-No breaking changes from 0.1.1.

package/docs/release-notes/0.1.3.md

@@ -1,42 +0,0 @@
-# 0.1.3
-
-*Patch release -- 2026-06-20*
-
-Fixes WASM binaries missing from JSR package, which
-caused 404 errors when installed via
-`deno install -Agf jsr:@dikolab/kbdb/cli`.
-
----
-
-## Fixes
-
-- **WASM binaries excluded from JSR publish** --
-  `deno publish` respects `.gitignore`, which listed
-  `src/wasm/`. Additionally, wasm-pack generates
-  `.gitignore` files (containing `*`) inside each
-  WASM output directory. Both layers prevented WASM
-  binaries from being included in the JSR package.
-  The build script now removes wasm-pack's nested
-  `.gitignore` files, and the publish script
-  temporarily un-ignores `src/wasm/` during
-  `deno publish`.
-
-- **Excluded unnecessary wasm-pack artifacts from
-  JSR** -- Added `publish.exclude` patterns for
-  `.js`, `.d.ts`, and `package.json` files inside
-  `src/wasm/`, so only the `.wasm` binaries are
-  published to JSR.
-
----
-
-## Upgrade
-
-```sh
-# Node.js
-npm install -g @dikolab/kbdb@0.1.3
-
-# Deno
-deno install -Agf jsr:@dikolab/kbdb/cli
-```
-
-No breaking changes from 0.1.2.