@dikolab/kbdb

A file-based knowledge base database -- no external server to install.

GitLab | NPM | JSR | License: ISC

Status: Beta -- actively developed. Core features (search, recall, MCP) are stable and tested.

What is kbdb?

kbdb stores your docs in a plain folder on disk and makes them searchable. No external server to install. No cloud account. Import your Markdown files, and kbdb indexes them automatically. Search returns ranked results instantly.

It runs anywhere Node.js or Deno runs, and also works as an MCP server -- giving AI agents like Claude a searchable second brain that persists between sessions.

How search works: kbdb uses keyword search by default -- synonyms are expanded, terms are ranked by relevance, and headings carry 2× weight in scoring. When an exact query finds nothing, kbdb automatically loosens the match so you still get the best available results.

Want smarter results? Use --algo hybrid to blend keyword matching with similarity search -- finding results even when different words describe the same concept. The default TF-IDF embedding provider works offline with zero setup. Swap it for a third-party provider (local ONNX model or remote API) in worker.toml when you need richer embeddings.

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.

Getting Started

What You Need

One of these (pick whichever you already have):

• Node.js version 20 or newer -- Download
• Deno version 2 or newer -- Download

That's it. No database server. No extra tools.

Install

Using Node.js:

npm install -g @dikolab/kbdb

Using Deno:

deno install -Agf jsr:@dikolab/kbdb/cli

Try It Out

1. Create a knowledge base

kbdb db init --db ./my-kb

This creates a .kbdb folder that holds all your data.

2. Feed it your docs

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 update existing sections from the same source.

3. Search

kbdb search "how does auth work" --db ./my-kb

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):

kbdb search "how does auth work" --algo hybrid \
   --db ./my-kb

Tip: --db is optional. If you're already inside a directory with a .kbdb folder, just omit it. You can also set KBDB_DB_DIR as an environment variable.

Scripting: Use --non-interactive or set KBDB_NON_INTERACTIVE=1 to suppress prompts in scripts and CI pipelines. Commands that need a database will return an error instead of waiting for user input.

4. Recall context

kbdb recall <kbid> --depth 1 --db ./my-kb

Start with a search result's kbid and expand context progressively: depth 0 gives the section content, depth 1 adds parent documents and back-references, depth 2 adds siblings and forward references, depth 3 includes full text of referenced sections.

Knowledge Base

Build, search, and maintain your knowledge store.

• Import Markdown and plain text files with tags and source tracking
• Smart updates -- re-learning a file replaces the old version instead of duplicating it
• Search with three algorithms: keyword (default), AI similarity, or hybrid (both)
• 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 -- snapshot your knowledge base for backup
• Verify database integrity and clean up stale data
• Rebuild indexes if anything goes wrong

See the Knowledge Base Guide for the full walkthrough, including export and backup.

Agent Tooling

Integrate kbdb with AI agents and custom tools.

• MCP server with 20 tools -- search, recall, learn, export, and more
• Skills -- store reusable prompt templates with fill-in-the-blank arguments
• Agents -- create AI agent profiles that combine a persona with skills
• Auto-capture -- the MCP server can proactively suggest knowledge to store from your conversations
• Daemon resilience -- configurable request timeout and automatic retry with daemon respawn
• Worker daemon lifecycle management -- stop and restart the background process

See the Agent Tooling Guide for MCP setup, skills, agents, and the library API.

For Developers

Library API

Use kbdb programmatically in your Node.js or Deno project:

import { createWorkerClient } from '@dikolab/kbdb';

// Spawns a background worker if not already running
const client = await createWorkerClient({
   contextPath: '/path/to/.kbdb',
   requestTimeoutMs: 30_000,
});

const results = await client.search({
   query: 'authentication',
   limit: 10,
   offset: 0,
});

console.log(results.items);
client.disconnect();

Pass contextPath (the .kbdb directory itself) or dbPath (the parent directory -- kbdb discovers .kbdb inside it).

See the Library API Reference for the full API.

Development Setup

git clone https://gitlab.com/tech-slaves/knowledge-base-db.git
cd knowledge-base-db
npm install
npm test

Docker

A Docker setup is included with all build tools (Node.js, Deno, Rust, wasm-pack):

HOST_UMASK=$(umask) docker compose run --rm dev bash

Run make benchmark to measure search and rebuild latency at scale -- results are written to docs/benchmark/benchmark.md automatically.

See the Makefile for all available build targets.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes and add tests
4. Run npm test and npm run lint
5. Open a merge request

Documentation

• Knowledge Base Guide -- importing, searching, recall, export
• Agent Tooling Guide -- MCP, skills, agents, library API
• CLI Reference -- full command list with examples
• MCP Server Guide -- setup, tools, environment config
• Search and Ranking -- how search works under the hood
• Storage Architecture -- file formats and directory layout
• Benchmark Results -- search and rebuild latency at scale
• Release Notes
• Architecture Overview

License

ISC License -- see LICENSE for details.