# kbdb [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/diko316/knowledge-base-db  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/kbdb

## Description
A searchable second brain for AI agents: ranked keyword and semantic search over your Markdown.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "kbdb": {
    "command": "npx",
    "args": ["-y","@dikolab/kbdb"]
  }
}
```

## Documentation & README

[![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 20 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 (`..`) in export/import

**What the server tells an agent.** The `initialize`
response carries an `instructions` string -- the one
channel every compliant MCP host receives without any
setup. kbdb spends it on capture policy: search before
answering, treat an `unanswered` verdict as a gap to
investigate rather than guess at, store decisions and
corrections that cost real effort to find, and do not
store what the code already says. The same sentences
are quoted in the `learn`, `revise` and `search` tool
descriptions rather than paraphrased, so there is one
source for all of them.

See the
[Agent Tooling Guide](https://diko316.gitlab.io/knowledge-base-db/details/agent-tooling.html)
for MCP setup, skills, agents, and the library API, and
[Capture Policy](https://diko316.gitlab.io/knowledge-base-db/details/design/capture-policy.html)
for the six clauses in full and why they are written
once.

---

## For Developers

### Library API

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

```typescript
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](https://diko316.gitlab.io/knowledge-base-db/details/library-api.html)
for the full API.

### Development Setup

```sh
git clone https://gitlab.com/diko316/knowledge-base-db.git
cd knowledge-base-db
npm install
npm test
```

### Docker

**Two Dockerfiles, and they are not interchangeable.**

`Dockerfile` at the repository root builds the **MCP
server** -- that is the one MCP directories build, and
the one to use if you want kbdb in a container. See
[Install MCP Server](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html#docker)
for the host configuration and why it needs a named
volume rather than a bind mount.

`Dockerfile.tooling` builds the **development
toolchain** (Node.js and Deno), which every `make`
target uses through `docker-compose.yaml`:

```sh
HOST_UMASK=$(umask) docker compose run --rm tool sh
```

Run `make benchmark` to measure search and rebuild
latency at scale -- results are written to
[docs/benchmark/benchmark.md](https://diko316.gitlab.io/knowledge-base-db/benchmark/benchmark.html)
automatically.

See the [Makefile](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/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

- [Second Brain with Claude Code](https://diko316.gitlab.io/knowledge-base-db/details/second-brain-claude-code.html)
  -- the canonical setup guide: workspace layout,
  correct commands, MCP wiring
- [CLI Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-cli.html)
  -- prerequisites, npm/JSR install, verification
- [Knowledge Base Guide](https://diko316.gitlab.io/knowledge-base-db/details/knowledge-base.html)
  -- importing, searching, recall, export
- [Agent Tooling Guide](https://diko316.gitlab.io/knowledge-base-db/details/agent-tooling.html)
  -- MCP, skills, agents, library API
- [CLI Reference](https://diko316.gitlab.io/knowledge-base-db/details/cli.html) -- full command
  list with examples
- [MCP Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html)
  -- Claude CLI, Claude Code, VS Code, Claude Desktop
- [MCP Server Guide](https://diko316.gitlab.io/knowledge-base-db/details/mcp-server.html) --
  setup, tools, environment config, and what the
  server tells an agent at `initialize`
- [Host Support](https://diko316.gitlab.io/knowledge-base-db/details/host-support.html) --
  which MCP hosts deliver the capture policy and
  advertise sampling, measured rather than assumed
- [Capture Policy](https://diko316.gitlab.io/knowledge-base-db/details/design/capture-policy.html)
  -- what kbdb tells an agent to store, and why it is
  stated once
- [Search and Ranking](https://diko316.gitlab.io/knowledge-base-db/details/search-and-ranking.html)
  -- how search works under the hood
- [Storage Architecture](https://diko316.gitlab.io/knowledge-base-db/details/storage.html) --
  file formats, directory layout, and what retained
  history costs
- [Deno Permissions](https://diko316.gitlab.io/knowledge-base-db/details/deno-permissions.html)
  -- the permission flags kbdb needs, and why
- [Benchmark Results](https://diko316.gitlab.io/knowledge-base-db/benchmark/benchmark.html)
  -- search and rebuild latency at scale
- [Learn scaling](https://diko316.gitlab.io/knowledge-base-db/benchmark/learn-scaling.html)
  -- how learn cost grows with corpus size
- [Contradiction signals](https://diko316.gitlab.io/knowledge-base-db/benchmark/contradiction-signals.html)
  -- calibrating the near-duplicate and contradiction
  thresholds over 1128 labelled pairs
- [Release Notes](https://diko316.gitlab.io/knowledge-base-db/release-notes/)
- [Architecture Overview](https://diko316.gitlab.io/knowledge-base-db/overview.html)

### The search engine

Storage, indexing and ranking come from
[`@dikolab/vdb`](https://www.npmjs.com/package/@dikolab/vdb),
kbdb's sibling project by the same author. Its
documentation covers the retrieval side in depth:

- [vdb Overview](https://diko316.gitlab.io/private-dikolab-moon-monorepo/vdb/overview.html)
  -- storage model, partitions, BM25F, vector and hybrid search
- [vdb Examples](https://diko316.gitlab.io/private-dikolab-moon-monorepo/vdb/examples.html)
  -- worked queries and ranking behaviour

---

## Support

kbdb is free, AGPL-licensed software. If it earns a
place in your workflow, you can support ongoing
development via
[PayPal](https://paypal.me/dikolab).

## License

This project is dual-licensed:

- **Open source** under the
  [GNU Affero General Public License v3.0](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/LICENSE)
  (`AGPL-3.0-only`)
- **Commercial license** available for closed-source
  or SaaS use

Versions `<= 0.5.0` remain under the ISC license.

See [LICENSING.md](https://github.com/diko316/knowledge-base-db/blob/HEAD/LICENSING.md) for details and
contact information.

---