@dikolab/kbdb

ランクリング付きキーワード検索と意味的（ハイブリド）検索を備えたファイベースの知識ベースです。ドキュメントを学習し、関連する知識を呼び出します。外部サーバーは不要。CLIとMCPサーバーとして動します。

📖 ドキュメンテーション · MCPセットアップ · CLIリファレンス

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

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

What is kbdb?

kbdb は、AIエージェントに対して永続で検索可能な第二の脳を提供します。Markdown ドキュメントを指し示すと、それらをファイベースの知識ベースにインデックス化します。その後、エージェント（そしてあなた）はランキングされたキーワード検索と意味検索によって、最も関連する知識を呼び出します。完全一致検索ではありません。これは そのものした"存"て"がつ"ものです。エージェントは新しい事実を学習し、それを更新し、セなしを超えて呼び出すことができます。

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

検索の仕組み: kbdb は既定では キーワード検索 を使用します。類語語が展開され、語が関連度でランキングされ、見出しにはスコアリンクの2倍の重みが付与えられます。完全一致クエリで何も見つからない場合、kbdb は自動的にマッチンを緩め、利用可能な最良結果を返します。

更に高い結果を求める場合は、--algo hybrid を使うとキーワード検索と類似度検索を組み合わせられます。同じ概念を表す異なる語彙を使って説明されていても、結果を見つけ出せます。既定の TF-IDF エンベディングプロバイダーは、ゼロ設定でオフライン動作します。よりリッチなエンベディングが必要なときは、worker.toml でサードパーティプロバイダー（ローカルの ONNX モデルまたはリモート API）に置き替えます。

知識は常に新しさを保てます。 kbdbセス。あるファイルを学習し直すと、古いバージョンを重複ではなく自動的に置き換えます。近似重複の検出は、学習しようとしている何かが既に存在する場合に警告します。これは埋め込み類似度で判定されるので、同じバイト列だけでなく、言い換えにられた同じ事実を検出します。kbdb contradictions は、同じ領域を扱うセクションを集めて、まとめて読けるようにします。整合性チェックは、checksンサム・孤児ファイ・参照を確認します。信頼度スコアは、エージェントが強いマッチと弱いマッチを見分けるのに役立ちます。

Related MCP server: Librarian

Getting Started

必要なものは次のどれでもか（すでにお持ちのものを選んでください）:

• Node.js バージョン 20 以上 -- ダウンロード

• Deno バージュン 2.6 以上 -- ダウンロード （2.6 が下限です。ストレージエンジンは ソースフェーズ・インポートで WebAssembly をロードするため、deno install を一度 実string 打?すでオフラインで動作します。2.6 より古い Deno は、存在する .wasm ファイルを指し示す Module not found という誤解を招エラーを出します。）

これだけです。データーベースサーバーは不要、追加ツールも不要です。

インストール

Node.js を使う場: NPM にホストされている CLを

npm install -g @dikolab/kbdb

Deno を使う場: JSR にホストされている CLI ルド

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: 各行に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>（.db の親ディレクトリ）または KBDB_DB_DIR を設定します。mcp サーバーだけは明示的な --db が必要で、作業ディレクトリを決して示し示しません。

ベースをまたいで検索する には、--other-db（繰り返し可能）を使っての他の読み取専用知識を --other-db(**)、または--cascade を追加して親ディレクトリの .kbdb フォルダからも取得します：

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

すべての結果には、取得元のデータベースルート (source_db フィールド) が含まれます。この値はそのまま --db にも --other-b にも入れ直して使用できます。

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

4. コンテキスト呼出し

kbdb recall <kbid> --depth 1

まず検索結果の kbid からです、コンテキストを段階的に広げます。深度0 ではセクション内容、深度1 では親ドキュメントと逆序参昭、深度2 では兄弟セクションと前方参昭、深度3 では参昭先セクションの全文が含まれます。

知識ベース

知識ストアを構築・検索・管理します。

• インポート -- Markdown とプレイン文書を、タグンとソース情報付きで取り込む

• スマート更新 -- ファイルを再学習すると、既存ファイルを重複させず、古いバージ→ンを置き換える

• 履歴 -- 置き換えれたセクションは削除ではなく退還されます。kbdb history は、どちら端からもチェーンを追記し、古い kb-id でも解決できます

• 検索 -- 3つのアルゴリズム。キーワード（既定)、ァイ類似度、ハイブリド（両方)

• 自動フォールバック -- 完全一致クエリで何も見つからない場合、kbdb は自動的にマッチンを緩めます

• リコール -- クイック要約から関連全体まで、あるいは --max-tokens の許容に応じて、コンテキストを徐々に広げてセクションを呼び出します

• 評価 -- 検索が実際に有効かを評価します。kbdb eval は独自データセットを使って Recall@k、MRR、nDCG@k をスコア化し、結果を悪化させるン変があったときは非ゼロの終了コードを返します。

• 近隣 -- kbdb neighbourhood は、あるセクションとの関わり方を、8種類の型付きエッジ（7つは記録された事実、1つは推論）として示します。

• 統合 -- kbdb consolidate は、1つに統合できるセクションのグループを提案します。あくまで提案だけであり、実際のマージ・コードを 自分で作し、適用しなければません。

• エクスポート -- バックアップのために知識ベースのスナップショトを取る

• 検証 -- データベースの整合性を検査し、古いクデータをクリーンアップする

• 再インデクス並び再ビルド -- 問題が生した場ためのインデクスを再構築する

完全な手順は、エクスポートとバックアップを含む Knowledge Base Guide を参照してください。

エージェント向けツール

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

MCP クイックスタート（クリプト CLI）:

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

Claude Code、VS Code、Claude Desktop の設定ファイルやトラブルシューティングなどは、[エージェントービングガイド](...? No, source: https://diko316.gitlab.io/knowledge-base-bd/details/install-mcp.html) を参照してください。

• MCPサーバー = 30種 のツール（検索、リコール、学習、更ン、ギャップ、矛ラ、エクスポート、スキル/エージェント検索など)を備える スキル -- 埋め込み引数を持つ再利用可能なプロンプトテンプレートを保存する

• エージェント -- ペルソナリティとスキルを組み合わせた AI エージェント・プロファイルを作成する

• キャプチャポリシー -- サーバーが MCP ハンドシェイク自体でエージェントに「何を保存すべきか」を伝えるため、ホストご不用の設定は不要。その6条のうち2条は、ない物を保守しない: チャット要約、類推、秘密情報、およびコードが既に述べてる内容を保存しない。kbdb はポリシーを提供するとはできますが、エージェントに従うさせることはできません

• 自動キャプチャ -- ホスト自身の**モデルに保存する価値のある知識を選抜いてもせられます。には MCP の sampling capability が必要ですが、Claude Code はその機能を公開していませんので、そこでは自動キャプチャは動しません。このリスとの他の機能は影響を受けません。Host Support を参照してください

• デーモンの耐性 -- 設定可能なタイムアウトと、デーモン再戦を伴ます自動リトライ

• ワーカーデーモンのライフサイクル管理 -- バックグラウンドプロセスの停止と再開始* 細度のDeno権限 -- デーモンは --all-all ではなくスコープ制限の権限で実行します。

• パス制返 -- デーモンはエクスポート/インポートのパス・トラバーサル (..) を拒否します。

サーバーがエージェントに伝える内容。 initialize レスポンスにはinstructions 文列が含まれます。これは、準拠なMCPホストが設定なしで受取れる唯一のチヤンネルです。kbdb はこれキに検索キャプチャ・ポリシーを載せます: 回答する前に検索、unanswered をという判定は推測ではなく、調査するべきギャップあると考ます。実際に見つけるに手間をかかる判断や訂正は保存し、コートが既に述べていることは保存しないません。だって文は、learn、revise、search のツール説明にも要約せずにそのまま引用されているため、一元化されたソースがあります。

MCP のセットアップ、スキル、エージェント、ラリブラリ API は Agent Tooling Guide、6条目の全文と、なぜ一括的に書かれているかは Capture Polity を参照してください。

開発者向け

ライブラリ API

Node.js プロジェクトまたは Deno プロジェクトで kbdb のプロジェクト的 API を利用するには:

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 ディレクトリ自体）か p dbPath（親ディレクトリ。kbdb が中から .kbdb` を発見します）を渡します。

完全版 API は Library API Reference を参照してください。

開発環境のセットアップ

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 をコンテナーして動作させる場合、使うべきでもします。ホスト設定と、バインドマウントでなの名前付きボリュームが必要な理由は、Install MCP Server を参照してください。

Dockerfile.tooling (開発用のツールチェーン (Listen) をビルドします。すべての make タケトは docker-compose.yaml を介して使用します。

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

make benchmark を実すると大規模での検索と再ビルドの待ち時間が計測でき、結果は [ド.Command] で、自動的に書出されます。

利用可能な全ビルド*...* と Makefile を参照してください。

コントリビューション

1. リポジトリをフォークする

2. フーチヤブに branch を作成する

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のラベル付きペアで調幅する

• リリースノート

• アーキテクチャ概要

検索エンジン

ストレージ、インデキング、ランキングは、 @dikolab/vdb — kbdb と同じ著者による兄弟プロジェクト — から得られます。 そのドキュメンテーションは、検索側の詳細を深く解説します:

• vdb 概説 -- ストレージモデル、分ブリゲーション、BM25F、ベクター検索とハイブリッド検索

• vdb 実例 -- 動作クエリとランキング動做

サポート

kbdbは無料AGPLライセンスのソフトウェアです。もしあなたのワークローで必要とされたならば、 PayPal を通じて継続的な開発をサポートできます。

ライセンス

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

• オープンソース GNU Affero General Public License v3.0 (AGPL-3.0-only)

• 商用ライセンス は、クローズドソース またやSaaS 向けに提供されます。

バージョン <= 0.5.0 は、引き続き ISC ライセンスです。

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