Skip to main content
Glama

kbdb documentation -- a file-based knowledge base with hybrid search, as a CLI and MCP server

@dikolab/kbdb

npm version JSR version documentation license: AGPL-3.0 Glama quality score support via PayPal

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 · MCP Setup · CLI Reference

GitLab | NPM | JSR | License: AGPL-3.0

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 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.


Related MCP server: Librarian

Getting Started

What You Need

One of these (pick whichever you already have):

  • Node.js version 20 or newer -- Download

  • Deno version 2.6 or newer -- Download (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.

npm install -g @dikolab/kbdb

Using Deno:

CLI build hosted on JSR.

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

See the CLI Installation Guide for prerequisites and verification steps.

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

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

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

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:

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

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 for the full walkthrough, including export and backup.


Agent Tooling

Integrate kbdb with AI agents and custom tools.

MCP quick-start (Claude CLI):

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

See the MCP Installation Guide 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

  • 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 for MCP setup, skills, agents, and the library API, and Capture Policy 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:

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

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

The search engine

Storage, indexing and ranking come from @dikolab/vdb, kbdb's sibling project by the same author. Its documentation covers the retrieval side in depth:

  • vdb Overview -- storage model, partitions, BM25F, vector and hybrid search

  • vdb Examples -- 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.

License

This project is dual-licensed:

Versions <= 0.5.0 remain under the ISC license.

See LICENSING.md for details and contact information.


Available Tools

30 tools
agent-contentB
Read-onlyIdempotent

Shorthand for content with sectionType: agent. Deprecated; removal in 2.0.0.

Inputs: ids (required).

agent-learnB
Idempotent

Shorthand for learn with sectionType: agent. The content is the persona text. Deprecated; removal in 2.0.0.

Inputs: content (required), tags, type, docid, +3 more.

agent-recallA
Read-onlyIdempotent

Shorthand for recall with sectionType: agent. Deprecated; removal in 2.0.0.

Inputs: kbid, depth, kbids, format, +1 more.

agent-unlearnB
DestructiveIdempotent

Shorthand for unlearn with sectionType: agent. Deprecated; removal in 2.0.0.

Inputs: kbid (required), docid.

auto-capture-reviewA

Propose knowledge for storage and let the user confirm it, when the host supports elicitation.

Inputs: title, action, content.

checkA
Read-onlyIdempotent

Verify the integrity of the knowledge base. Reports checksum mismatches, orphan sections, broken references, and circular reference chains.

Inputs: no named parameters.

consolidateA
Read-onlyIdempotent

Propose groups of stored sections that could become one, so a knowledge base of twenty overlapping notes can become a few good ones. Proposes ONLY -- nothing is merged. Each group reports its weakest link. Without an entailment judge kbdb CANNOT tell whether a group disagrees with itself; read every section before merging it.

Inputs: about, limit.

contentB
Read-onlyIdempotent

Compose a rendered Markdown document from one or more kbid or docid identifiers.

Inputs: ids (required), sectionType.

contradictionsA
Read-onlyIdempotent

Report pairs of stored sections covering the same ground, to read together before trusting either. Similarity finds pairs; it cannot judge agreement. Without an entailment model every pair reads "related", and no "contradicts" means nothing was asked, not that nothing conflicts.

Inputs: limit.

exportA
Idempotent

Export the knowledge base as a self-contained directory snapshot (sections, documents, catalog -- no indexes).

Inputs: path.

gapsA
Read-onlyIdempotent

Report what this knowledge base is repeatedly asked and answers badly, worst first. Call it to decide what to learn next. Ranking is triage, not measurement: the log records how each search went, never whether the answer helped.

Inputs: limit, since.

gcA
Destructive

Remove unreferenced sections from the knowledge base. A section is eligible when no document manifest references it.

Inputs: no named parameters.

historyA
Read-onlyIdempotent

List every revision of a section, oldest first, and name the current one. Call it when a kb-id you hold no longer appears in search: revisions are retired, not deleted, so a stale kb-id still leads to the text that replaced it. A section revised once has two revisions; one never revised has one.

Inputs: kbid (required).

learnA
Idempotent

Store durable knowledge in the agent's second brain. Store decisions, corrections, and facts that cost real effort to find. Do not store what the code or docs already say, chat summaries, guesses, or secrets. When a stored fact is wrong, fix it with revise, not a second copy. Structured content (Markdown, HTML, TOML) splits into sections sharing a docid, each carrying a level and a parent. Attach tags for scoping. replace matches on title within its document and heading path; a title with neither matches on title alone, so name things distinctly.

Inputs: content (required), tags, type, docid, +4 more.

mark_resultA
Idempotent

Record whether a recalled section answered a query. Accumulates real usage into an eval dataset. Call it once you know whether a result helped, including when it did not -- a wrong answer is the more useful judgement.

Inputs: kbid (required), query (required), useful (required).

neighbourhoodA
Read-onlyIdempotent

List what relates to a section and HOW, so you can decide what to read next. Eight relations: supersedes, superseded-by, parent, child, sibling, references, referenced-by, similar. Seven are recorded facts; only "similar" is inferred from a cosine. Related is not relevant -- judge these against your task.

Inputs: kbid (required), limit.

rebuildA

Reconstruct all index files from section files and document manifests on disk. Use this to recover from index corruption.

Inputs: no named parameters.

recallA
Read-onlyIdempotent

Expand remembered context after search. Retrieves full content and context for sections by identifier, returning section text, level, parent, metadata, references, and back-references. Call it on the kbids search returned. Use maxTokens to bound the payload, and format: compact when you only need the content.

Inputs: kbid, depth, kbids, format, +2 more.

retrieveA
Read-onlyIdempotent

Low-level fetch of a section or document by identifier. For AI agent workflows, prefer recall which includes metadata, context, and back-references.

Inputs: kbid, docid.

reviseA
Destructive

When a stored fact is wrong, fix it with revise, not a second copy. Content addressing means the correction gets a NEW kb-id. The old one is retired, not deleted: it stops appearing in search, still reads by kb-id, and "history" walks between them. Fields you omit keep their existing values.

Inputs: kbid (required), content (required), tags, docid, +3 more.

save_evalsA
Idempotent

Validate and persist retrieval eval cases drafted via the eval-generate prompt. Rejects cases whose kbids do not resolve, and drops duplicates. Call it only with kbids a search actually returned; invented ids fail the whole batch.

Inputs: cases (required).

skill-contentC
Read-onlyIdempotent

Shorthand for content with sectionType: skill. Deprecated; removal in 2.0.0.

Inputs: ids (required).

skill-learnA
Idempotent

Shorthand for learn with sectionType: skill. Skills are prompt templates; use {{argName}} placeholders for arguments. Deprecated; removal in 2.0.0.

Inputs: content (required), tags, type, docid, +3 more.

skill-recallA
Read-onlyIdempotent

Shorthand for recall with sectionType: skill. Deprecated; removal in 2.0.0.

Inputs: kbid, depth, kbids, format, +1 more.

skill-unlearnA
DestructiveIdempotent

Shorthand for unlearn with sectionType: skill. Deprecated; removal in 2.0.0.

Inputs: kbid (required), docid.

statusA
Read-onlyIdempotent

Get knowledge base status including document count, section count, index size, and cache statistics.

Inputs: no named parameters.

unlearnA
DestructiveIdempotent

Remove a section from the knowledge base by its kb-id, or an entire document (and its member sections) by docid.

Inputs: kbid (required), docid, sectionType.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 30 tools

    Disambiguation2/5

    Several tools occupy very similar ground: retrieve, recall, and content all fetch material by identifier with different levels of context, and the 10 deprecated skill-*/agent-* tools duplicate the core learn/search/unlearn/recall/content operations. The descriptions help somewhat, but an agent faces many near-overlapping choices for simple read and write actions.

    Naming Consistency2/5

    Naming is a mix of single-word verbs and nouns (learn, search, status, neighbourhood, gaps), bare abbreviations (gc, rebuild), verb_noun names with underscores (save_evals, mark_result), and a hyphenated compound (auto-capture-review). The deprecated skill-* and agent-* names introduce a third resource-prefix convention, so no coherent naming pattern holds across the set.

    Tool Count2/5

    Thirty tools is too many for this server, especially because ten are deprecated shorthands that should not be used. The 20 core operations are already extensive, so the deprecated duplicates add real selection burden and make the surface feel bloated.

    Completeness4/5

    The knowledge-base lifecycle is well covered: create/learn, read/search/recall/retrieve/content, update/revise, delete/unlearn, plus maintenance (check, gc, rebuild, status) and evaluation (mark_result, save_evals, contradictions, gaps). A notable gap is the lack of an import/restore tool to complement the export snapshot, but agents can work around it.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI agents with persistent knowledge storage, enabling them to store, search, and retrieve text, documents, and files using semantic and keyword search via MCP tools.
      34
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to parse and search documents including PDF, Word, Excel, PowerPoint, and images via OCR, with support for semantic search and batch processing.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents with long-term memory and retrieval-augmented generation (RAG) capabilities, allowing them to recall past conversations, search local files, and learn user preferences.
      MIT