@dikolab/kbdb 0.3.1 → 0.3.2

package/README.md

@@ -6,7 +6,7 @@ required.
 [GitLab](https://gitlab.com/tech-slaves/knowledge-base-db)
 | [NPM](https://www.npmjs.com/package/@dikolab/kbdb)
 | [JSR](https://jsr.io/@dikolab/kbdb)
-| [License: ISC](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/LICENSE)
+| [License: ISC](LICENSE)
 
 ---
 
@@ -23,13 +23,23 @@ 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.
+**How search works:** kbdb searches by keywords --
+it matches your query against indexed terms, expands
+synonyms, and ranks results by relevance. This is
+the default **lexical** mode: fast, works offline,
+and gives consistent results every time.
+
+When an exact query finds nothing, kbdb automatically
+loosens the match so you still get the best available
+results. Headings count for more in ranking, so
+writing clear headings helps.
+
+Want smarter matching? kbdb supports **hybrid search**
+(`--algo hybrid`) that blends keyword matching with
+AI-powered similarity. This catches results that use
+different words for the same concept. Hybrid mode
+needs an embedding provider -- without one, kbdb
+sticks to keyword search.
 
 **Knowledge stays fresh:** Re-learn a file and kbdb
 replaces the old version automatically.
@@ -87,7 +97,7 @@ 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. Add `--tags design,v2` to tag
-sections for scoping, or `--replace` to supersede
+sections for scoping, or `--replace` to update
 existing sections from the same source.
 
 **3. Search**
@@ -96,11 +106,16 @@ existing sections from the same source.
 kbdb search "how does auth work" --db ./my-kb
 ```
 
-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.
+Results are ranked by relevance with snippets
+showing where your terms matched. Use `--offset`
+to page through large result sets.
+
+To try hybrid search (keyword + AI similarity):
+
+```sh
+kbdb search "how does auth work" --algo hybrid \
+   --db ./my-kb
+```
 
 **4. Recall context**
 
@@ -121,25 +136,28 @@ referenced sections.
 
 - **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
+- **Smart updates** -- re-learning a file replaces
+  the old version instead of duplicating it
+- **Search** with three modes: keyword (default),
+  AI similarity, or hybrid (both combined)
+- **Auto-fallback** -- if your exact query finds
+  nothing, kbdb loosens the match automatically
 - **Recall** sections with progressive context --
   from a quick summary to full related content
-- **Export** the database as a portable snapshot
+- **Export and sync** -- snapshot your knowledge
+  base for backup or sharing across machines
 - **Skills** -- store reusable prompt templates
-  with placeholder arguments
+  with fill-in-the-blank arguments
 - **Agents** -- create AI agent profiles that
   combine a persona with skills
-- **Manage** documents, sections, and metadata
-- **Verify** database integrity, detect
-  contradictions, and clean up superseded data
+- **Auto-capture** -- the MCP server can
+  proactively suggest knowledge to store from
+  your conversations
+- **Verify** database integrity and clean up
+  stale 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)
+See the [CLI Reference](docs/details/cli.md)
 for the full command list and examples.
 
 ---
@@ -153,51 +171,17 @@ recall context progressively, export snapshots,
 store reusable skills, and build agent profiles --
 a second brain that persists between sessions.
 
-### Claude Code (CLI)
+### Setup
 
-Create `.mcp.json` in your project root:
+Add kbdb to your AI tool's MCP config. The setup
+is the same for Claude Code, VS Code, Cursor, and
+Claude Desktop -- just put the config in the right
+file for your tool.
 
-```json
-{
-   "mcpServers": {
-      "kbdb": {
-         "command": "npx",
-         "args": [
-            "-y",
-            "@dikolab/kbdb",
-            "mcp",
-            "--db",
-            "/path/to/.kbdb"
-         ]
-      }
-   }
-}
-```
-
-### Claude for VS Code
-
-Create `.vscode/mcp.json` in your project:
-
-```json
-{
-   "servers": {
-      "kbdb": {
-         "command": "npx",
-         "args": [
-            "-y",
-            "@dikolab/kbdb",
-            "mcp",
-            "--db",
-            "${workspaceFolder}/.kbdb"
-         ]
-      }
-   }
-}
-```
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
+**Claude Code** -- `.mcp.json` in your project root.
+**VS Code / Cursor** -- `.vscode/mcp.json` in your
+project. **Claude Desktop** --
+`claude_desktop_config.json`.
 
 ```json
 {
@@ -216,13 +200,18 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### Other AI Agents
+For VS Code / Cursor, wrap in `{"servers": ...}`
+instead of `{"mcpServers": ...}`. Use
+`"${workspaceFolder}/.kbdb"` for the db path.
 
-Any MCP-compatible agent can connect. See the
-[MCP Server Guide](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/details/mcp-server.md) for
-setup instructions, Deno variants, environment
-variable configuration, and the full list of
-available tools.
+**Deno users:** replace `npx` / `-y` /
+`@dikolab/kbdb` with `deno` / `run` / `-A` /
+`jsr:@dikolab/kbdb/cli`.
+
+See the
+[MCP Server Guide](docs/details/mcp-server.md)
+for Deno examples, environment variable config,
+multiple knowledge bases, and the full tool list.
 
 ---
 
@@ -246,13 +235,12 @@ const results = await client.search({
    offset: 0,
 });
 
-// results = { items, total, offset, limit, has_more, relaxed }
 console.log(results.items);
 client.disconnect();
 ```
 
 See the
-[Library API Reference](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/details/library-api.md)
+[Library API Reference](docs/details/library-api.md)
 for the full API.
 
 ### Development Setup
@@ -273,7 +261,7 @@ A Docker setup is included with all build tools
 HOST_UMASK=$(umask) docker compose run --rm dev bash
 ```
 
-See the [Makefile](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/Makefile) for all available
+See the [Makefile](Makefile) for all available
 build targets.
 
 ### Contributing
@@ -288,17 +276,17 @@ build targets.
 
 ## Documentation
 
-- [Detailed Guides](https://gitlab.com/tech-slaves/knowledge-base-db/-/tree/main/docs/details) -- CLI
-  reference, MCP setup, search internals, storage
-  format, library API
-- [Release Notes](https://gitlab.com/tech-slaves/knowledge-base-db/-/tree/main/docs/release-notes)
-- [Architecture Overview](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/overview.md)
+- [Detailed Guides](docs/details/) -- CLI reference,
+  MCP setup, search internals, storage format,
+  library API
+- [Release Notes](docs/release-notes/)
+- [Architecture Overview](docs/overview.md)
 
 ---
 
 ## License
 
-ISC License -- see [LICENSE](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/LICENSE) for details.
+ISC License -- see [LICENSE](LICENSE) for details.
 
 ---
 

package/docs/details/cli.md

@@ -80,8 +80,17 @@ These options apply to the `search` command.
 | `--limit <n>` | `-l` | `20` | positive integer | Maximum results returned |
 | `--offset <n>` | | `0` | non-negative integer | Zero-based result offset for pagination |
 | `--format <fmt>` | `-f` | `json` | `json`, `text`, `mcp` | Output format |
+| `--algo <algo>` | | `lexical` | `lexical`, `vector`, `hybrid` | Search algorithm |
 | `--content` | `-c` | off | boolean flag | Hydrate results with section content |
 
+### Search Algorithms
+
+| Algorithm | Description |
+|-----------|-------------|
+| `lexical` | Keyword matching with stemming and synonyms (default) |
+| `vector` | AI-powered similarity search using embeddings (requires a configured embedding provider) |
+| `hybrid` | Combines keyword and similarity results for best coverage |
+
 ### Search Modes
 
 | Mode | Description |

package/docs/details/mcp-server.md

@@ -196,7 +196,7 @@ daemon via JSON-RPC 2.0 over IPC.
 
 | Tool | Parameters | Description | Read-only | Destructive |
 |------|-----------|-------------|-----------|-------------|
-| `search` | `query` (string, required), `mode` (string), `limit` (number), `offset` (number), `content` (boolean) | Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use multiple short keyword queries for best coverage. | yes | no |
+| `search` | `query` (string, required), `mode` (string), `algo` (string: lexical, vector, hybrid), `limit` (number), `offset` (number), `content` (boolean) | Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use `algo` to select search algorithm (default: lexical). | yes | no |
 | `learn` | `content` (string, required), `type` (string), `title` (string), `description` (string), `docid` (string), `tags` (string[]), `replace` (boolean) | Import content into the knowledge base. Use for durable facts, decisions, and corrections. Use `replace` when updating existing knowledge. Attach `tags` for scoping. | no | no |
 | `unlearn` | `kbid` (string, required) | Remove a section by kb-id. Cascades deletion to index entries and ranking data. | no | yes |
 | `retrieve` | `kbid` (string), `docid` (string) | Fetch a specific section or document by identifier. At least one of `kbid` or `docid` required. | yes | no |

package/docs/details/search-and-ranking.md

@@ -1,5 +1,15 @@
 # How Search Works
 
+When you search, kbdb finds the sections that best
+match your query and ranks them by relevance. By
+default it matches keywords (like a search engine).
+You can also enable AI-powered similarity search
+or combine both with `--algo hybrid`. The rest of
+this page explains how ranking works under the hood
+-- you don't need to read it to use kbdb.
+
+---
+
 kbdb uses field-weighted BM25F ranking to score search
 results by relevance. Sections are indexed across
 three fields -- heading, body, and code -- each with a
@@ -513,3 +523,48 @@ Neither standalone module calls the other directly.
 | `sections`  | Individual matching sections with scores, snippets, and matched terms |
 | `documents` | Documents containing matches, with aggregated scores and per-section details |
 | `stats`     | Match counts and top terms without content bodies |
+
+## Search Algorithms
+
+kbdb supports three search algorithms, selected
+with `--algo` (CLI) or the `algo` parameter (MCP).
+
+### Lexical (default)
+
+Keyword matching with stemming and synonym
+expansion, scored by BM25F as described above.
+Fast, works offline, and gives consistent results.
+This is the default when no `--algo` flag is given.
+
+### Vector
+
+Embedding-based similarity search. Each section's
+content is converted into a numeric vector (an
+"embedding") by an AI model. Search finds sections
+whose vectors are closest to the query's vector
+using cosine similarity.
+
+Vector search catches matches that keyword search
+misses -- for example, searching "database
+rationale" finds a section about "we chose Postgres
+because of JSONB" even though none of the words
+overlap.
+
+Requires an embedding provider to be configured.
+Without one, vector mode falls back to lexical.
+
+### Hybrid
+
+Runs both lexical and vector searches in parallel,
+then merges the two ranked lists using Reciprocal
+Rank Fusion (RRF). This combines the precision of
+keyword matching with the associative recall of
+embeddings.
+
+RRF works by converting each result's rank position
+into a score (`1 / (k + rank)` with k=60), then
+summing scores across both lists. Results that rank
+well in both lists get the highest combined scores.
+
+Hybrid mode requires an embedding provider. Without
+one, it falls back to lexical.

package/docs/overview.md

@@ -27,6 +27,8 @@ to it as a tool.
   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
 
@@ -34,15 +36,25 @@ to it as a tool.
 
 - **Import** Markdown files with automatic keyword
   extraction and indexing
-- **Search** with ranked results, snippets, and
-  paginated output
+- **Search** three ways: keyword (default),
+  AI similarity, or hybrid (both combined) 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
-  placeholder arguments
+  fill-in-the-blank arguments
 - **Agents** -- AI profiles combining a persona
   with skills
-- **Export** the database as a portable snapshot
+- **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,
@@ -76,32 +88,31 @@ mode runs short-lived commands (`learn`, `search`,
 `recall`). MCP mode starts a long-lived server for
 AI agents over stdio.
 
-**Worker Client** -- TypeScript module that discovers
-or spawns the daemon and provides a typed async API.
+**Worker Client** -- Connects to the background
+daemon and gives your code a typed API.
 
 **Worker Daemon** -- Background process that loads
-WASM modules, caches data in memory, and serves
-JSON-RPC 2.0 requests over local IPC.
+the search engine, caches data in memory, and
+handles requests.
 
-**Rust/WASM Engine** -- Three WASM modules handle
-tokenization, indexing, ranking, and file I/O. Rust
-provides speed and memory safety; WASM runs on any
-runtime.
+**Search Engine** -- Compiled from Rust to
+WebAssembly for speed. Three modules handle
+tokenization, indexing, ranking, and file I/O.
 
-**File Database** -- Structured directory on disk.
+**File Database** -- Structured folder on disk.
 No server process. Portable, version-controllable,
 and human-readable.
 
 ### Technology Stack
 
-| Layer | Technology | Purpose |
-|-------|-----------|---------|
-| Runtime | Node.js, Deno | Runs CLI, MCP server, orchestration |
-| Language | TypeScript | CLI, MCP protocol, I/O |
-| Engine | Rust -> WebAssembly | Indexing, ranking, file operations |
+| 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 | Package delivery |
-| Storage | File database | Persistent, portable data |
+| Distribution | NPM, JSR | Install from either |
+| Storage | File database | Your data, in a folder |
 
 ## Design Principles
 
@@ -120,7 +131,9 @@ and human-readable.
 
 ## Design Documents
 
-Detailed specifications for each subsystem:
+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
@@ -128,6 +141,8 @@ Detailed specifications for each subsystem:
 - **[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)** --
@@ -138,6 +153,10 @@ Detailed specifications for each subsystem:
   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)** --
@@ -155,16 +174,19 @@ 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-internal/knowledge-base-db
+- **Repository**: https://gitlab.com/tech-slaves/knowledge-base-db

package/docs/release-notes/0.3.1.md

@@ -55,6 +55,16 @@ tool (`auto-capture-review`).
   `list`, `approve`, or `reject`. This brings the
   MCP server to 20 tools.
 
+- **Hybrid search infrastructure** -- New `--algo`
+  flag (CLI) and `algo` parameter (MCP/IPC) with
+  values `lexical`, `vector`, `hybrid`. Embedding
+  module with pluggable provider interface, vector
+  index binary format (KBVX), cosine similarity,
+  and RRF score fusion. Defaults to `lexical`.
+  Concrete embedding providers are deferred -- a
+  `NullEmbeddingProvider` is used until one is
+  configured.
+
 ---
 
 ## Testing

package/docs/release-notes/0.3.2.md

@@ -0,0 +1,64 @@
+# 0.3.2
+
+*Patch release -- 2026-06-23*
+
+Documentation alignment, hybrid search highlight,
+and readability improvements for non-technical users.
+
+---
+
+## Documentation
+
+- **Internal doc links use relative paths** --
+  README.md links to CLI reference, MCP guide,
+  library API, Makefile, release notes, overview,
+  and LICENSE now use relative paths instead of
+  absolute GitLab URLs. External links (NPM, JSR,
+  GitLab homepage) remain absolute.
+
+- **Fixed repository URL in overview.md** --
+  Corrected `tech-slaves-internal` to `tech-slaves`.
+
+- **`--algo` added to CLI reference** -- Search
+  Options table now documents the `--algo` flag with
+  values `lexical`, `vector`, `hybrid` and a new
+  Search Algorithms subsection.
+
+- **Hybrid search section in search-and-ranking.md**
+  -- New section explains lexical, vector, and hybrid
+  algorithms with plain-language descriptions of
+  how each works and when to use it.
+
+- **Beginner summary in search-and-ranking.md** --
+  Three-sentence intro at the top so non-technical
+  readers know what the page covers without reading
+  the full technical deep-dive.
+
+- **Feature lists updated** -- README and overview
+  now include auto-capture, sync/export, and
+  near-duplicate detection. Design Documents section
+  in overview now links to hybrid search,
+  auto-capture, and sync goal docs.
+
+- **Readability pass** -- Simplified jargon across
+  README and overview. "RRF score fusion" becomes
+  "blends keyword matching with AI-powered
+  similarity". Technology stack table simplified.
+  MCP setup examples consolidated from three
+  nearly-identical blocks into one with platform
+  notes.
+
+- **"Vibe coders" added to audience list** in
+  overview.md.
+
+---
+
+## Upgrade
+
+```sh
+# Node.js
+npm install -g @dikolab/kbdb@0.3.2
+
+# Deno
+deno install -Agf jsr:@dikolab/kbdb/cli
+```

package/docs/release-notes/README.md

@@ -2,6 +2,7 @@
 
 ## Releases
 
+- [0.3.2](0.3.2.md) -- Docs alignment, hybrid search highlight, readability
 - [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

package/package.json

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