Knowledge Rag

🚀 知識RAGシステム

Claude Code用のローカルRAG（Retrieval-Augmented Generation）システム。個人の知識ベースに対するハイブリッド検索（セマンティック + BM25）とキーワードルーティングを提供します。

v2.2.0の新機能

検索パフォーマンスの修正

• hybrid_alpha=0 ではOllamaを完全にスキップ - 純粋なBM25キーワード検索が即座に実行されます（埋め込み生成なし）
• hybrid_alpha=1.0 ではBM25をスキップ - キーワードのオーバーヘッドなしの純粋なセマンティック検索
• デフォルトが0.5から0.3に変更 - デフォルトでキーワード重視となり、より高速な応答が得られます

キーワードルーティングの拡張

• redteam カテゴリに40以上の新しいキーワードを追加：GTFOBins、LOLBAS、BYOVD、SQLi、XSS、SSTI、hashcat、Kerberoast、BloodHound、ADCSなど
• 攻撃的セキュリティクエリに対するルーティング精度が向上

前バージョン (v2.0.0)

• 相互ランク融合を用いたハイブリッド検索（セマンティック + BM25）
• 単語境界に基づくキーワードルーティング（誤検出なし）
• 並列埋め込み生成（インデックス作成が4倍高速化）

概要

知識RAGは、MCP（Model Context Protocol）を介してClaude Codeと統合された100%ローカルのセマンティック検索システムです。Claudeがドキュメント（PDF、Markdown、コードなど）を検索し、質問に対する関連コンテキストを取得できるようにします。

知識RAGを選ぶ理由

• プライバシー重視：すべての処理はローカルで行われ、データはマシンから流出しません
• ハイブリッド検索：セマンティック理解と正確なキーワードマッチングを組み合わせます
• 複数フォーマット対応：MD、PDF、TXT、Python、JSONファイルをサポートします
• スマートなルーティング：単語境界に基づくキーワードルーティングにより、正確なカテゴリマッチングが可能です
• Claudeとの統合：ネイティブのMCPツールにより、Claude Codeとのシームレスな統合が実現されます
• 高速：並列埋め込み生成 + ChromaDBによるベクトル検索

✨ 主な機能

🔧 技術詳細

システム概要

flowchart TB
    subgraph MCP["🔌 MCP SERVER (FastMCP)"]
        direction TB
        TOOLS["MCP Tools<br/>search_knowledge | get_document<br/>reindex_documents | list_categories"]
    end

    subgraph SEARCH["🔍 HYBRID SEARCH ENGINE"]
        direction LR
        ROUTER["Keyword Router<br/>(word boundaries)"]
        SEMANTIC["Semantic Search<br/>(ChromaDB)"]
        BM25["BM25 Keyword<br/>(rank-bm25)"]
        RRF["Reciprocal Rank<br/>Fusion (RRF)"]

        ROUTER --> SEMANTIC
        ROUTER --> BM25
        SEMANTIC --> RRF
        BM25 --> RRF
    end

    subgraph STORAGE["💾 STORAGE LAYER"]
        direction LR
        CHROMA[("ChromaDB<br/>Vector Database")]
        COLLECTIONS["Collections<br/>security | ctf<br/>logscale | development"]
        CHROMA --- COLLECTIONS
    end

    subgraph EMBED["🧠 EMBEDDINGS"]
        OLLAMA["Ollama<br/>nomic-embed-text<br/>(768 dimensions)"]
        PARALLEL["Parallel Processing<br/>(4 workers)"]
        OLLAMA --- PARALLEL
    end

    subgraph INGEST["📄 DOCUMENT INGESTION"]
        PARSERS["Parsers<br/>MD | PDF | TXT | PY | JSON"]
        CHUNKER["Chunking<br/>1000 chars + 200 overlap"]
        PARSERS --> CHUNKER
    end

    CLAUDE["☁️ Claude Code"] --> MCP
    MCP --> SEARCH
    SEARCH --> STORAGE
    STORAGE --> EMBED
    INGEST --> EMBED
    EMBED --> STORAGE

データフロー

1. ドキュメント取り込みフロー

flowchart LR
    subgraph INPUT["📁 Input"]
        FILES["documents/<br/>├── security/<br/>├── logscale/<br/>├── ctf/<br/>└── development/"]
    end

    subgraph PARSE["📖 Parse"]
        MD["Markdown<br/>Parser"]
        PDF["PDF Parser<br/>(PyMuPDF)"]
        TXT["Text<br/>Parser"]
        CODE["Code Parser<br/>(PY/JSON)"]
    end

    subgraph CHUNK["✂️ Chunk"]
        SPLIT["Text Splitter<br/>1000 chars"]
        OVERLAP["Overlap<br/>200 chars"]
        SPLIT --> OVERLAP
    end

    subgraph EMBED["🧠 Embed"]
        PARALLEL["ThreadPoolExecutor<br/>(4 workers)"]
        OLLAMA["Ollama API<br/>nomic-embed-text"]
        PARALLEL --> OLLAMA
    end

    subgraph STORE["💾 Store"]
        CHROMADB[("ChromaDB")]
        BM25IDX["BM25 Index"]
    end

    FILES --> MD & PDF & TXT & CODE
    MD & PDF & TXT & CODE --> CHUNK
    CHUNK --> EMBED
    EMBED --> STORE

2. クエリ処理フロー（ハイブリッド検索）

flowchart TB
    QUERY["🔍 User Query<br/>'mimikatz credential dump'"] --> ROUTER

    subgraph ROUTING["📍 Keyword Routing"]
        ROUTER["Keyword Router"]
        MATCH{"Word Boundary<br/>Match?"}
        CATEGORY["Filter: redteam"]
        NOFILTER["No Filter"]

        ROUTER --> MATCH
        MATCH -->|Yes| CATEGORY
        MATCH -->|No| NOFILTER
    end

    subgraph HYBRID["⚡ Hybrid Search"]
        direction LR
        SEMANTIC["Semantic Search<br/>(ChromaDB)<br/>Conceptual similarity"]
        BM25["BM25 Search<br/>(rank-bm25)<br/>Exact term matching"]
    end

    subgraph FUSION["🔀 Result Fusion"]
        RRF["Reciprocal Rank Fusion<br/>score = Σ 1/(k + rank)"]
        COMBINE["Combine Rankings<br/>+ Deduplicate"]
        SORT["Sort by<br/>Combined Score"]

        RRF --> COMBINE --> SORT
    end

    CATEGORY --> HYBRID
    NOFILTER --> HYBRID
    SEMANTIC --> RRF
    BM25 --> RRF

    SORT --> RESULTS["📋 Results<br/>search_method: hybrid|semantic|keyword<br/>semantic_rank + bm25_rank"]

3. hybrid_alphaパラメータの影響

flowchart LR
    subgraph ALPHA["hybrid_alpha values"]
        A0["0.0<br/>Pure BM25<br/>⚡ INSTANT"]
        A3["0.3 (default)<br/>Keyword-heavy<br/>⚡ Fast"]
        A5["0.5<br/>Balanced"]
        A7["0.7<br/>Semantic-heavy"]
        A10["1.0<br/>Pure Semantic<br/>🐢 Slower"]
    end

    subgraph USE["Best For"]
        U0["CVEs, tool names<br/>exact matches<br/>NO Ollama needed"]
        U3["Technical queries<br/>specific terms"]
        U5["General queries"]
        U7["Conceptual queries<br/>related topics"]
        U10["'How to...' questions<br/>Requires Ollama"]
    end

    A0 --- U0
    A3 --- U3
    A5 --- U5
    A7 --- U7
    A10 --- U10

📦 インストール

前提条件

• Windows 10/11
• Python 3.11または3.12
• Ollama（ローカル埋め込み用）
• Claude Code CLI

クイックインストール（自動）

# リポジトリをクローン
git clone https://github.com/lyonzin/knowledge-rag.git
cd knowledge-rag

# インストーラーを実行
.\install.ps1

手動インストール

1. Python 3.12をインストール

   # https://www.python.org/downloads/ からダウンロード
   # またはwingetを使用:
   winget install Python.Python.3.12
   

2. Ollamaをインストール

   # https://ollama.com からダウンロード
   # またはwingetを使用:
   winget install Ollama.Ollama
   

3. 埋め込みモデルを取得

   ollama pull nomic-embed-text
   

4. プロジェクトをクローンしてセットアップ

   git clone https://github.com/lyonzin/knowledge-rag.git
   cd knowledge-rag
   
   # 仮想環境を作成
   python -m venv venv
   .\venv\Scripts\activate
   
   # 依存関係をインストール
   pip install -r requirements.txt
   

5. Claude Code用にMCPを設定

   ~/.claude.json の mcpServers の下に以下を追加します：

   {
     "mcpServers": {
       "knowledge-rag": {
         "type": "stdio",
         "command": "cmd",
         "args": ["/c", "cd /d C:\\path\\to\\knowledge-rag && .\\venv\\Scripts\\python.exe -m mcp_server.server"],
         "env": {}
       }
     }
   }
   

   注意: cmd /c と cd /d を使用して、Pythonサーバーを起動する前に作業ディレクトリを正しく設定します。Claude CodeがMCP構成の cwd プロパティを尊重しない場合があるため、これは必要です。

6. Claude Codeを再起動

💻 使用例

ドキュメントの追加

ドキュメントを documents/ ディレクトリにカテゴリごとに配置します：

documents/
├── security/          # ペンテスト、エクスプロイト、脆弱性ドキュメント
│   ├── redteam/       # レッドチーム関連
│   ├── blueteam/      # ブルーチーム関連
│   └── RTFM.pdf
├── logscale/          # LogScale/LQLのドキュメント
│   └── LQL_REFERENCE.md
├── ctf/               # CTFのwriteupと方法論
├── development/       # コード、API、フレームワーク
│   └── api-docs.md
└── general/           # その他すべて
    └── notes.txt

ドキュメントのインデックス作成

Claude Codeが起動すると、ドキュメントは自動的にインデックスが作成されます。手動で再インデックスを作成するには：

# Claude Codeのチャットで:
force=true で reindex_documents ツールを使用してインデックスを再構築します

検索

Claudeに質問を投げかけるだけです！RAGシステムが自動的にコンテキストを提供します：

ユーザー: LogScaleでformatTimeをどう使うの？
Claude: [内部的にsearch_knowledgeを使用し、関連するチャンクを取得]
        あなたのドキュメントによると、LogScaleのformatTimeは...

ハイブリッド検索の制御

セマンティック検索とキーワード検索のバランスを制御できます：

// 純粋なキーワード - 即時、Ollama不要（正確な用語のデフォルト）
search_knowledge("gtfobins suid", hybrid_alpha=0.0)

// キーワード重視（デフォルト） - 高速、わずかなセマンティックブースト
search_knowledge("lolbas certutil", hybrid_alpha=0.3)

// バランスの取れたハイブリッド - 両方のエンジンが同等に重み付けされる
search_knowledge("SQL injection techniques", hybrid_alpha=0.5)

// セマンティック重視 - 概念的なクエリに適しています
search_knowledge("how to escalate privileges", hybrid_alpha=0.7)

// 純粋なセマンティック - Ollamaのみ、キーワードマッチングなし
search_knowledge("how to bypass authentication", hybrid_alpha=1.0)

📚 詳細ドキュメント

MCPツール

search_knowledge

セマンティック検索とBM25キーワード検索を組み合わせたハイブリッド検索。

パラメータ:

返り値: 検索結果を含むJSON（内容、ソース、関連性スコア、検索方法）。

例:

{
  "status": "success",
  "query": "mimikatz credential dump",
  "hybrid_alpha": 0.5,
  "result_count": 3,
  "results": [
    {
      "content": "Mimikatz can extract credentials from memory...",
      "source": "C:/docs/security/redteam/credential-attacks.pdf",
      "filename": "credential-attacks.pdf",
      "category": "redteam",
      "score": 0.016393,
      "semantic_rank": 2,
      "bm25_rank": 1,
      "search_method": "hybrid",
      "keywords": ["mimikatz", "credential", "lsass"],
      "routed_by": "redteam"
    }
  ]
}

検索方法の値:

• hybrid: セマンティック検索とBM25検索の両方で見つかった（最も信頼度が高い）
• semantic: セマンティック検索のみで見つかった
• keyword: BM25キーワード検索のみで見つかった

get_document

特定のドキュメントの完全な内容を取得します。

パラメータ:

返り値: ドキュメントの内容とメタデータを含むJSON。

reindex_documents

知識ベース内のすべてのドキュメントのインデックスを作成または再作成します。

パラメータ:

返り値: インデックス作成の統計情報を含むJSON。

list_categories

すべてのドキュメントカテゴリとそのドキュメント数をリストします。

返り値:

{
  "status": "success",
  "categories": {
    "security": 52,
    "Detections_Rules ": 12,
    "redteam": 3,
    "blueteam": 3,
    "ctf": 2,
    "general": 1
  },
  "total_documents": 73
}

list_documents

インデックスが作成されたすべてのドキュメントを、オプションでカテゴリでフィルタリングしてリストします。

パラメータ:

get_index_stats

知識ベースのインデックスに関する統計情報を取得します。

返り値:

{
  "status": "success",
  "stats": {
    "total_documents": 73,
    "total_chunks": 9256,
    "categories": {"security": 52, "logscale": 12, ...},
    "embedding_model": "nomic-embed-text",
    "chunk_size": 1000,
    "chunk_overlap": 200
  }
}

設定

キーワードルーティング

システムは単語境界を考慮したキーワードルーティングを使用して、検索精度を向上させます。

flowchart TB
    QUERY["Query: 'CVE-2021-44228 log4j'"] --> EXTRACT["Extract Keywords"]

    subgraph ROUTES["🏷️ Keyword Routes (config.py)"]
        SEC["security<br/>anti-bot, waf bypass, cloudflare..."]
        RED["redteam<br/>pentest, exploit, payload..."]
        BLUE["blueteam<br/>detection, sigma, yara..."]
        CTF["ctf<br/>ctf, flag, hackthebox..."]
        LOG["logscale<br/>logscale, humio, lql..."]
        DEV["development<br/>python, javascript, api..."]
    end

    EXTRACT --> CHECK{"Word Boundary<br/>Check (\\b)"}

    CHECK -->|"'api' in query?"| BOUNDARY["Does NOT match<br/>'RAPID' or 'capital'"]
    CHECK -->|"'log4j' matches"| MATCHED["✓ Matches 'security'<br/>route"]

    BOUNDARY --> NOROUTE["No routing applied"]
    MATCHED --> WEIGHT["Weighted Scoring<br/>Multiple matches = higher confidence"]
    WEIGHT --> FILTER["Filter to 'security' category"]

mcp_server/config.py でルートを設定します：

keyword_routes = {
    "security": ["anti-bot", "waf bypass", "cloudflare", ...],
    "redteam": ["pentest", "exploit", "payload", "reverse shell", ...],
    "blueteam": ["detection", "sigma", "yara", "incident response", ...],
    "ctf": ["ctf", "flag", "hackthebox", "tryhackme", ...],
    "Detections_Rules": ["logscale", "humio", "lql", "formatTime", ...],
    "development": ["python", "javascript", "api", "docker", ...]
}

単語境界のマッチング: 単語のキーワードは正規表現の単語境界 (\b) を使用して、誤検出を防ぎます。たとえば、"api" は "RAPID" とはマッチしません。

重み付きスコアリング: 複数のキーワードがマッチした場合、最も多くのマッチがあるカテゴリが選択されます。

チャンク分割設定

config.py でチャンクサイズとオーバーラップを調整します：

chunk_size = 1000      # チャンクあたりの文字数
chunk_overlap = 200    # チャンク間のオーバーラップ

埋め込みモデル

デフォルトのモデルは nomic-embed-text です。変更するには：

1. 別のモデルを取得します：ollama pull <model-name>
2. config.py を更新します：ollama_model = "<model-name>"

ハイブリッド検索の調整

hybrid_alpha パラメータでバランスを制御します：

プロジェクト構造

flowchart TB
    subgraph ROOT["📁 knowledge-rag/"]
        direction TB

        subgraph SERVER["🐍 mcp_server/"]
            INIT["__init__.py"]
            CONFIG["config.py<br/>(settings, routes)"]
            INGEST["ingestion.py<br/>(parsing, chunking)"]
            SERV["server.py<br/>(MCP, ChromaDB, BM25)"]
        end

        subgraph DOCS["📚 documents/"]
            SEC["security/<br/>Pentest, exploits"]
            LOG["logscale/<br/>LQL docs"]
            DEV["development/<br/>Code, APIs"]
            GEN["general/<br/>Everything else"]
        end

        subgraph DATA["💾 data/"]
            CHROMA["chroma_db/<br/>(Vector storage)"]
            META["index_metadata.json"]
        end

        subgraph FILES["📄 Root Files"]
            INSTALL["install.ps1"]
            REQS["requirements.txt"]
            README["README.md"]
            CHANGE["CHANGELOG.md"]
        end
    end

knowledge-rag/
├── mcp_server/
│   ├── __init__.py
│   ├── config.py          # 設定
│   ├── ingestion.py       # ドキュメントの解析とチャンク分割
│   └── server.py          # MCPサーバー、ChromaDB、BM25
├── documents/             # ドキュメントをここに配置
│   ├── security/
│   ├── Detections_Rules/
│   ├── development/
│   └── general/
├── data/
│   ├── chroma_db/         # ベクトルデータベースのストレージ
│   └── index_metadata.json
├── .claude/
│   └── mcp.json           # プロジェクトのMCP設定
├── venv/                  # Python仮想環境
├── install.ps1            # 自動インストーラー
├── requirements.txt       # Pythonの依存関係
├── CHANGELOG.md           # バージョン履歴
└── README.md              # このファイル

トラブルシューティング

Ollamaが実行されていない場合

# Ollamaを起動
ollama serve

# または実行中かどうかを確認
curl http://localhost:11434/api/tags

Pythonバージョンが一致しない場合

ChromaDBはPython 3.11または3.12が必要です。Python 3.13以降はonnxruntimeの互換性の問題でサポートされていません。

# バージョンを確認
python --version

# 特定のバージョンを使用
py -3.12 -m venv venv

インデックスが空の場合

# ドキュメントディレクトリを確認
ls documents/

# 強制的に再インデックスを作成
# Claude Codeで: reindex_documents(force=true) を使用

MCPサーバーが読み込まれない場合

1. ~/.claude.json が存在し、mcpServers セクションに有効なJSONが含まれていることを確認します
2. Windowsではパスがダブルバックスラッシュ (\\) を使用していることを確認します
3. Claude Codeを完全に再起動します
4. claude mcp list を実行して接続状態を確認します

"ModuleNotFoundError: No module named 'rank_bm25'"

仮想環境でBM25の依存関係をインストールします：

.\venv\Scripts\pip.exe install rank-bm25

"ModuleNotFoundError: No module named 'mcp_server'"

このエラーは、Claude Codeが作業ディレクトリを正しく設定しない場合に発生します。解決策: 構成で cmd /c "cd /d ... && python" ラッパーを使用します：

{
  "knowledge-rag": {
    "type": "stdio",
    "command": "cmd",
    "args": ["/c", "cd /d C:\\path\\to\\knowledge-rag && .\\venv\\Scripts\\python.exe -m mcp_server.server"],
    "env": {}
  }
}

変更履歴

v2.2.0 (2026-02-27)

• 修正: hybrid_alpha=0 でOllamaの埋め込みを完全にスキップ - 純粋なBM25が即座に実行されます
• 修正: hybrid_alpha=1.0 でBM25検索をスキップ - 不要なキーワード計算を行いません
• 変更: デフォルトの hybrid_alpha を0.5から0.3に変更（高速な応答のためにキーワード重視）
• 新機能: redteam カテゴリに40以上のキーワードルートを追加（GTFOBins、LOLBAS、BYOVD、SQLi、XSS、SSTI、hashcatなど）

v2.1.0 (2026-02-05)

• 新機能: アーキテクチャの可視化のためのインタラクティブなMermaidフローチャート
• 新機能: ハイブリッド検索の内部を示すクエリ処理フロー図
• 新機能: ドキュメント取り込みパイプラインの図
• 新機能: キーワードルーティングの視覚的な説明
• 新機能: hybrid_alphaパラメータの影響の図
• 新機能: プロジェクト構造の視覚的な図
• 改善: ドキュメントをGitHubネイティブにし、ダーク/ライトテーマをサポート

v2.0.0 (2025-01-20)

• 新機能: セマンティック + BM25キーワード検索を組み合わせたハイブリッド検索
• 新機能: 最適な結果ランキングのための相互ランク融合（RRF）
• 新機能: 検索バランスを制御する hybrid_alpha パラメータ
• 新機能: 結果に search_method フィールドを追加（hybrid/semantic/keyword）
• 改善: 単語境界を考慮したキーワードルーティング（誤検出なし）
• 改善: 複数のキーワードマッチに対する重み付きスコアリング
• 改善: 並列埋め込み生成（インデックス作成が4倍高速化）
• 改善: MCPツールの入力検証
• 修正: チャンクループの無限ループの可能性
• 修正: 埋め込みエラーの処理

v1.0.1 (2025-01-16)

• 再インデックス時に孤立したUUIDフォルダを自動的にクリーンアップ
• ハードコードされたユーザーパスを削除
• install.ps1をプラグアンドプレイにしました

v1.0.0 (2025-01-15)

• 初期リリース

貢献方法

1. リポジトリをフォークします
2. 機能ブランチを作成します (git checkout -b feature/amazing-feature)
3. 変更をコミットします (git commit -m 'Add amazing feature')
4. ブランチにプッシュします (git push origin feature/amazing-feature)
5. プルリクエストを作成します

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

謝辞

• ChromaDB - ベクトルデータベース
• Ollama - ローカルLLMと埋め込み
• FastMCP - MCPフレームワーク
• PyMuPDF - PDF解析
• rank-bm25 - BM25の実装

作者

Ailton Rocha (Lyon)

AIオペレーター | セキュリティ研究者 | 開発者