Knowledge Rag

🚀 Knowledge RAG System

A local RAG (Retrieval-Augmented Generation) system for Claude Code, featuring hybrid search (Semantic + BM25) with keyword routing for personal knowledge bases.

🚀 Quick Start

Knowledge RAG is a 100% local semantic search system integrated with Claude Code via MCP (Model Context Protocol). It allows Claude to search through your documents (PDFs, Markdown, code, etc.) and retrieve relevant context for answering questions.

Prerequisites

• Windows 10/11
• Python 3.11 or 3.12
• Ollama (for local embeddings)
• Claude Code CLI

Quick Install (Automated)

# Clone the repository
git clone https://github.com/lyonzin/knowledge-rag.git
cd knowledge-rag

# Run the installer
.\install.ps1

✨ Features

📦 Installation

Manual Installation

1. Install Python 3.12

   # Download from https://www.python.org/downloads/
   # Or use winget:
   winget install Python.Python.3.12
   

2. Install Ollama

   # Download from https://ollama.com
   # Or use winget:
   winget install Ollama.Ollama
   

3. Pull the embedding model

   ollama pull nomic-embed-text
   

4. Clone and setup the project

   git clone https://github.com/lyonzin/knowledge-rag.git
   cd knowledge-rag
   
   # Create virtual environment
   python -m venv venv
   .\venv\Scripts\activate
   
   # Install dependencies
   pip install -r requirements.txt
   

5. Configure MCP for Claude Code Add to ~/.claude.json under 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": {}
       }
     }
   }
   

   ⚠️ Important Note

   We use cmd /c with cd /d to ensure the working directory is set correctly before starting the Python server. This is required because Claude Code may not respect the cwd property in MCP configurations.

6. Restart Claude Code

💻 Usage Examples

Adding Documents

Place your documents in the documents/ directory, organized by category:

documents/
├── security/          # Pentest, exploit, vulnerability docs
│   ├── redteam/       # Red team specific
│   ├── blueteam/      # Blue team specific
│   └── RTFM.pdf
├── logscale/          # LogScale/LQL documentation
│   └── LQL_REFERENCE.md
├── ctf/               # CTF writeups and methodology
├── development/       # Code, APIs, frameworks
│   └── api-docs.md
└── general/           # Everything else
    └── notes.txt

Indexing Documents

Documents are automatically indexed when Claude Code starts. To manually reindex:

# In Claude Code chat:
Use the reindex_documents tool with force=true to rebuild the index

Searching

Simply ask Claude questions! The RAG system automatically provides context:

User: How do I use formatTime in LogScale?
Claude: [Uses search_knowledge internally, retrieves relevant chunks]
        Based on your documentation, formatTime in LogScale...

Hybrid Search Control

You can control the balance between semantic and keyword search:

// Pure keyword - INSTANT, no Ollama needed (default for exact terms)
search_knowledge("gtfobins suid", hybrid_alpha=0.0)

// Keyword-heavy (default) - fast, slight semantic boost
search_knowledge("lolbas certutil", hybrid_alpha=0.3)

// Balanced hybrid - both engines equally weighted
search_knowledge("SQL injection techniques", hybrid_alpha=0.5)

// Semantic-heavy - better for conceptual queries
search_knowledge("how to escalate privileges", hybrid_alpha=0.7)

// Pure semantic - Ollama only, no keyword matching
search_knowledge("how to bypass authentication", hybrid_alpha=1.0)

📚 Documentation

API Reference

search_knowledge

Hybrid search combining semantic search + BM25 keyword search.

Parameters:

Returns: JSON with search results including content, source, relevance score, and search method.

Example:

{
  "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"
    }
  ]
}

Search Method Values:

• hybrid: Found by both semantic and BM25 search (highest confidence)
• semantic: Found only by semantic search
• keyword: Found only by BM25 keyword search

get_document

Retrieve the full content of a specific document.

Parameters:

Returns: JSON with document content and metadata.

reindex_documents

Index or reindex all documents in the knowledge base.

Parameters:

Returns: JSON with indexing statistics.

list_categories

List all document categories with their document counts.

Returns:

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

list_documents

List all indexed documents, optionally filtered by category.

Parameters:

get_index_stats

Get statistics about the knowledge base index.

Returns:

{
  "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
  }
}

Configuration

Keyword Routing

The system uses keyword routing with word boundaries to improve search accuracy.

Configure routes in 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", ...]
}

Word Boundary Matching: Single-word keywords use regex word boundaries (\b) to prevent false positives. For example, "api" won't match "RAPID".

Weighted Scoring: When multiple keywords match, the category with the most matches wins.

Chunking Settings

Adjust chunk size and overlap in config.py:

chunk_size = 1000      # Characters per chunk
chunk_overlap = 200    # Overlap between chunks

Embedding Model

The default model is nomic-embed-text. To change:

1. Pull a different model: ollama pull <model-name>
2. Update config.py: ollama_model = "<model-name>"

Hybrid Search Tuning

The hybrid_alpha parameter controls the balance:

🔧 Technical Details

Architecture

System Overview

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

Data Flow

1. Document Ingestion Flow

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. Query Processing Flow (Hybrid Search)

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 Parameter Effect

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

Project Structure

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          # Configuration settings
│   ├── ingestion.py       # Document parsing & chunking
│   └── server.py          # MCP server, ChromaDB, BM25
├── documents/             # Your documents go here
│   ├── security/
│   ├── Detections_Rules/
│   ├── development/
│   └── general/
├── data/
│   ├── chroma_db/         # Vector database storage
│   └── index_metadata.json
├── .claude/
│   └── mcp.json           # Project MCP config
├── venv/                  # Python virtual environment
├── install.ps1            # Automated installer
├── requirements.txt       # Python dependencies
├── CHANGELOG.md           # Version history
└── README.md              # This file

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Ollama not running

# Start Ollama
ollama serve

# Or check if running
curl http://localhost:11434/api/tags

Python version mismatch

ChromaDB requires Python 3.11 or 3.12. Python 3.13+ is NOT supported due to onnxruntime compatibility.

# Check version
python --version

# Use specific version
py -3.12 -m venv venv

Index is empty

# Check documents directory
ls documents/

# Force reindex
# In Claude Code: use reindex_documents(force=true)

MCP server not loading

1. Check ~/.claude.json exists and has mcpServers section with valid JSON
2. Verify paths use double backslashes (\\) on Windows
3. Restart Claude Code completely
4. Run claude mcp list to check connection status

"ModuleNotFoundError: No module named 'rank_bm25'"

Install the BM25 dependency in your virtual environment:

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

"ModuleNotFoundError: No module named 'mcp_server'"

This error occurs when Claude Code doesn't set the working directory correctly. Solution: Use the cmd /c "cd /d ... && python" wrapper in your config:

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

Changelog

v2.2.0 (2026-02-27)

• FIX: hybrid_alpha=0 now completely skips Ollama embedding - pure BM25 is instant
• FIX: hybrid_alpha=1.0 now skips BM25 search - no unnecessary keyword computation
• CHANGED: Default hybrid_alpha from 0.5 to 0.3 (keyword-heavy for faster responses)
• NEW: 40+ keyword routes for redteam category (GTFOBins, LOLBAS, BYOVD, SQLi, XSS, SSTI, hashcat, etc.)

v2.1.0 (2026-02-05)

• NEW: Interactive Mermaid flowcharts for architecture visualization
• NEW: Query processing flow diagram showing hybrid search internals
• NEW: Document ingestion pipeline diagram
• NEW: Keyword routing visual explanation
• NEW: hybrid_alpha parameter effect diagram
• NEW: Project structure visual diagram
• IMPROVED: Documentation now GitHub-native with dark/light theme support

v2.0.0 (2025-01-20)

• NEW: Hybrid search combining semantic + BM25 keyword search
• NEW: Reciprocal Rank Fusion (RRF) for optimal result ranking
• NEW: hybrid_alpha parameter to control search balance
• NEW: search_method field in results (hybrid/semantic/keyword)
• IMPROVED: Keyword routing with word boundaries (no more false positives)
• IMPROVED: Weighted scoring for multiple keyword matches
• IMPROVED: Parallel embedding generation (4x faster indexing)
• IMPROVED: Input validation on MCP tools
• FIXED: Chunk loop infinite loop potential
• FIXED: Embedding error handling

v1.0.1 (2025-01-16)

• Auto-cleanup orphan UUID folders on reindex
• Removed hardcoded user paths
• Made install.ps1 plug-and-play

v1.0.0 (2025-01-15)

• Initial release

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Acknowledgments

• ChromaDB - Vector database
• Ollama - Local LLM & embeddings
• FastMCP - MCP framework
• PyMuPDF - PDF parsing
• rank-bm25 - BM25 implementation

Author

Ailton Rocha (Lyon)

AI Operator | Security Researcher | Developer