knowledge-base-db

[![kbdb documentation -- a file-based knowledge base with hybrid search, as a CLI and MCP server](https://diko316.gitlab.io/knowledge-base-db/readme-banner.png)](https://diko316.gitlab.io/knowledge-base-db/)

# @dikolab/kbdb

[![npm version](https://img.shields.io/npm/v/@dikolab/kbdb)](https://www.npmjs.com/package/@dikolab/kbdb)
[![JSR version](https://jsr.io/badges/@dikolab/kbdb)](https://jsr.io/@dikolab/kbdb)
[![documentation](https://img.shields.io/badge/docs-diko316.gitlab.io-blue)](https://diko316.gitlab.io/knowledge-base-db/)
[![license: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/LICENSE)
[![Glama quality score](https://glama.ai/mcp/servers/diko316/knowledge-base-db/badges/score.svg)](https://glama.ai/mcp/servers/diko316/knowledge-base-db)
[![support via PayPal](https://img.shields.io/badge/support-PayPal-0070ba.svg)](https://paypal.me/dikolab)

A file-based knowledge base with ranked keyword and
semantic (hybrid) search -- learn your documents,
then recall the relevant knowledge. No external
server. Runs as a CLI and MCP server.

📖 **[Documentation](https://diko316.gitlab.io/knowledge-base-db/)** ·
[MCP Setup](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html) ·
[CLI Reference](https://diko316.gitlab.io/knowledge-base-db/details/cli.html)

[GitLab](https://gitlab.com/diko316/knowledge-base-db)
| [NPM](https://www.npmjs.com/package/@dikolab/kbdb)
| [JSR](https://jsr.io/@dikolab/kbdb)
| [License: AGPL-3.0](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/LICENSE)

> Runs on **Node.js 20+** or **Deno 2.6+**. No database
> server, no cloud account -- just files on disk.

---

## What is kbdb?

**kbdb** gives AI agents a persistent, searchable
second brain. Point it at your Markdown docs and it
indexes them into a file-based knowledge base --
then agents (and you) recall the most relevant
knowledge by ranked keyword and semantic search,
not exact-key lookup. It is a *living* store: agents
learn new facts, update them, and recall them across
sessions.

No external server to install, no cloud account --
just files on disk. It runs anywhere Node.js or Deno
runs, and works as an [MCP](https://modelcontextprotocol.io/)
server, so agents like Claude can plug it in as a
memory tool.

**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 when you are
learning something you already have -- by embedding
similarity, so it catches the same fact reworded, not
just the same bytes. `kbdb contradictions` reports
sections that cover the same ground so you can read
them together. Integrity checks verify checksums,
orphans and references. 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](https://nodejs.org/)
- **Deno** version 2.6 or newer --
  [Download](https://deno.com/)
  (2.6 is the floor: the storage engine loads its
  WebAssembly through source-phase imports, which
  is what lets it run offline after one
  `deno install`. Older Deno fails with a
  misleading `Module not found` naming a `.wasm`
  file that is present.)

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

### Install

**Using Node.js:**

CLI build hosted on
[NPM](https://www.npmjs.com/package/@dikolab/kbdb).

```sh
npm install -g @dikolab/kbdb
```

**Using Deno:**

CLI build hosted on
[JSR](https://jsr.io/@dikolab/kbdb).

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

See the
[CLI Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-cli.html)
for prerequisites and verification steps.

### Try It Out

**1. Create a knowledge base**

```sh
kbdb db init --db ./my-kb
```

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

**2. Feed it your docs**

```sh
kbdb learn ./docs
```

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, `--replace` to update
existing sections from the same source, or
`--level 2` to set the hierarchical depth
(1 = broadest, 6 = narrowest). When learning a
directory, level is auto-detected from folder
depth.

**3. Search**

```sh
kbdb search "how does auth work"
```

Results are ranked by relevance with snippets
showing where your terms matched. Output defaults
to `--format rec` (recfile: one `field: value` per
line) for easy grepping. Other formats: `json`
(machine-readable), `text` (numbered list), and
`mcp` (JSON-RPC 2.0 envelope). Use `--offset` to
page through large result sets.

To try hybrid search (keyword + AI similarity):

```sh
kbdb search "how does auth work" --algo hybrid
```

> **Tip: `--db` is optional for the CLI.** kbdb
> walks up from your working directory to the
> nearest `.kbdb` folder, so commands just work
> anywhere inside a project. Point at a specific
> base with `--db <dir>` (the parent of `.kbdb`),
> or set `KBDB_DB_DIR`. Only the `mcp` server
> requires an explicit `--db` -- it never searches
> the working directory.

**Search across bases:** enrich results with
read-only knowledge from other databases using
`--other-db <dir>` (repeatable), or add `--cascade`
to also pull from `.kbdb` folders in parent
directories:

```sh
kbdb search "how does auth work" \
   --other-db ~/shared-kb --cascade
```

Every result carries a `source_db` field -- the
database root it came from -- which you can paste
straight back into `--db` or `--other-db`.

> **Scripting:** Add `--format json` to get
> structured JSON output for parsing. Use
> `--non-interactive` or set
> `KBDB_NON_INTERACTIVE=1` to suppress prompts in
> CI pipelines.

**4. Recall context**

```sh
kbdb recall <kbid> --depth 1
```

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 supersedes
  the old version instead of duplicating it
- **History** -- a superseded section is retired, not
  deleted: `kbdb history` walks the chain from either
  end, and an old kb-id still resolves
- **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,
  or as deep as a `--max-tokens` budget allows
- **Measure** whether retrieval is actually any
  good -- `kbdb eval` scores Recall@k, MRR and
  nDCG@k against your own dataset, and exits
  non-zero when a change makes ranking worse
- **Neighbourhood** -- `kbdb neighbourhood` says what
  relates to a section *and how*: eight typed edges,
  seven of them recorded facts and one inferred
- **Consolidate** -- `kbdb consolidate` proposes groups
  of sections that could become one. It proposes only;
  you write the merge and apply it yourself
- **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](https://diko316.gitlab.io/knowledge-base-db/details/knowledge-base.html)
for the full walkthrough, including export and backup.

---

## Agent Tooling

Integrate kbdb with AI agents and custom tools.

**MCP quick-start (Claude CLI):**

```sh
claude mcp add kbdb -- \
   npx @dikolab/kbdb mcp --db /path/to/project
```

See the
[MCP Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html)
for Claude Code, VS Code, and Claude Desktop
config files, plus troubleshooting.

- **MCP server** with 30 tools -- search, recall,
  learn, revise, gaps, contradictions, export,
  skill/agent search, and more
- **Skills** -- store reusable prompt templates
  with fill-in-the-blank arguments
- **Agents** -- create AI agent profiles that
  combine a persona with skills
- **Capture policy** -- the server tells the agent
  what to store during the MCP handshake itself, so
  it needs no per-host configuration. Two of its six
  clauses are about what *not* to store: chat
  summaries, guesses, secrets, and anything the code
  already says. kbdb delivers the policy; it cannot
  make an agent follow it
- **Auto-capture** -- can ask the host's own model to
  pick out knowledge worth storing. It needs the MCP
  `sampling` capability, and **Claude Code does not
  advertise it**, so auto-capture is inert there.
  Every other feature in this list is unaffected --
  see [Host Support](https://diko316.gitlab.io/knowledge-base-db/details/host-support.html)
- **Daemon resilience** -- configurable request
  timeout and automatic retry with daemon respawn
- **Worker daemon** lifecycle management --
  stop and restart the background process
- **Granular Deno permissions** -- the daemon
  runs with scoped permissions instead of
  `--allow-all`
- **Path confinement** -- the daemon rejects
  path traversal (`..`)