kbdb

@dikolab/kbdb

キーワード検索とセマンティック検索を組み合わせたハイブリッド検索に対応する、ファイルベースのナレッジベースです。ドキュメントを学習させ、関連する知識を呼び出せます。外部サーバーは不要です。CLI と MCP サーバーとして動作します。

📖 ドキュメント · MCP のセットアップ · CLI リファレンス

GitLab | NPM | JSR | ライセンス：AGPL-3.0

Node.js 20+ または Deno 2.6+ で動作します。データベース サーバーもクラウドアカウントも不要です。ディスク上のファイルだけで動きます。

---

kbdb とは？

kbdb は、AI エージェントに永続的で検索可能な第二の脳を提供します。Markdown ドキュメントを指定すると、インデックスを作成してファイルベースのナレッジベースに取り込みます。その後、エージェント（およびあなた自身）は、完全一致のキー検索ではなく、ランキング付きのキーワード検索とセマンティック検索によって、最も関連性の高い知識を呼び出せます。これは 成長し続ける ストアです。エージェントは新たな事実を学習し、更新して、セッションをまたいで呼び出せます。

インストールする外部サーバーもクラウドアカウントも不要です。ディスク上のファイルだけで動きます。Node.js または Deno が動作する環境ならどこでも利用でき、MCP サーバーとしても動作するため、Claude などのエージェントがメモリツールとして接続できます。

検索の仕組み： kbdb はデフォルトでキーワード検索を使用します。同義語を展開し、関連度に応じて用語をランキングし、スコア計算では見出しに 2 倍の重みを付けます。完全一致するクエリで何も見つからない場合は、kbdb が自動的に一致条件を緩め、利用可能な最良の結果を取得します。

さらに精度の高い結果が必要ですか？ --algo hybrid を使うと、キーワードのマッチングと類似度検索を組み合わせ、異なる言葉で同じ概念が表現されている場合も結果を見つけられます。デフォルトの TF-IDF 埋め込みプロバイダーは、セットアップ不要でオフライン動作します。より高性能な埋め込みが必要な場合は、worker.toml でサードパーティーのプロバイダー（ローカルの ONNX モデルまたはリモート API）に切り替えられます。

知識を最新の状態に保ちます： ファイルを再学習させると、kbdb は古いバージョンを自動的に置き換えます。近似重複検出により、すでに持っている情報を再度学習させようとすると警告が表示されます。埋め込みの類似度を使うため、同じ内容を言い換えたものも検出でき、バイト列が同一のものだけに限りません。kbdb contradictions は、同じ内容を扱うセクションを報告するので、まとめて確認できます。整合性チェックでは、チェックサム、孤立データ、参照を検証します。信頼度スコアにより、エージェントは一致度の高い結果と低い結果を見分けられます。

---

はじめに

必要なもの

以下のいずれか（すでに利用しているものを選んでください）：

• Node.js バージョン 20 以降 — ダウンロード
• Deno バージョン 2.6 以降 — ダウンロード （2.6 が最低バージョンです。ストレージエンジンは source-phase import を使って WebAssembly を読み込むため、deno install を一度実行すればオフラインで 動作できます。古い Deno では、実際には存在する .wasm ファイルを示して Module not found と誤解を招くエラーが発生します。）

以上です。データベースサーバーも、追加のツールも必要ありません。

インストール

Node.js を使用する場合：

CLI ビルドは NPMで公開されています。

npm install -g @dikolab/kbdb

Deno を使用する場合：

CLI ビルドは JSRで公開されています。

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

前提条件と検証手順については、 CLI インストールガイド をご覧ください。

試してみる

1. ナレッジベースを作成する

kbdb db init --db ./my-kb

すべてのデータを格納する .kbdb フォルダーが作成されます。

2. ドキュメントを取り込む

kbdb learn ./docs

Markdown ファイルのフォルダーを指定します。kbdb はファイルを読み込み、セクションに分割して、検索インデックスを構築します。セクションをスコープ指定するタグを付けるには --tags design,v2 を、同じソースの既存セクションを更新するには --replace を、階層の深さを設定するには --level 2 を追加します（1 = 最も広い、6 = 最も狭い）。ディレクトリを学習させる場合、レベルはフォルダーの深さから自動検出されます。

3. 検索する

kbdb search "how does auth work"

結果は関連性順に並び、検索語句が一致した箇所を示すスニペットが表示されます。出力形式の既定値は --format rec（recfile：1 行につき field: value）で、grep で簡単に検索できます。その他の形式：json（機械可読）、text（番号付きリスト）、mcp（JSON-RPC 2.0 エンベロープ）。大きな検索結果セットをページ分割するには --offset を使います。

ハイブリッド検索（キーワード + AI 類似度）を試すには：

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

ヒント：CLI では --db は省略可能です。 kbdb は作業ディレクトリから上位にたどり、最も近い .kbdb フォルダーを探すため、プロジェクト内のどこからでもコマンドを実行できます。特定のベースを指定するには --db <dir>（.kbdb の親フォルダー）を使うか、KBDB_DB_DIR を設定します。明示的な --db が必要なのは mcp サーバーだけです。作業ディレクトリは検索しません。

複数のベースを横断して検索する： --other-db <dir>（複数回指定可能）を使うと、他のデータベースの読み取り専用ナレッジを使って結果を補完できます。または --cascade を追加すると、親ディレクトリにある .kbdb フォルダーからも取り込みます。

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

各結果には source_db フィールドが含まれます。これは結果の取得元であるデータベースのルートで、--db または --other-db にそのまま貼り付けて指定できます。

スクリプト： 解析用の構造化 JSON 出力を得るには --format json を追加します。CI パイプラインでプロンプトを抑制するには、--non-interactive を使うか、KBDB_NON_INTERACTIVE=1 を設定します。

4. コンテキストを呼び出す

kbdb recall <kbid> --depth 1

検索結果の kbid から始めて、コンテキストを段階的に展開します。深さ 0 ではセクションの内容が得られ、深さ 1 では親ドキュメントとバックリファレンスが追加され、深さ 2 では兄弟セクションとフォワードリファレンスが追加され、深さ 3 では参照先セクションの全文が含まれます。

---

ナレッジベース

ナレッジストアを構築、検索、管理できます。

• インポート Markdown ファイルとプレーンテキストファイルを、タグとソース追跡情報とともにインポートします
• スマート更新 -- ファイルを再学習すると、重複せずに古いバージョンを置き換えます
• 履歴 -- 置き換えられたセクションは削除されず、退役します。kbdb history を使うと、どちらの端からでも履歴をたどることができ、古い kb-id も引き続き解決されます
• 検索 3 つのアルゴリズムに対応しています。キーワード（デフォルト）、AI 類似度、またはハイブリッド（両方）
• 自動フォールバック -- 完全一致するクエリで何も見つからない場合、kbdb が自動的に照合条件を緩めます
• 想起 段階的なコンテキストでセクションを想起します。簡潔な要約から関連コンテンツ全体まで、または --max-tokens の予算が許す限り詳細に取得できます
• 評価 検索結果が実際にどれだけ優れているかを測定します。kbdb eval は独自のデータセットに対する Recall@k、MRR、nDCG@k をスコア化し、変更によってランキングが悪化した場合はゼロ以外の終了コードを返します
• 近傍 -- kbdb neighbourhood は、セクションとの関連性とその理由を示します。8 種類の型付きエッジのうち、7 つは記録された事実、1 つは推論です
• 統合 -- kbdb consolidate は、1 つにまとめられるセクションのグループを提案します。提案のみを行うため、マージ内容の作成と適用はご自身で行ってください
• エクスポート -- バックアップ用にナレッジベースのスナップショットを作成します
• データベースの整合性を検証し、古いデータをクリーンアップします
• 問題が発生した場合はインデックスを再構築します

エクスポートやバックアップを含む詳しい手順については、 ナレッジベースガイド をご覧ください。

---

エージェント向けツール

AI エージェントやカスタムツールに kbdb を統合します。

MCP クイックスタート（Claude CLI）：

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

Claude Code、VS Code、Claude Desktop の設定ファイルと トラブルシューティングについては、 MCP インストールガイド をご覧ください。

• MCP サーバー：検索、想起、学習、修正、ギャップ、矛盾、エクスポート、 スキル／エージェント検索など、20 個のツール
• スキル：穴埋め式の引数を使って、再利用可能なプロンプトテンプレートを 保存します
• エージェント：ペルソナとスキルを組み合わせた AI エージェントの プロファイルを作成します
• キャプチャポリシー：MCP ハンドシェイク自体でサーバーがエージェントに 保存対象を伝えるため、ホストごとの設定は不要です。6 つの条項のうち 2 つは、 保存してはいけないものについて定めています。チャットの要約、推測、秘密情報、 そしてコードにすでに書かれている内容です。kbdb はポリシーを提供しますが、 エージェントにそれを遵守させることはできません
• 自動キャプチャ：ホスト独自のモデルに、保存する価値のある知識を選び出す よう依頼できます。MCP の sampling 機能が必要ですが、Claude Code はこれを アドバタイズしないため、Claude Code では自動キャプチャは機能しません。 この一覧の他のすべての機能には影響しません。 ホストのサポート状況 をご覧ください
• デーモンの耐障害性：設定可能なリクエストタイムアウトと、デーモンを再起動 して行う自動再試行
• ワーカーデーモンのライフサイクル管理： バックグラウンドプロセスを停止して再起動します
• Deno のきめ細かな権限設定：デーモンは --allow-all ではなく、 スコープを限定した権限で実行されます
• パスの制限：エクスポート／インポート時に、デーモンがパストラバーサル （..）を拒否します

サーバーがエージェントに伝える内容。 initialize レスポンスには instructions 文字列が含まれています。これは、設定なしで 準拠するすべての MCP ホストに届く唯一のチャネルです。kbdb はここで キャプチャポリシーを伝えます。回答する前に検索すること、unanswered という判定は推測するのではなく調査すべきギャップとして扱うこと、見つけるのに 実際の労力がかかる決定や訂正を保存すること、そしてコードにすでに書かれている 内容を保存しないことです。同じ文は言い換えずに learn、revise、search ツールの説明にも引用されているため、すべての文の情報源は 1 つです。

MCP の設定、スキル、エージェント、ライブラリ API については エージェント向けツールガイド、 6 つの条項の全文と一度だけ記述されている理由については キャプチャポリシー をご覧ください。

---

開発者向け

ライブラリ API

Node.js または Deno のプロジェクトで、プログラムから kbdb を使用します。

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();

contextPath（.kbdb ディレクトリ自体）または dbPath（親ディレクトリ。kbdb はその中の .kbdb を検出します）を渡します。

API の全容については、 ライブラリ API リファレンス をご覧ください。

開発環境のセットアップ

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

Docker

Dockerfile は 2 つあります。互換性はありません。

リポジトリのルートにある Dockerfile は、MCP サーバーをビルドします。MCP ディレクトリがビルドするのはこちらであり、 kbdb をコンテナ内で使う場合もこちらを使用します。ホストの設定方法と、 バインドマウントではなく名前付きボリュームが必要な理由については、 MCP サーバーのインストール をご覧ください。

Dockerfile.tooling は、すべての make ターゲットが docker-compose.yaml を通じて使用する開発ツールチェーン （Node.js と Deno）をビルドします。

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

make benchmark を実行すると、大規模環境での検索と再構築のレイテンシを 計測できます。結果は自動的に docs/benchmark/benchmark.md に書き込まれます。

利用可能なすべてのビルドターゲットについては、 Makefile をご覧ください。

貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加え、テストを追加します
4. npm test と npm run lint を実行します
5. マージリクエストを作成します

---

ドキュメント

• Claude Code で作るセカンドブレイン -- 標準のセットアップガイド：ワークスペースのレイアウト、 正しいコマンド、MCP の接続
• CLI インストールガイド -- 前提条件、npm/JSR によるインストール、動作確認
• ナレッジベースガイド -- インポート、検索、想起、エクスポート
• エージェントツールガイド -- MCP、スキル、エージェント、ライブラリ API
• CLI リファレンス -- コマンドの全 一覧と例
• MCP インストールガイド -- Claude CLI、Claude Code、VS Code、Claude Desktop
• MCP サーバーガイド -- セットアップ、ツール、環境設定、initialize 時にサーバーが エージェントに伝える内容
• ホストのサポート -- どの MCP ホストが取得ポリシーを提供し、サンプリングを アドバタイズするかを、推測ではなく実測で確認
• 取得ポリシー -- kbdb がエージェントに何を保存するよう伝えるのか、また、それを 一度だけ伝える理由
• 検索とランキング -- 検索の内部処理
• ストレージアーキテクチャ -- ファイル形式、ディレクトリ構成、履歴を保持するコスト
• Deno の権限 -- kbdb が必要とする権限フラグと、その理由
• ベンチマーク結果 -- 大規模環境での検索および再構築のレイテンシ
• 学習コストのスケーリング -- コーパスのサイズに応じた学習コストの増加
• 矛盾のシグナル -- ラベル付きペア 1128 件を用いた、近似重複および矛盾の しきい値の調整
• リリースノート
• アーキテクチャの概要

検索エンジン

ストレージ、インデックス作成、ランキング機能は、同じ作者による kbdb の姉妹プロジェクト @dikolab/vdb が提供します。ドキュメントでは、検索機能について詳しく解説しています。

• vdb の概要 -- ストレージモデル、パーティション、BM25F、ベクトル検索、ハイブリッド検索
• vdb の例 -- クエリの例とランキングの動作

---

サポート

kbdb は無料の AGPL ライセンスソフトウェアです。ワークフローで役立つと感じた場合は、 PayPal を通じて 継続的な開発を支援できます。

ライセンス

このプロジェクトはデュアルライセンスです。

• GNU Affero General Public License v3.0 に基づくオープンソース （AGPL-3.0-only）
• クローズドソースまたは SaaS での利用向けに商用ライセンスを提供

バージョン <= 0.5.0 は ISC ライセンスのままです。

詳細と連絡先については、LICENSING.md をご覧ください。

---