知识检索工具

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 12 for accelerated embeddings (see GPU Acceleration below)

1. Install GPU dependencies (onnxruntime-gpu + all CUDA 12 runtime DLLs)

pip install knowledge-rag[gpu]

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.

config.yaml

server: transport: "sse" # "stdio" | "sse" | "streamable-http" host: "127.0.0.1" port: 8179 ```

Or via CLI: knowledge-rag --transport sse

Optional enterprise features (all disabled by default): - Rate limiting: Sliding-window counter, configurable RPM and burst - Prometheus metrics: /metrics endpoint on separate port - Bearer auth: Token validation for SSE/HTTP connections

All 13 MCP tools are instrumented with @rate_limited and @instrument decorators — zero overhead when features are disabled. Default transport remains stdio for full backwards compatibility.

Migration: Existing users need zero changes. SSE mode is opt-in via server.transport: "sse" in config.yaml. See Configuration for details.

2. Enable in config.yaml

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

Server

In stdio mode (default), server settings are ignored. SSE/HTTP mode auto-enables the single-instance lock.

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.

query_expansions is directional: only the key on the left triggers the terms on the right. If you need mutual expansion without duplicating entries, use query_expansion_groups.

query_expansion_groups:
  - ["triple barrier", "tb", "trip_barr"]
  - ["profit factor", "pf"]

Each group is interpreted symmetrically, so every term expands to the rest of the group. The final internal expansion table is built by merging both sources:

1. query_expansions entries are loaded as-is.
2. query_expansion_groups adds reciprocal links for every term in each group.
3. Overlaps are merged by union with duplicate terms removed.

This keeps backward compatibility while allowing concise synonym groups.

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