Knowledge Base MCP Server

Knowledge Base MCP サーバー

このサーバーに Markdown のメモが入ったフォルダーを指定すると、キーワードだけでなく意味に基づいて検索できるようになります。AI クライアントからでも、シェルからでも利用できます。

メモは、手元のディスクに通常のファイルとして保存したままです。サーバーはそれらを読み込み、チャンクに分割し、任意の埋め込みモデル（ローカルの Ollama モデル、OpenAI、HuggingFace）を使って各チャンクをベクトルに変換し、そのベクトルをローカルの FAISS インデックスに保存します。ローカルの埋め込みモデルとローカルの LLM で実行すれば、メモがマシンの外に出ることはありません。ホスト型プロバイダーを指定した場合に限り、ネットワーク経由で送信されます。このインデックスは、次の 2 つの窓口から利用できます。

• MCP サーバー。任意の Model Context Protocol クライアント（Claude Desktop、Codex CLI、Cursor、Continue、Cline）から呼び出して、メモを検索したり、メモの内容に基づいて回答を得たり、（任意で）新しいメモを書き込んだりできます。
• kb コマンドラインツール。ターミナルやエージェントのシェルから同じコーパスを利用できます。また、MCP のインターフェースでは提供されない、インデックス作成、診断、評価、メモの整理のための運用コマンドも利用できます。

ドキュメントでは、ナレッジベース（または シェルフ）はメモのルートディレクトリにある 1 つのサブディレクトリ（work/、research/、personal/）を指します。個別に検索することも、まとめて検索することもできます。

デモ

実際の出力であり、モックデータではありません。このキャプチャでは、リポジトリ自身の docs/ を元に用意した小規模なナレッジベースを、デフォルトの Ollama 埋め込みモデルでインデックス化し、kb CLI を実行しています。docs/assets/record-demo.sh を使って再生成できます。

目次

セクション	参照するタイミング
インストール	サーバーまたは kb CLI をマシンにインストールするとき。
設定	埋め込みプロバイダーを選び、メモを配置するとき。
MCP サーバーの使用	AI クライアントをナレッジベースに接続するとき。
kb CLI の使用	シェルから検索、質問、書き込み、整理を行うとき。
検索品質の調整	任意の再ランキング、ゲーティング、安全性の各処理を有効にするとき。
リモートトランスポート	stdio の代わりに HTTP または SSE で MCP を提供するとき。
ベンチマーク	ローカルで検索品質を測定するとき。
トラブルシューティング	検索結果が返らない、または情報が古いように見えるとき。
セキュリティ	信頼できないコンテンツを指定する前に、信頼境界を把握するとき。
ドキュメント一覧	docs/ にある詳細なリファレンスや運用手順を探すとき。

インストール

どの方法でインストールする場合も、Node.js 22 以降と npm が必要です。

MCP サーバーとして（1 つのコマンドで）

npx -y @jeanibarz/knowledge-base-mcp-server@latest

npx が npm からパッケージを取得し、stdio サーバーを起動します。同じコマンドを MCP クライアントに指定し、設定で説明されている環境変数を設定してください。docs/clients.mdには、Claude Desktop、Codex CLI、Cursor、Continue、Cline 用のコピーして貼り付けられる設定スニペットがあります。

バージョンを指定しない指定ではなく、@latest を指定してください。 npx -y @jeanibarz/knowledge-base-mcp-server（バージョン指定なし）では、解決されたバージョンが ~/.npm/_npx/ に無期限にキャッシュされます。新しいリリースが公開されても、以降のクライアント起動ではキャッシュされたバージョンが再利用されます。@latest 形式は異なるキャッシュキーにハッシュ化され、起動のたびに再解決されるため、手動で ~/.npm/_npx/ を消去しなくても、クライアントを次に再起動したときに新しい修正が反映されます。RFC 012 §2.4を参照してください。

CLI として（kb）

グローバルにインストールすると、どのシェルでも kb コマンドを使えるようになります。対話的な利用にも、AI エージェントがシェルから実行するツールとしても便利です。

npm install -g @jeanibarz/knowledge-base-mcp-server@latest
kb list          # which knowledge bases can I see?
kb doctor        # is retrieval actually healthy?
kb search "your query"

OS は呼び出しのたびにバイナリを解決するため、npm i -g …@latest の変更はすぐに反映されます。MCP サーバーをすでに読み込んでいる AI クライアントを再起動する必要はありません。kb バイナリは、MCP サーバーと同じ環境変数を読み取ります。コマンドの全容については、kb CLI の使用を参照してください。

Smithery 経由

Smithery を使って Claude Desktop に自動的にインストールするには：

npx -y @smithery/cli install @jeanibarz/knowledge-base-mcp-server --client claude

ソースから

リポジトリを使った開発や、未リリースのコミットへの固定には、この方法を使ってください。

git clone https://github.com/jeanibarz/knowledge-base-mcp-server.git
cd knowledge-base-mcp-server
npm install
npm run build

続いて環境変数を設定し（設定を参照）、ナレッジベースのディレクトリを作成して、node build/index.js を MCP クライアントの設定に追加してください。詳しくは docs/clients.md を参照してください。

ローカル開発向け

リポジトリを積極的に開発していて、npm publish したり、git pull のたびに手動で再インストールしたりせずに、グローバルの kb と knowledge-base-mcp-server のバイナリを常にチェックアウトの最新状態に保ちたい場合に使用します。

git clone https://github.com/jeanibarz/knowledge-base-mcp-server.git
cd knowledge-base-mcp-server
npm run dev:setup

dev:setup は、冪等な処理を 3 つ実行します。

1. npm install + npm run build — リンクする前にバイナリを用意するための初回ビルドです。
2. npm link — kb と knowledge-base-mcp-server をグローバルの node プレフィックスにシンボリックリンクします（セットアップ中にパスが表示されるため、リンク先を確認できます）。以降は、npm run build を実行するたびに build/ がその場で上書きされ、次回の実行時からグローバルのバイナリで新しいコードが使われます。再リンクは不要です。
3. git config core.hooksPath .githooks — git の参照先を、追跡対象の .githooks/ ディレクトリに設定します。これにより、git pull（マージまたはリベース）と git merge のたびに post-merge フックと post-rewrite フックが実行されます。各フックは、package.json が変更されていれば npm install を再実行し、ソースに変更があれば npm run build を実行します。関連する変更がなければ、何も表示しません。フックの順序では最後に実行されるため、インストールやビルドに失敗しても、リポジトリは元の状態のままです。

日々の作業では、git pull（フックがビルドします）か、編集後に npm run build を実行するだけです。グローバルの kb には、次回の実行時から変更が反映されます。

なぜ npm install -g . ではなく npm link なのですか？ npm link はシンボリックリンクなので、再ビルドするだけで変更が反映されます。npm install -g . はビルド時点のスナップショットをコピーするため、変更のたびに再インストールが必要です。

フックの適用範囲。 フックは git pull ／ git merge ／ git pull --rebase の実行時に動作しますが、ブランチ間で git checkout したときには動作しません。ブランチを切り替えた後は、npm run build を手動で実行してください。再ビルドに失敗した場合、フックは警告を表示して終了コード 0 で終了するため、pull 自体は失敗として報告されません。

3 つの開発用ヘルパーは、実際のナレッジベースやインデックスではなく、使い捨ての状態を使って実行されます。

コマンド	処理内容
npm run dev:doctor	チェックアウトをビルドし、使い捨てのスクラッチコーパスを作成して、CLI、ネイティブ FAISS 依存関係、kb list、語彙検索を検証します。また、設定済みの埋め込みプロバイダーに接続できる場合は、密ベクトル検索も検証します。新規コントリビューターのシェル環境のスモークテストに使用してください。
npm run dev:cli -- search "…" --kb=work	ソースマップを使って TypeScript の CLI エントリーポイントを直接実行するため、再ビルドや再リンクをしなくても実際のスタックトレースを確認できます。まず、アクティブな KNOWLEDGE_BASES_ROOT_DIR、FAISS_INDEX_PATH、埋め込みプロバイダー、モデルを標準エラー出力に表示するため、このコマンドがどの KB とインデックスを操作するかを確認できます。
npm run dev:remote -- --transport=http|sse	スクラッチ KB をシードし、空いているループバックポートを選び、MCP_AUTH_TOKEN を生成して、curl の使用例を表示します。その後、このスクラッチ状態を使って TypeScript サーバーを起動し、終了時に削除します。生成されたファイルを確認するには --keep を追加し、サーバーを起動せずに環境変数と使用例を出力するには --print-env を追加してください。

公開済みの npm リリースに戻す場合（動作を比較する場合など）：

npm unlink -g @jeanibarz/knowledge-base-mcp-server
npm install -g @jeanibarz/knowledge-base-mcp-server@latest

設定

まず重要なのは、ノートの保存場所と、ノートをベクトルに変換する埋め込みモデルの2つです。それ以外はすべて、動作するデフォルト値が設定されています。

KNOWLEDGE_BASES_ROOT_DIR=$HOME/knowledge_bases   # one subdirectory per knowledge base
EMBEDDING_PROVIDER=ollama                        # ollama | openai | huggingface

これらは、シェルのプロファイル（.bashrc、.zshrc）または MCP クライアントの設定に直接設定してください。認識されるすべての変数、そのデフォルト値、許容値、検証上の制約は docs/reference/configuration.md に記載されています。検索フラグとロールアウト状況に関する運用者向け情報は docs/feature-flags.md をご覧ください。ローカル開発では .env.example を .env にコピーしてください。

起動前に kb config validate を実行して、設定を確認してください。個々の値の不正だけでなく、変数間の不整合も検出します。たとえば、KB_CHUNK_OVERLAP は KB_CHUNK_SIZE より厳密に小さくする必要があります。kb doctor も同じ問題を報告し、2つの値の組み合わせが無効な場合はゼロ以外の終了コードを返します。

埋め込みプロバイダーを選ぶ

本番環境での使用に対応しているプロバイダーは3つです。4つ目の EMBEDDING_PROVIDER=fake は、テストやオフラインのフィクスチャ向けに決定論的なベクトルを返します。実際の検索品質には適していません。

Ollama（推奨 — ローカルで無料）

埋め込みモデルを自分のマシン上で実行するため、ノートの内容が外部に送信されることはありません。

EMBEDDING_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434                   # default
OLLAMA_MODEL=dengcao/Qwen3-Embedding-0.6B:Q8_0           # default
KNOWLEDGE_BASES_ROOT_DIR=$HOME/knowledge_bases

まず Ollama をインストールし、モデルをプルしてください：ollama pull dengcao/Qwen3-Embedding-0.6B:Q8_0。

モデルを選ぶ前に、コンテキストウィンドウを確認してください。 デフォルトのチャンク分割処理では約1000文字のチャンクが出力されます。通常は256トークンを超えるため、all-minilm のような256トークンのモデルは、すべてのリクエストを拒否します。少なくとも約500トークンを受け入れるモデルを使用してください：nomic-embed-text（8192）、dengcao/Qwen3-Embedding-0.6B:Q8_0（32K）、または512以上のモデル。

OpenAI

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL_NAME=text-embedding-3-small
KNOWLEDGE_BASES_ROOT_DIR=$HOME/knowledge_bases

公式 API の代わりに OpenAI-互換エンドポイント（セルフホスト型ゲートウェイ、Volcengine Ark、OpenRouter など）を利用するには、そのエンドポイントのベース URL を API バージョンのパスも含めて OPENAI_BASE_URL に設定してください（OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3）。設定しない場合は、デフォルトの https://api.openai.com/v1 が使用されます。Azure OpenAI を利用できるのは、/openai/v1/ API 互換サーフェス経由のみです（OPENAI_BASE_URL=https://<resource>.openai.azure.com/openai/v1）。従来の Azure デプロイでは、api-key 認証、api-version クエリパラメーター、デプロイごとのパスが必要なため、通常のベース URL では接続できません。

デフォルトモデルが変更されました。 OpenAI のデフォルトは text-embedding-ada-002 から text-embedding-3-small に変更されました。どちらも1536次元のベクトルを生成しますが、モデル名が変わるため、次のクエリ時に FAISS が一度再構築されます。以前のデフォルトを維持するには、OPENAI_MODEL_NAME=text-embedding-ada-002 を設定してください。

HuggingFace（フォールバック。何も設定していない場合のデフォルト）

EMBEDDING_PROVIDER=huggingface          # optional — this is the default
HUGGINGFACE_API_KEY=your_api_key_here
HUGGINGFACE_MODEL_NAME=BAAI/bge-small-en-v1.5
HUGGINGFACE_PROVIDER=hf-inference       # optional router provider for serverless inference
KNOWLEDGE_BASES_ROOT_DIR=$HOME/knowledge_bases

開始するには、HuggingFace の無料 API キーがあれば十分です。

HuggingFace は、従来の api-inference.huggingface.co/models/... エンドポイントを 2025 年に廃止しました。現在、特徴抽出の呼び出しは Inference Providers ルーターの https://router.huggingface.co/hf-inference/models/<model>/pipeline/feature-extraction を経由します。別の対応プロバイダーを選択するには、HUGGINGFACE_PROVIDER に together、replicate、fireworks-ai、sambanova、nebius、novita のいずれかを設定します。HUGGINGFACE_API_KEY には、上流でのリクエスト認証方法に応じて、Hugging Face トークンまたは互換性のあるプロバイダーキーを設定できます。セルフホスト環境または専用の Inference Endpoint を指定するには、HUGGINGFACE_ENDPOINT_URL に完全な POST URL を設定します。エンドポイント URL を明示すると、ルーターによるプロバイダー選択は行われません。

デフォルトモデルが変更されました。 HuggingFace のデフォルトは sentence-transformers/all-MiniLM-L6-v2 から BAAI/bge-small-en-v1.5 に変更されました。どちらも 384 次元のベクトルを生成しますが、名前が変わったため、次回のクエリ時に FAISS が一度再構築されます。以前のデフォルトを維持するには、HUGGINGFACE_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2 を設定してください。

すべてのモデルでサポートされるデフォルト、ベクトルの次元数、タスクプレフィックスの要件、再インデックスに関する注意事項は、docs/reference/embedding-models.md に記載されています。

ナレッジベースを構成する

KNOWLEDGE_BASES_ROOT_DIR の下に、ナレッジベースごとに 1 つのサブディレクトリを作成します（例：company/、it_support/、onboarding/）。その中にメモを入れてください。サブディレクトリは自由にネストでき、サーバーは再帰的に読み込みます。

$HOME/knowledge_bases/
├── work/
│   └── runbooks/deploy.md
├── research/
│   └── papers/retrieval.md
└── .faiss/              # index storage, created for you

インデックス対象となるもの。 許可リストに含まれる拡張子（.md、.markdown、.txt、.rst、.html、.htm）を持つファイルのみが対象です。隠しファイルと隠しディレクトリ（. で始まるもの）はスキップされます。また、PDF、ワークフローのサイドカーファイル（_seen.jsonl、_index.jsonl）、ログおよびステージング用のサブツリー（logs/、tmp/、_tmp/）、OS 関連の不要ファイル（.DS_Store、Thumbs.db、desktop.ini）も対象外です。README、LICENSE、Makefile のような拡張子のないファイルは埋め込み対象になりません。

対象を広げたり絞ったりするには、次のようにします。

# Comma-separated extensions (case-insensitive; leading dot optional).
INGEST_EXTRA_EXTENSIONS=".json,.yaml"
# Comma-separated minimatch globs relative to the KB root.
INGEST_EXCLUDE_PATHS="drafts/**,scratch.md"

PDF の抽出を意図している場合に限り、".pdf" を追加してください。基本の除外設定は変更できません。さらに項目を追加することはできますが、組み込みの項目を削除することはできません。ローダーと拡張子の完全な対応表は、docs/reference/loaders.md に記載されています。

ファイルが検索可能になるまでの流れ。 サーバーは、取り込み可能な各ファイルの SHA256 ハッシュを計算し、ファイルの隣にある隠し .index/ サブディレクトリに保存します。これにより、後続の処理で前回のインデックス作成以降にファイルが変更されたかどうかを判定できます。変更された内容はチャンクに分割されます。.md ファイルには見出しを考慮する MarkdownTextSplitter を、それ以外のファイルには RecursiveCharacterTextSplitter を使用し、どちらも chunkSize: 1000, chunkOverlap: 200 に設定します。そのため、大きな .txt ファイルや .rst ファイルは、曖昧な 1 つの埋め込みではなく複数のチャンクになります。各チャンクは埋め込まれて FAISS インデックスに追加されます。インデックスはサーバーの起動時に初期化され、サーバーがファイルの変更を検知するたびに更新されます。

サーバーが適切に検索できるメモの書き方については、docs/authoring-knowledge.md をご覧ください。チャンクに適した Markdown、フロントマターの分類体系、コンテンツ境界の安全性、メモのライフサイクルについて説明しています。

インデックスの保存先

FAISS インデックスは FAISS_INDEX_PATH に保存されます。デフォルトは $KNOWLEDGE_BASES_ROOT_DIR/.faiss です。各埋め込みモデルはその下の個別のサブディレクトリに保存されるため、2 つ目のモデルを登録しても最初のモデルが上書きされることはありません。詳しくは「埋め込みモデルを比較する」をご覧ください。

複数のプロセス間でインデックスのパスを共有する場合。 複数の MCP および CLI プロセスで、信頼できる同一の FAISS_INDEX_PATH を共有できます。書き込みはモデルごとのロックによって直列化され、バージョン管理されたアトミック保存が行われます。ディレクトリはローカルの信頼できる場所に置いてください。信頼できない相手が書き込み可能なファイルシステムには置かないでください。セキュリティおよびdocs/architecture/threat-model.mdをご覧ください。

ロギングと監査

• LOG_FILE=/path/to/logs/knowledge-base.log は、構造化ログをファイルにも出力します。ログの詳細度は LOG_LEVEL=debug|info|warn|error で指定し、デフォルトは info です。JSON-RPC ストリームが出力される stdout にはログを出力しません。
• KB_MUTATION_AUDIT_LOG=/path/to/kb-mutations.jsonl は、KB のコンテンツ書き込みをすべて追記専用の台帳に記録します。各行には、実行したサーフェス（cli.kb-remember、cli.kb-capture、cli.kb-ask、mcp.add_document、mcp.delete_document）、操作、KB と相対パス、タイムスタンプ、before_sha256 / after_sha256、書き込みと更新が行われたかどうか、サーフェスごとの判断フラグが記録されます。ノートの内容は保存されません — ハッシュとメタデータのみが記録されます。監査ログへの書き込みはベストエフォートです。失敗すると stderr に警告が出力されますが、記録対象の書き込みが中止されることはありません。KB 名とパスは記録に含まれるため、監査ログは KB ディレクトリ自体と同等の機密情報として扱ってください。

MCP ツールの説明をカスタマイズする

各ツールについて AI クライアントに表示される説明は、サーバーの起動前に上書きできます。特定のコーパスにサービスを提供するデプロイ環境で、モデルに適切なツールを選ばせたい場合に便利です。未設定または空の場合は、組み込みのデフォルト値が使用されます。

RETRIEVE_KNOWLEDGE_DESCRIPTION="Search engineering runbooks, RFCs, and postmortems."
ASK_KNOWLEDGE_DESCRIPTION="Answer from engineering runbooks with citations."
LIST_KNOWLEDGE_BASES_DESCRIPTION="List available engineering knowledge bases."
LIST_MODELS_DESCRIPTION="List embedding models registered for engineering retrieval."
KB_STATS_DESCRIPTION="Report engineering KB index and transport health."

MCP サーバーを使用する

ツール

クライアントには、これらのツールが表示されます（src/KnowledgeBaseServer.ts で登録されています）。

ツール	用途
list_knowledge_bases	どの棚があるかを確認します。エージェントは、名前を推測するのではなく、後続の検索対象を絞り込めます。
retrieve_knowledge	中核となるセマンティック検索です。クエリに最も関連性の高い文章を返すため、エージェントはモデルがすでに知っていることではなく、ドキュメントを根拠に回答できます。knowledge_base が指定されている場合は単一のナレッジベースを検索し、指定されていない場合はすべてを検索します。デフォルトでは最大 10 個のチャンクを返します。threshold は、クエリとの距離がどこまでの一致を許容するかを制限します（これは距離なので、値が小さいほど近い一致です）。デフォルトの 2 はスケールの上限にあたるため、それだけで何かが除外されることはほとんどありません。検索をより厳しくするには値を下げるか、その役割を適切に果たす段階については関連性ゲートを参照してください。ハイブリッドモードでは、統合前に両方の検索経路で多めに取得するため、しきい値は適用されません。
ask_knowledge	情報を取得した後、設定済みのローカルまたは OpenAI 互換の LLM に引用付きの回答を書かせます。取得してからプロンプトを送る代わりに、1 回の呼び出しで実行できます。
list_models	登録済みの埋め込みモデルと、アクティブなモデルを一覧表示します。
kb_stats	コーパス、インデックス、モデル、キャッシュ、トランスポートの統計情報を読み取り専用で取得します。インデックスに触れずにヘルスチェックを行う際に便利です。
diff_index	2 つの永続化されたインデックスバージョン間で検索結果を比較し、再構築によって実際に何が変わったかを確認します。
add_document	保護された変更経路を通じて、テキストドキュメントを KB に書き込みます。
delete_document	保護された変更経路を通じて、KB を基準とする相対パスのドキュメントを削除します。
reindex_knowledge_base	必要に応じて名前を指定した KB を先に検証し、グローバルな再構築を強制します。

正確な入力スキーマ、型、範囲は、同梱のツールレジストリから生成されます。docs/reference/mcp-tools.mdを参照してください。

書き込みを無効にする（KB_INGEST_ENABLED）。 最後の 3 つのツール — add_document、delete_document、reindex_knowledge_base — は、KB_INGEST_ENABLED が on の場合にのみ登録されます。デフォルトは on です。これを off に設定すると、3 つすべてが削除され、ツール群が厳密な読み取り専用になります。エージェントによる誤った書き込みが大きな損害につながる、共有環境や読み取り専用のデプロイ環境で設定してください。

リソース

ソースドキュメントを検索するのではなく、直接列挙して読み取りたいクライアントは、MCP リソースを利用できます。resources/list は、KNOWLEDGE_BASES_ROOT_DIR 配下にある、取り込み可能で隔離されていないすべてのファイルについて、kb://<knowledge-base>/<encoded-relative-path> URI を返します。resources/read は、ドキュメントの生テキスト、または取り込み対象に指定された .pdf ファイルの場合は base64 エンコードされた PDF データを返します。URI、MIME タイプ、パーセントエンコーディングの詳細については、docs/mcp-resources.md を参照してください。

ロギング

サーバーは標準の MCP logging 機能を通知します。HTTP クライアントと SSE クライアントは logging/setLevel を呼び出して、セッションの通知レベルの下限を設定できます。stdio では、リクエストを何もせずに受け付けます。これは KB_LOG_FORMAT および LOG_FILE とは独立しています。詳細については、docs/mcp-logging.md を参照してください。

結果の例

retrieve_knowledge は、一致ごとに1つのブロックを含む Markdown 文字列を返します。

## Semantic Search Results

**Result 1:**

[Content of the most similar chunk]

**Source:**
```json
{
  "source": "[Path to the file containing the chunk]"
}
```

---

**Result 2:**

[Content of the second most similar chunk]

**Source:**
```json
{
  "source": "[Path to the file containing the chunk]"
}
```

> **Disclaimer:** The provided results might not all be relevant. Please cross-check the relevance of the information.

各結果には、チャンクの内容、ソースファイル、類似度スコアが含まれます。チャンクのメタデータに行番号が含まれている場合、ソースヘッダーは alpha/docs/deploy.md#L42-L78 のような安定したチャンクハンドルを、対応する kb://alpha/docs/deploy.md#L42-L78 リソース URI にリンクします。サーバーの起動前に KB_EDITOR_URI=vscode、cursor、または file を設定すると、ローカルの絶対パスを含むエディターで開くリンクも出力されます。デフォルトの none では、絶対パスはレスポンスに含まれません。

エラーコード

ツールエラーは isError: true と JSON テキストのペイロードを返すため、クライアントは部分文字列に一致させるのではなく、安定したコードに基づいて処理を分岐できます。

{
  "error": {
    "code": "PROVIDER_AUTH",
    "message": "OPENAI_API_KEY environment variable is required when using OpenAI provider"
  }
}

コード	意味	クライアントでの一般的な対応
INDEX_NOT_INITIALIZED	FAISS インデックスが利用可能になる前に検索が実行されました。	初期化後に再試行するか、更新を実行します。
PROVIDER_UNAVAILABLE	埋め込みプロバイダーが一時的に利用できません。	バックオフして再試行します。
PROVIDER_TIMEOUT	埋め込みプロバイダーがタイムアウトしました。	バックオフして再試行します。
PROVIDER_AUTH	プロバイダーの認証情報がないか、無効です。	有効な API キーを設定するようユーザーに依頼します。
KB_NOT_FOUND	指定されたナレッジベースが存在しません。	一覧にあるナレッジベースのいずれかを指定するよう促します。
PERMISSION_DENIED	サーバーが必要なローカルパスの読み取りまたは書き込みを行えません。	運用担当者または管理者に通知します。
CORRUPT_INDEX	永続化された FAISS インデックスが破損しているか、読み取れません。	インデックスを再構築するか、復旧します。
VALIDATION	呼び出し元が指定した引数の検証に失敗しました。	再試行する前にリクエストを修正します。
INTERNAL	分類されていないサーバーエラーが発生しました。	調査のため、メッセージとログを提示します。

CLI 固有のコードを含む完全な分類一覧は、docs/reference/error-codes.md に生成されます。

kb CLI を使う

kb は MCP サーバーと同じ環境変数（KNOWLEDGE_BASES_ROOT_DIR、FAISS_INDEX_PATH、EMBEDDING_PROVIDER、OLLAMA_*、OPENAI_*、HUGGINGFACE_*）を読み取るため、サーバーが動作すれば CLI も動作します。利用対象は2つあります。ターミナルを使う人と、シェルツールはあるものの MCP 接続を持たない AI エージェントです。

各コマンドの完全なリファレンスは docs/reference/cli.md に自動生成されています — 以下の一覧は概要を示すもので、網羅的なものではありません。

コマンド一覧

タスク	コマンド
内容を確認する	kb list · kb stats · kb tags · kb where "<topic>"
検索する	kb search · kb open · kb related · kb explain
LLM で回答する	kb llm · kb ask
証拠を集める	kb research plan · kb research collect
メモを作成・整理する	kb remember · kb capture · kb import-url · kb tag · kb promote · kb superseded · kb stale-check · kb quarantine · kb cite
埋め込みモデルを管理する	kb models · kb compare
品質を測定する	kb feedback · kb eval · kb eval-gate
運用・診断する	kb doctor · kb config validate · kb serve · kb reindex · kb logs · kb diagnose · kb cache · kb verify
シェル連携	kb --help · kb help <command> · kb completion bash|zsh|fish

検索

kb search はデフォルトで読み取り専用です。既存のインデックスを読み込みますが、ファイルを再スキャンしません。編集内容を先に反映させたい場合は、--refresh を渡してください。出力の末尾には、ファイルの更新日時に照らしてインデックスが最新かどうかを示すフッターが表示されます。

kb search "your query"                        # dense (semantic) search over all shelves
kb search "your query" --kb=work --k=5        # scope to one shelf, cap results
kb search "your query" --refresh              # re-scan KB files first (this writes)
kb search "your query" --timing               # per-stage elapsed milliseconds
kb search "your query" --explain-empty        # deep diagnostics when nothing comes back

検索モードの選択。 セマンティック検索（「dense」）では、クエリと同じ 意味 を持つ文章を見つけます。これは、文章で書かれた質問に適しています。一方、ファイルパス、フラグ名、エラーコードなど、埋め込みモデルにとって意味が少ない正確なトークンの検索は苦手です。戦略は --mode で選択します。

モード	ランキング方法	使用する場面
dense（デフォルト）	FAISS インデックスに対するベクトル類似度。	文章で質問するとき。
lexical	検索エンジンで使われている従来型のキーワード／用語頻度ランキング、BM25。	INDEX_NOT_INITIALIZED、src/cli.ts のような正確な文字列がわかっているとき。
hybrid	両方を実行し、RRF（Reciprocal Rank Fusion）で2つのランキングリストを統合します。RRF は生のスコアではなく各リスト内の 順位 に基づいて結果を評価するため、比較できないスケールを正規化する必要がありません。	セマンティック検索の一致を維持しつつ、正確なトークンも見つけたいとき。
auto	ヒューリスティックにより、文章には dense、コード、パス、フラグ、エラーコード、Issue 参照のような形式のクエリには hybrid を使用します。	モードを意識したくないとき。

kb search "INDEX_NOT_INITIALIZED" --mode=lexical
kb search "retrieval benchmarks" --mode=lexical --lexical-unit=source  # rank whole files, not chunks
kb search "INDEX_NOT_INITIALIZED" --mode=hybrid
kb search "src/cli-search.ts" --mode=auto

一致範囲の拡張。 チャンクはおよそ1000文字なので、良い検索結果が、より長い文章の途中部分であることもよくあります。--context-before、--context-after、--context-window を指定すると、dense 検索で一致した各結果に、同じソース内の隣接チャンクが追加されます。読む量は増えますが、追加の検索が減ります。JSON の形式とトレードオフについては、docs/search-neighbor-context.md を参照してください。

kb search "runbook rollback" --context-window=1

結果セットの調整。 以下の演算子は追加指定で、読み取り専用です。それぞれ、単純な top-k 検索では期待どおりにならない別のケースに対応します。

演算子	使用する場面
--diverse	上位の結果が1つのファイルに偏った重複に近い内容で、複数のソースをカバーする結果を見たいとき。dense 検索の候補を一定数に絞り、その中で結果を再ランキングして、より多くのソースファイルに分散させます。
--anti-query="<text>"	関連性がないとわかっている隣接トピックから結果を遠ざけたいとき。負のクエリに近い候補にペナルティを付けますが、正のクエリがすでに支持している候補の中でのみ行います。
--plus="<text>" / --minus="<text>"	クエリ自体を調整したいとき。後からフィルタリングするのではなく、クエリベクトルに正と負の要素を追加します。

kb search "agent evidence" --diverse --format=json
kb search "agent evidence" --anti-query="frontend styling"
kb search "queue debt" --plus="slow loop" --minus="UI layout" --format=json

JSON 出力には advanced_retrieval ブロックが含まれ、モード、制約、クエリの構成要素、結果ごとのスコアリング指標が説明されます。これにより、結果が なぜ その順位になったのかを確認できます。

出力形式。

フラグ	形式
--format=md（デフォルト）	人間が読みやすい Markdown ブロック。
--format=json	スコア、メタデータ、advanced_retrieval の説明を含む完全なエンベロープ。
--format=compact	結果ごとに score|kb|path:line の1行を出力します。簡潔な運用者向けリストに適しています。
--format=vimgrep	結果ごとに path:line:col:preview の1行を出力します。エディターの quickfix リストに適しています。
--batch-jsonl	標準入力から {"query":"…","kb":"…","k":N} レコードを読み込み、1行ごとに JSON エンベロープを出力します。

printf '{"query":"q1"}\n{"query":"q2"}\n' | kb search --batch-jsonl

検索結果からソースをたどる。 JSON の結果には、チャンクに KB、パス、行範囲がある場合、alpha/docs/deploy.md#L42-L78 のような安定した chunk_id が含まれます。行のメタデータがないチャンクでは、#chunk-N が使用されます。

kb open alpha/docs/deploy.md#L42-L78     # resolve a chunk id, kb:// URI, or result path to a source file
kb related alpha/docs/deploy.md#L42-L78  # find dense neighbors of an existing result chunk

kb open はパスが KB のルート内にあることを検証し、そのパスを出力します。引用された行範囲と editorUri を含めるには、--json を追加してください。kb related はハンドルを使ってインデックス内のシードチャンクを取得し、そのテキストで検索します。--include-self を渡さない限り、シード自体は除外されます。

質問：ローカル LLM による回答

kb ask は検索を決定論的なまま維持し、その上にチャットステップを追加します。まず検索し、その後、OpenAI 互換の LLM が引用付きの回答を作成します。kb search と同じ --mode の値に加えて、--rerank を受け付けます。

エンドポイントは次の順に解決されます。--endpoint、KB_LLM_ENDPOINT、--llm-profile、アクティブな kb llm プロファイル、最後に 127.0.0.1:8080 のデフォルトの local-research-agent アドレスです。(local-research-agent は、ローカルの llama-server を実行する別のプロジェクトです。kb はすでに実行中のものを再利用することも、独自に管理することもできます。詳しくは以下をご覧ください。)

kb llm use-endpoint http://127.0.0.1:8080/v1/chat/completions --profile=local-research-agent
kb llm status
kb ask "Which notes discuss reboot recovery?" --kb=operating-environment
kb ask "why does src/cli.ts throw?" --mode=hybrid --rerank
kb ask "what changed in the daemonization notes?" --timing

REPL での反復。 --interactive（-i）を指定すると、1 回限りの回答ではなく複数ターンのセッションが開始されます。最初の質問では根拠を検索し、フォローアップでは新たに検索せず、同じ根拠を再利用します。新しいスキャンを依頼するまで、この状態が続きます。各フォローアップで検索の往復が省かれるため、トピックを掘り下げるのに便利な方法です。セッション中のコマンド：

• /sources — 直前の回答の引用元を表示します。
• /kb <name> — 検索対象を KB に限定して再検索します。引数なしで /kb を実行すると、現在の対象範囲を表示します。
• /refresh — キャッシュ済みの根拠を破棄し、次の質問で再スキャンして検索します。
• /save [title] — 直前のやり取りをトランスクリプトのノートとして保存します（--kb または /kb で KB を指定する必要があります）。
• /reset — キャッシュ済みの根拠と会話履歴を消去します。
• /help、/exit（別名 /quit）。

インタラクティブモードには TTY が必要です。stdin がパイプまたはリダイレクトされている場合は、通知を stderr に出力して、1 回限りの回答にフォールバックします。

kb ask -i --kb=operating-environment
# > Which notes discuss reboot recovery?         # first question retrieves evidence
# > What do they say about the watchdog timer?   # follow-up reuses the same evidence
# > /refresh                                      # drop cached evidence; next question re-retrieves
# > /exit

回答をノートとして保存する。 --save-transcript --kb=<name> --yes を指定すると、質問、回答、引用、ソースチャンク ID、LLM エンドポイント／プロファイル／モデル、検索モデルを記録した新しい Markdown ノートをその KB に書き込みます。--timing を指定した場合は、タイミングのメタデータも記録されます。--title=<title> では、ノートのタイトルとスラッグを設定します。既存のトランスクリプトノートが上書きされることはありません。

kb ask "what changed?" --kb=work --save-transcript --title="Ask - daemon changes" --yes

LLM プロンプトからノートを除外する。 フロントマターに kb_policy: { no_llm_context: true } が含まれるノートは検索結果には引き続き表示されますが、kb ask と MCP ask_knowledge は LLM を呼び出す前にそのノートを除外し、除外した件数を context_packing.policy_filtered_chunks に報告します。コンテキストプレフィックスの取り込みと関連性ゲートによる判定でも除外されますが、通常の検索データとしてはチャンクが保持されます。

オフラインで開発する。 KB_LLM_FAKE=on を指定すると、kb ask、関連性ゲートによる判定、コンテキストプレフィックスの生成が、決定論的なプロセス内のフェイク LLM によって行われます。エンドポイントは不要です。クライアントが実際の OpenAI 互換の localhost エンドポイントを必要とする場合は、npm run dev:mockllm -- --port=18080 を実行します。ルールは KB_LLM_FAKE_RULES でカスタマイズできます。docs/testing/fake-llm.md をご覧ください。

モデルを起動した状態で管理する。 kb に他のプロセスのモデルを再利用させず、モデルプロセスを管理させる場合：

kb llm install --profile=qwen --runner=llama-server \
  --bin=/path/to/llama-server --model=/path/to/model.gguf --port=8091
kb llm start --profile=qwen
kb llm set-model --profile=qwen --model=/path/to/other-model.gguf --start
kb llm uninstall --profile=qwen

外部プロファイルは再利用専用です。kb llm stop、restart、uninstall、reap は、local-research-agent が所有するサービスを停止しません。管理対象プロファイルには kb-llm@<profile>.service という名前空間が割り当てられ、127.0.0.1 にバインドされます。また、ユーザーの状態ディレクトリにリースを書き込むため、古い管理対象モデルをいつまでも常駐させずに、再利用可能な状態にできます。

幅広い質問のための根拠を収集する

kb research は、回答、RFC、評価計画、課題を作成する前に幅広く根拠を調べる必要があるエージェントシェル向けの読み取り専用ワークフローです。LLM の呼び出し、モデルの起動、インデックスの更新、メモの書き込みは意図的に行わず、既存の検索結果を読み取って整理するだけです。

まず plan を実行して決定論的な分類棚／クエリ計画を確認し、次に collect で実行ディレクトリに収集します。

kb research plan "synthesize an end-to-end approach for autonomous research agents and evals" --format=json
kb research collect "synthesize an end-to-end approach for autonomous research agents and evals" \
  --run-dir /tmp/kb-research-autonomous-agents-evals-20260521 \
  --format=json

その後、生成された evidence_packet.md を読み、自分で情報をまとめてください。実行ディレクトリには run.json、plan.json、ledger.json、events.jsonl も含まれます。ledger.json は監査とデバッグのために情報を損失なく保持し、evidence_packet.md は人がざっと目を通せる形式になっています。JSON の仕様と安定した成果物フィールドについては docs/cli-json-contracts.md を、使用する場面、パケットの読み方、後続の kb ask と kb feedback の連携を含む詳しい手順については docs/operations/research-workflow.md を参照してください。

メモの作成と整理

これらのコマンドを使うと、エージェントシェルからナレッジベースに慎重に情報を追加できます。収集からタグ付け、レビュー、昇格までのタスク指向のワークフロー全体については、docs/authoring-knowledge.mdを、機械可読なコマンド形式については、docs/cli-json-contracts.mdを参照してください。

kb remember — メモを作成または追記します。 --suggestは安全な最初のステップです。メモのファイル名と見出しから、既存の候補を一覧表示します。標準入力は読み取らず、メモも書き込みません（小さな.index見出しキャッシュを更新する場合があります）。実際に書き込むには、--stdinと--yesの両方が必要です。新規作成ではスラッグ化した.mdファイル名を使い、上書きは拒否します。追記では、ナレッジベース内の既存パスのみ受け付けます。追記は対象ごとに直列化され、一時ファイル、fsync、アトミックな名前変更を経てコミットされます。

kb remember --suggest --kb=work --title="Quarterly plan"
printf '# Quarterly plan\n\n...' | kb remember --kb=work --title="Quarterly plan" --stdin --yes
printf '\nFollow-up note.\n' | kb remember --kb=work --append=quarterly-plan.md --stdin --yes

kb captureはコマンドを実行し、その標準出力をフェンス付きブロックとしてメモに追記します。デフォルトでは、取得した出力と表示されるコマンドラインの両方から一般的な認証情報の形式を伏せ字にします。生のテキストが本当に必要な場合に限り、--no-redactを渡してください。どちらのコマンドにも--refreshを追加すると、書き込みが成功した後に、影響を受けたナレッジベースを再インデックス化します。

kb import-url — 出典情報とともに、ウェブページまたはPDFをスナップショットとしてメモに保存します。 http(s)経由で取得し、HTMLとPDFのレスポンスをインデクサーと同じローダーで処理して、source_url、fetched_at、content_sha256、content_type、http_status、byte_countを記録したYAMLフロントマター付きのメモを1つ作成します。

kb import-url --kb=research https://example.com/article

URLは攻撃者が制御できる入力であるため、取得処理は意図的に厳しく制限されています。許可されるスキームはhttpとhttpsのみです。リダイレクトは手動でたどり、各ホップで再検証します（--max-redirectsのデフォルトは5）。レスポンスのサイズには上限（--max-bytesのデフォルトは8 MiB）があり、時間も制限されます（--timeoutのデフォルトは30000 ms）。--allow-local-networkを渡さない限り、プライベート、ループバック、リンクローカルのアドレスは拒否されます（SSRF対策）。メモのパスのデフォルトはページタイトルのスラッグです。--note=<path.md>でパスを指定し、--titleでタイトルを上書きし、--refreshでその後に再インデックス化できます。既存のメモの上書きは拒否されます。

kb tag — 1つのメモのフロントマターにあるタグを管理します。 デフォルトはドライランです。複数のタグを指定するには--addまたは--removeを繰り返し、アトミックライターとナレッジベースの.kb-policy.json変更ポリシーを通じてコミットするには--yesを渡します。メモ本文はバイト単位でそのまま保持され、書き込み前に不正なフロントマターは拒否されます。

kb tags --kb=work                       # list facet values (tags/status/type) with counts
kb tags --facet=status --format=json    # discover the vocabulary for kb search --status filters
kb tag work/runbooks/deploy.md --add=verified        # dry run
kb tag work/runbooks/deploy.md --add=verified --yes  # commit

kb tagsはメモファイルを直接読み取りますが、既存のインデックスに新しいタグ値が反映されるのは、kb search --refreshの実行後です。

kb superseded — 古くなったメモを見つけます。 読み取り専用の「積極的な忘却」レビューです。フロントマターをスキャンして、明示的な矛盾、非推奨または休止中のライフサイクル状態、古い検証日、信頼度の低い有効なメモを探します。さらに、セマンティックインデックスを使って、該当する場合には新しい近隣情報を慎重に証拠として追加します。--format=jsonはエージェントのワークフローに適しており、--include-cleanを指定すると全件を一覧表示します。

kb superseded --kb=work
kb promote alpha/docs/deploy.md   # review and update lifecycle frontmatter on one note
kb stale-check --kb=work          # find path / URL references that no longer resolve
kb quarantine list --kb=work      # inspect per-file ingest quarantine entries
kb cite alpha/docs/deploy.md      # export BibTeX or CSL-JSON from note frontmatter

埋め込みモデルを比較する

複数の埋め込みモデルを並行して保持し、IDを指定してそれぞれにクエリを実行できます。すでに信頼しているインデックスを破棄せずに、検索品質のA/Bテストを行うのに便利です。

# List registered models. The * marks the active one.
kb models list

# Add a second model — embeds your KB once under the new model.
# For paid providers, prints an estimated cost and prompts before any HTTP traffic.
kb models add ollama nomic-embed-text          # local, free
kb models add openai text-embedding-3-small    # paid; estimate first
kb models add huggingface BAAI/bge-small-en-v1.5
kb models add ollama nomic-embed-text --index-type=sq8   # FAISS scalar quantization
kb models add ollama nomic-embed-text --index-type=hnsw  # HNSW approximate search backend

# Query a specific model without changing the default.
kb search "your query" --model=openai__text-embedding-3-small

# Side-by-side comparison: unified rank/score table over both models' top-k.
kb compare "your query" ollama__nomic-embed-text-latest openai__text-embedding-3-small

# Switch the default model.
kb models set-active openai__text-embedding-3-small

# Remove a model (refuses to remove the active one).
kb models remove huggingface__BAAI-bge-small-en-v1.5

モデルIDとその保存先の決まり方は次のとおりです。

• IDの形式 — <provider>__<filesystem-safe-slug>。入力した (provider, model_name) から、決定的に計算されます。OLLAMA_MODEL=nomic-embed-text:latest は ollama__nomic-embed-text-latest になります。
• ディスク上の保存先 — 各モデルは ${FAISS_INDEX_PATH}/models/<id>/ に保存されます。
• アクティブモデル — ${FAISS_INDEX_PATH}/active.txt に記録されます。プロセスごとに上書きするには KB_ACTIVE_MODEL を使用します。
• インデックスの種類 — KB_INDEX_TYPE または kb models add --index-type=flat|sq8|hnsw で指定します。詳しくは docs/operations/index-quantization.md を参照してください。

対応するデフォルト、ベクトルの次元数、タスクプレフィックスの要件、再インデックスに関する注意事項については docs/reference/embedding-models.md を、設計については RFC 013 を参照してください。

単一モデルのレイアウトからのアップグレード。 最初にサーバーまたは kb を起動すると、自動的に移行されます。既存の単一モデルのインデックスは ${FAISS_INDEX_PATH}/models/<derived_id>/ に移動され、active.txt が書き込まれます。同時起動時は ${FAISS_INDEX_PATH}/.kb-migration.lock を使用して処理を調整します。ロールバックできるようにする場合は、以前の ${FAISS_INDEX_PATH} のバックアップを保管してください。MCP側の変更は追加のみです。retrieve_knowledge にオプションの model_name が追加され、新たに list_models が追加され、kb_stats は最新のプロセス内 updateIndex の概要を last_index_update として報告するようになりました。model_name を渡さないツールの動作はこれまでとまったく同じです。ワイヤーフォーマットは0.2.xとバイト単位で一致します。

検索品質を測定する

kb feedback — 判定を記録し、テストに変換します。 各判定は、KBごとの台帳 <kb>/.index/relevance-feedback.jsonl に追記されます。promote を実行すると、クエリに対する台帳の各行が検索評価ケースとして反映されます。これにより、人間による判定の蓄積を、消えてしまうことなく回帰テストに活用できます。

kb feedback add --kb=work --query="rollback procedure" \
  --source=runbooks/deploy.md --verdict=relevant   # also: irrelevant | stale | misleading
kb feedback add --kb=work --query="rollback procedure" \
  --source=runbooks/deploy.md --verdict=relevant \
  --relevance=3 --chunk-id=work/runbooks/deploy.md#L42-L78   # graded 0..3, pinned to one chunk
kb feedback list --kb=work
kb feedback promote --kb=work --query="rollback procedure" \
  --fixture=docs/testing/feedback-fixture.yml --yes

docs/operations/feedback-workflow.md を参照してください。

kb eval — フィクスチャに基づく検索チェックを実行します。 ケースでは query を設定し、必要に応じて kb、required_sources、forbidden_sources、expected_metadata、max_duplicate_groups、stale_policy、gate を指定できます。ケースの gate フィールドは関連性ゲーティングとは無関係です。ここでは「このケースの失敗によってビルドを失敗させるべきか」を意味します。ゲートされていないケースが失敗した場合は警告が出力され、終了コードは0です。ゲートされたケースが失敗した場合は終了コード1となるため、CIで利用できます。

gate: false
cases:
  - name: deployment runbook
    query: rollback procedure
    kb: work
    gate: true
    required_sources: [runbooks/deploy.md]
    forbidden_sources: [archive/old-deploy.md]
    expected_metadata:
      frontmatter.status: approved
    max_duplicate_groups: 1
    stale_policy: fresh

kb eval-gate — 信頼する前に、関連性ゲートを検証します。 ラベル付きクエリのフィクスチャに対してゲートをエンドツーエンドで実行し、段階ごとの適合率、再現率、誤った空結果率を報告します。統計的な下限に加え、オプションでLLMの判定も使用できます。KB_GATE_* の調整値または判定プロンプトを変更したときは、必ず実行してください。

kb eval retrieval-eval.yml
kb eval-gate docs/testing/fixtures/rfc-018-gate-eval/queries.yml

docs/operations/eval-gate-harness.md を参照してください。

運用と診断

kb doctor                          # availability snapshot: index, embedding backend, LLM
kb config validate                 # static env-var schema validation before startup
kb serve                           # loopback daemon for warm reads; --warm pre-loads indexes
kb serve status                    # daemon liveness and degraded-mode diagnostics
kb reindex --with-context          # rebuild the index with contextual prefaces
kb reindex status --format=json    # ledger of recent and in-flight reindex passes
kb logs show --request-id=<id>     # read canonical request logs by id
kb logs recent --limit=20 --format=json
kb diagnose --request-id=<id> --repro-bundle=/tmp/kb-diag
kb cache list                      # inspect local cache surfaces
kb cache prune                     # prune stale cache entries
kb verify                          # slow integrity checks for persisted indexes and sidecars

kb serve は、--daemon を渡すクライアントがウォーム読み込みに使用するループバックデーモンを実行するため、クエリのたびにモデルとインデックスの読み込み時間がかかることはありません。kb serve [--host=127.0.0.1] [--port=17799] [--idle-timeout-ms=300000] [--warm] で起動します。--warm（または KB_DAEMON_PREWARM=on）を指定すると、準備完了を報告する前にアクティブなモデル、FAISS インデックス、字句インデックスを事前に読み込みます。kb serve status [--json] は、KB_DAEMON_URL（デフォルトは http://127.0.0.1:17799）における到達可能性、PID、アイドルタイムアウト、サポートされるコマンド、事前読み込みの状態、およびデーモンから報告される場合は受付負荷（処理中、拒否数、同時実行上限、キューサイズ）を報告します。SIGINT または SIGTERM で停止し、デーモンに到達できない場合、CLI コマンドはインプロセスでの直接実行にフォールバックします。詳細は docs/operations/daemon-lifecycle.md を参照してください。

kb reindex はインデックスを再構築します。--with-context を指定すると、コンテキストプレフィックスが追加されます（KB_CONTEXTUAL_RETRIEVAL=on と KB_LLM_ENDPOINT が必要です）。kb reindex status は、永続化された実行状態とソースごとのサイドカーレジャーを読み取り、稼働状況、インデックス対象となるファイル、サイドカーのカバレッジ、保留中のファイル、解決済みおよび失敗したチャンク、失敗コードを報告します。--kb=<name> はガードおよび推定のヒントにすぎない点に注意してください。再構築は常に、単一インデックス／モデルのレイアウト全体を対象とします（RFC 017 §5）。

kb logs は、KB_LOG_FORMAT=canonical または both のときに出力される構造化リクエストログを読み取ります。kb logs show --request-id=<id> は、1 回の検索に関するすべての行を取得します。--query-sha=<hash> は繰り返し実行されるクエリを追跡します。kb logs recent --limit=<n> は最新のエントリを表示します。--format=json はレポートエンベロープを出力し、--format=csv|tsv|ndjson は後続のツールで処理できるフラットなイベント行を出力します。

kb diagnose は、リクエストの正規イベントを、Issue で共有するための非公開の秘匿化済みバンドルにまとめます。正規ログにはクエリの生テキストは保存されないため、ログイベントから推定したモデル、KB のスコープ、k、閾値のヒントを使って kb explain --repro-bundle で再現する場合は、--query、--query-file、または --stdin を渡してください。

検索品質を調整する

標準の高密度検索はデフォルトで有効で、設定は不要です。その周囲には、さらに 5 つの段階があります。そのうち 4 つは、精度または安全性の向上に伴うコストを意図的に選べるよう、デフォルトでは無効になっています。5 つ目の信頼できないコンテンツガードは有効です。デフォルト、呼び出しごとのオーバーライド、ロールアウト状況、検証コマンドを含む完全なフラグ一覧は、docs/feature-flags.md にあります。

インジェスト時のコンテキスト付与

ノートをチャンクに分割すると、約 1000 文字の断片になり、埋め込みモデルは各断片を単独で処理します。そのため、次のようなチャンクには、

「ゲートモデルですでに 24 GB のカードが最大限使われているので、CPU に固定しています。」

見つけやすくする情報が一切ありません。どのサービスを固定しているのか、どのカードなのか、どのモデルなのかが分からないのです。そのベクトルは、運用担当者が実際に入力する GPU の競合に関する質問ではなく、「固定」に関する別の文章の近くに配置されます。ノートはインデックス化されているのに、実質的には見つけられません。

コンテキストプレフィックスを使うと、クエリ時ではなくインジェスト時にこの問題を解決できます。チャンクを埋め込む前に、LLM がそのチャンクの文書内での位置を説明する短い文章（約 50～100 トークン）を作成し、そのプレフィックスをベクトル化するテキストの先頭に付加します。これにより、チャンクは文字どおりに書かれている内容だけでなく、実際に何についてのものかを埋め込みます。この手法を公開した Anthropic は、コードと文章を含むベンチマークにおいて、上位 5 件の検索失敗が 49％減少したと測定しています。

有効にする前に知っておきたいことが 2 つあります。呼び出し元に返されるテキストは変わりません。プレフィックスが影響するのはベクトルだけで、retrieve_knowledge や kb search が返す内容には影響しません。また、コストもかかります。インジェスト時にチャンクごとに LLM を 1 回呼び出します。生成されたプレフィックスはソースごとのサイドカーにキャッシュされるため、再インデックス時にコストが発生するのは、実際に変更されたチャンクだけです。

KB_CONTEXTUAL_RETRIEVAL=on     # plus a KB_LLM_ENDPOINT to generate against
kb reindex --with-context      # backfill existing shelves
kb reindex status              # sidecar coverage, pending files, failures

設計と導入の詳細については、RFC 017 を参照してください。

クロスエンコーダーによる再ランキング

高密度検索では、クエリと各チャンクのスコアを個別に計算してから 2 つのベクトルを比較します。チャンクのベクトルはインデックス作成時に一度だけ計算されるため高速ですが、モデルがクエリとチャンクを一緒に処理することはありません。クロスエンコーダーは、クエリとチャンクのペアをまとめて読み取り、一致度を直接スコア化するため、はるかに精度が高くなります。ただし、コーパス全体を対象に実行するには遅すぎます。再ランキングでは、高密度検索（またはハイブリッド検索）で候補を絞り込み、その候補だけをクロスエンコーダーで並べ替えることで、両方の利点を得られます。

KB_RERANK=on で有効にするか、呼び出しごとに kb search --rerank / kb ask --rerank を指定します。クエリごとにわずかな遅延が発生します。

Env var	Description	Default
KB_RERANK	クロスエンコーダーによる再ランキング段階を有効にします。	off
KB_RERANK_MODEL	再ランキングに使用するクロスエンコーダーモデルの ID です。	(組み込みのデフォルト)
KB_RERANK_TOP_N	再ランキングに渡す上位候補の数です。	(組み込みのデフォルト)
KB_RERANK_SKIP_DOMAINS	再ランキングをスキップする KB ドメイン名をカンマ区切りで指定します。	(なし)

KB_RERANK_DEVICE（cuda、cpu）と KB_RERANK_DTYPE（fp32、…）は、クロスエンコーダーの実行に関する任意の Transformers.js / ONNX Runtime オーバーライドです。ランタイム固有の高速化やデータ型の制御が必要な場合に設定してください。どちらも kb config show に表示され、kb config validate で検証されます。設計の詳細については、RFC 019 を参照してください。

関連性ゲート

検索では常に何らかの結果が返されます。ノートに記載のないトピックについて尋ねても、最もましなチャンクが10件返されます。検索時の類似度しきい値も役に立ちません。デフォルトでは距離スケールの上限に近い値に設定されており、何かを除外することはほとんどありません（retrieve_knowledge を参照）。LLM に渡すと、これらのチャンクは信頼できるコンテキストのように読めてしまい、回答をひそかに損ないます。関連性ゲートは、検索と利用の間にチェックを加えます。まず統計スコアの下限を適用し、必要に応じて LLM による判定も行います。タスクに実際には一致しないチャンクを除外し、誤った情報を返す代わりに何も返さないこともできます。

これは現実的なトレードオフです。ゲートは本当に関連するチャンクも破棄する場合があり、適合率を高める一方で再現率を下げることがあります。そのため、明示的に有効にしない限りオフになっています。

KB_RELEVANCE_GATE=on          # enable for a whole process
kb search "…" --gate          # enable for one call
kb search "…" --no-gate       # bypass in a process where it is enabled

判定には --task-context=<text> / --task-context-file=<path>（MCP：task_context）で指定したタスクの説明が使われ、KB_GATE_LLM_ENDPOINT / KB_GATE_LLM_MODEL が参照されます。設定されていない場合は、KB_LLM_ENDPOINT / KB_LLM_MODEL にフォールバックします。MCP の呼び出し元は gate: "off" を渡して回避できます。

環境変数	意味	デフォルト
KB_GATE_SCORE_FLOOR	チャンクがクリアする必要のある統計スコアの下限です。	0.95
KB_GATE_JUDGE_INPUT	LLM による判定に渡す、下限をクリアしたチャンクの件数です。	10
KB_GATE_LLM_TIMEOUT_MS	判定の呼び出しタイムアウトです。	8000
KB_GATE_MIN_TASK_TOKENS	判定を実行するために必要なタスクコンテキストの最小長です。	8
KB_GATE_EMPTY_VERDICT	ゲートがコンテキストをまったく返さないことを許可します。	off

呼び出し元に検索コンテキストがゼロ件返されても問題ないと確信できてから、KB_GATE_EMPTY_VERDICT を有効にしてください。調整の変更を反映する前に、kb eval-gate で検証してください。設計については RFC 018 を参照してください。

取り込み時のシークレットスキャン

ターミナルやログから取り込んだノートには、認証情報が含まれている場合があります。KB_INGEST_SECRET_SCAN=on を設定すると、埋め込み処理の前にチャンクのテキストとフロントマターをスキャンし、認証情報らしき内容を検出します。検出されたものは理由 secret_detected とともに隔離され、FAISS への書き込み前にスキップされるため、シークレットがインデックスに入ることはありません。

kb quarantine list --reason=secret_detected

認証情報の例を意図的に保存するシェルフに限り、KB_SECRET_SCAN_BYPASS_KBS=trusted-kb,... を使用してください。取り込み時のシークレットスキャン を参照してください。

信頼できないコンテンツのガード

検索した内容はすべて LLM のコンテキストに貼り付けられるため、「以前の指示を無視してください」と書かれたノートは、質問したエージェントを標的にするインジェクションベクトルになります。そのため、検索された各チャンクは信頼できないコンテンツのガードを通過します。このガードは、システムロールのマーカー、指示を上書きする表現、Unicode の双方向制御文字・ゼロ幅文字・タグ制御文字など、プロンプトインジェクションの兆候をスキャンし、検出したものに印を付けます。

ほかの3つの段階とは異なり、この機能はデフォルトで有効です（KB_INJECTION_GUARD=tag）。

値	動作
tag（デフォルト）	検出内容をチャンクのメタデータに注記します。
wrap	コンテンツをセンチネル文字列で囲み、後続のプロンプトがデータと指示を区別できるようにします。
both	上記の両方を行います。
off	スキャンしません。

完全に管理下にあるシェルフでのみ off を設定してください。または、KB_INJECTION_GUARD_BYPASS_KBS=trusted-kb,... を使って特定のシェルフを除外すれば、全体のデフォルトを弱めずに済みます。

リモートトランスポート（任意）

デフォルトでは、サーバーは stdio 経由で MCP を通信します。サポート対象のすべてのクライアント（Claude Desktop、Codex、Cursor、Continue、Cline）は、シングルユーザー向けのローカルツールに適した形で、サーバーを子プロセスとして起動します。RFC 008 では、ブラウザベースのクライアント、Smithery のリモートモード、共有デプロイメント向けに、オプトインの SSE および streamable HTTP トランスポートを追加します。MCP_TRANSPORT を設定しない限り、stdio の動作は変更されません。

export MCP_TRANSPORT=http                            # stdio (default), sse, or http
export MCP_AUTH_TOKEN="$(openssl rand -base64 32)"   # must be ≥32 characters; shorter tokens abort startup
# Or MCP_AUTH_TOKEN_FILE=/run/secrets/kb-mcp-token to read the token from a file; takes precedence over MCP_AUTH_TOKEN
export MCP_ALLOWED_ORIGINS="http://localhost:5173"   # comma-separated; unset denies all browser origins
export MCP_PORT=8765                                 # default
export MCP_BIND_ADDR=127.0.0.1                       # default — loopback only
export MCP_AUTH_BACKOFF_THRESHOLD=5                  # failed bearer attempts before backoff; 0 disables
export MCP_AUTH_BACKOFF_MS=30000                     # Retry-After window for auth backoff
node build/index.js

このモードのエンドポイント：

エンドポイント	認証	用途
GET /health	なし	稼働状態の確認用プローブです。200 {"status":"ok"} のみを返し、それ以外は返しません。匿名の呼び出し元に対して、バージョン、稼働時間、ファイルシステムのフィンガープリントは返しません（RFC 008 §6.8）。
GET /ready	bearer	オペレーターとリバースプロキシ向けの準備状態確認用プローブです。アクティブなモデルが解決され、アクティブなインデックスファイルが存在し、埋め込みバックエンドが簡単なスモーククエリに応答した場合は 200 を返します。それ以外の場合は、失敗したチェック名のみを列挙して 503 を返します。
GET /sse + POST /messages?sessionId=<uuid>	bearer	MCP_TRANSPORT=sse：長時間接続のストリームと、そのセッション用の JSON-RPC メッセージです。
POST /mcp	bearer	MCP_TRANSPORT=http：streamable HTTP です。サーバーは初期化時に Mcp-Session-Id を返します。クライアントは、以降の GET、POST、DELETE /mcp リクエストでこの ID を送信する必要があります。

/ready を含む、ヘルスチェック以外のすべてのエンドポイントには、Authorization: Bearer <token> が必要です。MCP_AUTH_TOKEN_FILE を設定すると、マウントされたシークレットファイルからトークンを読み込みます。内容の前後の空白は削除されますが、それでも 32 文字以上である必要があり、MCP_AUTH_TOKEN より優先されます。同一のリモートアドレスから bearer 認証の失敗が繰り返されると、上限付きのインメモリバックオフが適用され、Retry-After が返されます。認証に成功すると、そのアドレスの状態はクリアされます。リバースプロキシの背後では、バックオフのキーはプロキシのソケットアドレスであり、X-Forwarded-For ではありません。そのため、インターネットに公開する場合は、プロキシ側でスロットリングを設定してください。

セキュリティのデフォルト設定。 サーバーは、MCP_AUTH_TOKEN または MCP_AUTH_TOKEN_FILE がない状態で SSE または HTTP モードを起動することを拒否し、ループバックのみでバインドし、bearer トークンを一定時間で比較します。ホスト外に公開するには、MCP_BIND_ADDR=0.0.0.0 を設定し、さらにリバースプロキシで TLS を終端してください。このサーバーでは TLS は対象外です。

開発中に使い捨てのプレイグラウンドを利用するには、npm run dev:remote を使用してください（ローカル開発についてを参照）。

ベンチマーク

npm run bench:beir を実行すると、認証情報不要の語彙検索を使ったローカルの BEIR 検索ベンチマークが実行されます。これにより、チャンク分割やランキングの変更による効果を推測ではなく測定できます。

npm run bench:beir -- --dataset=scifact --split=test --mode=lexical --lexical-unit=source --output-dir=/tmp/kb-beir-scifact

ランナーは一時的な KB ルートを構築し、メトリクス JSON と TREC の実行ファイルに加えて、再現用メタデータ（git SHA、コマンド、データセットのチェックサム、ランタイムのバージョン、チャンク分割の設定、レイテンシのパーセンタイル）を出力します。これらはローカルの成果物であり、公式の BEIR リーダーボードへの投稿ではありません。語彙ソースのパスはドキュメント単位でスコアリングされ、kb search --mode=lexical --lexical-unit=source に一致します。スモークテストのコマンドと注意事項については benchmarks/README.md を、アーカイブされた SciFact の実行結果については benchmarks/results/README.md を参照してください。

nomic-embed-text を Ollama 上で使用する、コミット済みの dense / small-model の数値（BEIR、MTEB、BRIGHT）を最初から最後まで再現するには、benchmarks/REPRODUCE.md の手順に沿って実行してください。

Optuna によるチューニングは任意で、実行した場合にのみ動作します。語彙チャンク分割のパラメーターをスイープし、再実行可能な最良設定ファイルを書き出します。

npm run bench:tune -- \
  --trials=12 \
  --direction=maximize \
  --metric=metrics.ndcgAt10 \
  --study-name=scifact-lexical \
  --best-config-out=/tmp/kb-scifact-lexical-best.json \
  --param-int=KB_CHUNK_SIZE=256:1024:128 \
  --param-int=KB_CHUNK_OVERLAP=0:128:32 \
  -- npm run bench:beir -- --dataset=scifact --split=test --mode=lexical --max-queries=25 --output-dir=/tmp/kb-scifact-tune

最良の試行を再実行する場合、Optuna をインストールする必要はありません。

npm run bench:tune -- --replay-config=/tmp/kb-scifact-lexical-best.json

トラブルシューティング

コマンドを中心とした手順書 docs/troubleshooting-local-kb.md から始めてください。結果が空になる場合、インデックスが古いことを示すフッター、リンクされたチェックアウトとグローバル bin の不一致、アクティブなモデルが見つからない場合、バックエンドの稼働状況、更新ロックの競合を扱っています。進行中のインシデントについては、症状別にまとめられた docs/operations/incident-response.md を参照してください。Ollama、llama-server、n8n、systemd ユーザーユニット、リモートトランスポート、kb serve については、ローカルサービス運用手順書 を参照してください。

まず kb doctor を実行する

kb search（または MCP の retrieve_knowledge ツール）が何も返さない場合は、まず読み取り専用の kb doctor を実行してください。これは検索機能の正式な稼働状況チェックであり、kb ask のローカル LLM の準備状況も報告します。

kb doctor                    # human-readable report
kb doctor --format=json      # machine-readable, for agent shells

全レポートでは、次の 4 つの領域を扱います。

• 検索の準備状況 — アクティブなモデルの解決、FAISS インデックスのバージョンと mtime、プロセス内での最新のインデックス更新サマリー、KB ごとの古い項目数。
• バックエンドへの到達性 — 埋め込みプロバイダー（Ollama / HuggingFace / OpenAI）に加え、kb ask と関連性ゲートの LLM エンドポイント。
• LLM 使用カウンター（処理別） — 呼び出し数、エラー数、p95 レイテンシ、報告されたトークン合計、試行回数と再試行回数、キャッシュヒットの結果、回答が実際に変更された頻度。プロバイダーとモデルの帰属情報には 上限があります。名前を記録するのは使用頻度の高い少数の値だけなので、使用頻度の低いモデルが増え続けてもカウンターの種類は無制限に増えません。
• ローカルインストールの状態 — CLI バージョンとローカルの git 状態。これにより、グローバルの kb bin が古いチェックアウトを指している場合に検出できます。

必須の検索チェックに失敗した場合、終了コードは 0 以外になります — アクティブなモデルを解決できない、インデックスがない、バックエンドに到達できない場合です。LLM エンドポイントの失敗は WARN 行にとどまります。検索機能が正常でも、kb ask や任意のゲートが使えないことがあるためです。

次の 4 つの専用モードでは、ヘルスレポート全体を読み込まずに、より限定的な問題を確認できます。

コマンド	使用する場面
kb doctor --endpoints	設定済みのローカルエンドポイントに到達できるかだけを、クライアントの起動や接続前に確認したい場合。MCP のバインドアドレス／ポートの利用可能性、KB_DAEMON_URL のヘルス、Ollama の埋め込み機能への到達性、KB_LLM_ENDPOINT またはアクティブな LLM プロファイル、ゲートが有効な場合の KB_GATE_LLM_ENDPOINT を確認します。ゲートが無効、エンドポイントが未設定、またはフェイク判定機能が有効な場合、ゲートの行は省略されます。
kb doctor --locks	更新またはモデルへの書き込みでロック競合が報告される場合。モデルごとの .kb-write.lock パスをスキャンし、ロックの経過時間、新しいロックに記録された所有者の PID とコマンド、古いロックの可能性、慎重な次の対応を報告します。ロックファイルを削除することはありません。
kb doctor --kb-symlinks	KB コンテンツのルートを監査する場合。lstat を使ってスキャンし、シンボリックリンクされたディレクトリをたどらずに、ターゲットをルート内、ルート外、リンク切れ、ループ／エラーに分類し、上限付きの例を表示します。
kb doctor --bug-report=/tmp	イシューを作成する場合や、診断情報を別の運用担当者に渡す場合。タイムスタンプ付きディレクトリに、秘匿化した doctor.json、stats.json、最近の正式なログサマリー、ランタイムと環境のメタデータ、README を書き出します。ノートの内容と生の API キーは含まれませんが、KB 名、パス、モデル名、ログのメタデータは機密情報となる可能性があります。

検索失敗の読み方

kb search の失敗は6つのカテゴリーに分類されているため、スタックトレースを読まなくても、あなたやエージェントが修正すべき箇所を判断できます。各失敗には、安定した code、category、人が読める message、具体的な next_action が含まれます。

カテゴリー	代表的なコード	試すこと
configuration	PROVIDER_AUTH、KB_NOT_FOUND、ACTIVE_MODEL_UNRESOLVED	不足している API キーを設定するか、kb list ／ kb models list を実行するか、kb models set-active <id> を実行します。
indexing	INDEX_NOT_INITIALIZED、CORRUPT_INDEX	kb search --refresh でインデックスを構築または再構築します。
provider	PROVIDER_UNAVAILABLE、PROVIDER_TIMEOUT	埋め込みバックエンドにアクセスできることを確認します（ollama serve、プロバイダーのステータスページ）。
permissions	PERMISSION_DENIED	$FAISS_INDEX_PATH と各ナレッジベースの .index/ への書き込み権限を付与します。
input	VALIDATION	メッセージに記載された、拒否されたフィールドを修正します。
lock	REFRESH_LOCK_BUSY	少し待ってから再試行します。モデルごとに kb search --refresh を実行できる書き込みプロセスは1つだけです。

--format=md では、標準エラー出力に kb search: <message> に続いて category: と next: の各行が出力されます。--format=json では、標準出力に {"error":{"code","category","message","next_action",...}} として出力されるため、エージェントはカテゴリーに応じて処理を分岐できます。原因が不明な場合、next_action は kb doctor にフォールバックします。終了コードは CLI の規約に従います。再試行せずに修正できる設定と入力の問題には 2、実行時、インデックス、プロバイダー、権限、ロックの問題には 1 が返されます。

その他のヒント

• 構造化ログを記録するには、LOG_FILE を設定します。JSON-RPC の通信は引き続き標準出力を使用するため、MCP のハンドシェイクエラーを診断する際に特に役立ちます。すべての診断メッセージは標準エラー出力と、任意のログファイルに記録されます。
• インデックスの作成時や更新時に発生した権限エラーは、コンソールとログファイルの両方に明示的に表示されます。プロセスが FAISS_INDEX_PATH と各ナレッジベース内の .index/ ディレクトリに書き込めることを確認してください。
• npm test はプロジェクトをビルドし、並列 Jest プロジェクトを --maxWorkers=4 で実行した後、シリアルプロジェクトを --runInBand で実行します。テストスイートでは、ロガーのフォールバック動作と FAISS の権限処理をカバーしています。

セキュリティ

このサーバーは、ローカルツールとして実行するよう設計されています。つまり、1人のユーザー、1台のマシン、1つの信頼できるターミナルを想定しています。実際の運用では、2つの信頼境界が重要です。

$FAISS_INDEX_PATH はコード実行の境界です。 FaissStore.load は pickleparser を介して docstore をデシリアライズするため、このディレクトリにはこのサーバーが書き込んだファイルだけを置く必要があります。信頼できないバックアップや、複数のユーザーが書き込み可能なマウントは置かないでください。複数の MCP プロセスや CLI プロセスで、信頼できる インデックスパスを共有できます。書き込みはモデルごとのロックとアトミックな保存によって調整されます。

$KNOWLEDGE_BASES_ROOT_DIR はコンテンツの境界です。 ここに含まれる内容は埋め込み化され、そのまま MCP クライアントに返されます。そのため、信頼できないソースの Markdown は、結果を利用するエージェントにとってプロンプトインジェクションのリスクになります。信頼できないコンテンツのガード はデフォルトでこのリスクを軽減しますが、完全に排除するものではありません。

プロバイダーキーの取り扱い、パスの検証、リモートトランスポートの方針、並行処理に関する詳細は、docs/architecture/threat-model.md を参照してください。

ドキュメントの案内

docs/ に完全な目次があります。よく参照されるページは次のとおりです。

知りたいこと	参照先
特定の MCP クライアントを接続する	docs/clients.md
検索されやすいメモを書く	docs/authoring-knowledge.md
コマンド、フラグ、環境変数、ツール、メトリクス、エラーコードを調べる	docs/reference/ — ソースから生成されるため、内容が古くなることはありません
すべての検索フラグと、デフォルト値およびロールアウト状況を確認する	docs/feature-flags.md
CLI の JSON 出力を使ってスクリプトを作成する	docs/cli-json-contracts.md
デプロイを実行または復旧する	docs/operations/
システムの構築方法を理解する	docs/architecture/
その構築方法が選ばれた理由を理解する	docs/rfcs/ および docs/architecture/adr/

「RFC NNN」について。 このプロジェクトにおける重要な設計上の決定は、docs/rfcs/ に番号付きの RFC としてまとめられています。これはこのリポジトリ独自の設計ドキュメントシリーズであり、IETF 文書ではありません。上記のセクションで RFC が参照されている場合、機能の背景にある詳しい根拠を示しています。利用するために読む必要がある文書という意味ではありません。

貢献

貢献のワークフローについては CONTRIBUTING.md を、アーキテクチャ、規約、検証手順に関するエージェント向けガイドについては CLAUDE.md を参照してください。