知识检索工具

Prerequisites

• Python 3.11+
• Claude Code CLI
• …or any other MCP client (Claude Desktop, Cursor, VS Code, Antigravity, opencode, Windsurf) — see Use with other MCP clients
• ~200MB disk for model cache (auto-downloaded on first run)
• Optional: NVIDIA GPU + CUDA for accelerated embeddings (pip install knowledge-rag[gpu] + models.embedding.gpu: true in config)

5 Ways to Install

npx -y knowledge-rag                    # NPM — zero setup, auto-manages Python venv
pip install knowledge-rag               # PyPI — classic Python install
curl -fsSL .../install.sh | bash        # One-line installer (Linux/macOS/Windows)
docker pull ghcr.io/lyonzin/knowledge-rag  # Docker — models pre-downloaded
git clone ... && pip install -r ...     # From source

All methods produce the same MCP server. See Installation for full instructions.

Installation

Install Methods

Pick one — all produce the same running server.

Option A: NPX (fastest)

Requires Node.js 16+. Handles Python venv, pip install, and version upgrades automatically.

claude mcp add knowledge-rag -s user -- npx -y knowledge-rag

That's it. On first run, npx creates a venv at ~/.knowledge-rag/, installs the PyPI package, and starts the MCP server. Subsequent runs reuse the cached venv.

Option B: One-line installer

```bash

Smart reindex: detect changes + rebuild BM25

reindex_documents(force=True)

Nuclear rebuild: delete everything, re-embed all (use after model change)

reindex_documents(full_rebuild=True) ```

Or nuclear rebuild if model changed:

reindex_documents(full_rebuild=True)

```

Usage

Quick Start

```bash

Memory usage

With ~200 documents, expect ~300-500MB RAM. The embedding model (~200MB ONNX runtime resident, lazy-loaded on first query since v3.8.0) and reranker (~25MB, lazy-loaded) are loaded into memory only when actually used. For very large knowledge bases (1000+ documents), consider enabling GPU acceleration and using exclude patterns to limit index scope.

Configuration

Knowledge RAG is fully configurable via a config.yaml file in the project root. If no config.yaml exists, sensible defaults are used — the system works out of the box with zero configuration.

Option 1: Use a preset

cp presets/cybersecurity.yaml config.yaml # Offensive/defensive security, CTFs cp presets/developer.yaml config.yaml # Software engineering, APIs, DevOps cp presets/research.yaml config.yaml # Academic research, papers, studies cp presets/general.yaml config.yaml # Blank slate, pure semantic search

Option 2: Start from the documented template

cp config.example.yaml config.yaml

Edit config.yaml to your needs

```

Restart Claude Code after changing config.yaml.

config.yaml Structure

```yaml

Configuration Reference

Paths

Relative paths resolve from the project root. Absolute paths work too.

Documents

Chunking guidelines: Short notes → 500/100. General use → 1000/200. Long technical docs → 1500/300.

For .md files, chunking splits at ## and ### header boundaries first. Sections larger than chunk_size are sub-chunked with overlap. Non-markdown files use fixed-size chunking.

Models

If the reranker model is not available locally and the machine cannot download it, search now falls back to the RRF order from hybrid semantic+BM25 retrieval. This keeps search_knowledge available offline, but result ordering may be less precise for ambiguous queries until the reranker model is cached.

Embedding model options (fastest → most accurate): - BAAI/bge-small-en-v1.5 — 384D, ~33MB (default) - BAAI/bge-base-en-v1.5 — 768D, ~130MB - BAAI/bge-large-en-v1.5 — 1024D, ~335MB - intfloat/multilingual-e5-small — 384D, 100+ languages

Warning: Changing the embedding model after indexing requires reindex_documents(full_rebuild=True).

Search

Categories

Map folder paths to category names. Documents in matching folders get auto-tagged, enabling filtered searches.

category_mappings:
  "security/redteam": "redteam"
  "security": "security"

Set category_mappings: {} to disable — documents are still searchable, just without category filters.

Keyword Routing

Route queries to categories based on keywords. When a query contains listed keywords, results from that category are prioritized (not filtered — other categories still appear, ranked lower).

keyword_routes:
  redteam:
    - pentest
    - exploit
    - sqli

Single-word keywords use regex word boundaries (\b) — "api" won't match "RAPID". Multi-word keywords use substring matching.

Set keyword_routes: {} for pure semantic search.

Query Expansion

Expand search terms with synonyms before BM25 search. Supports single tokens, bigrams, and full query matches.

query_expansions:
  sqli:
    - sql injection
    - sqli
  k8s:
    - kubernetes
    - k8s

Set query_expansions: {} for no expansion.

API Reference

Models — AI models for search (all run locally, no API keys)

models: embedding: model: "BAAI/bge-small-en-v1.5" # ONNX, ~33MB, auto-downloaded dimensions: 384 gpu: false # Set true + pip install knowledge-rag[gpu] reranker: enabled: true # Falls back to RRF if model is unavailable model: "Xenova/ms-marco-MiniLM-L-6-v2" top_k_multiplier: 3 # Candidates fetched before reranking

Troubleshooting