What are the requirements for Hybrid RAG Project?

Hybrid RAG Project requires a compatible MCP client such as Claude Desktop, Claude Code, or Cursor. No additional environment variables are needed for basic setup.

Is Hybrid RAG Project free to use?

Yes, Hybrid RAG Project is open source and free to use. You can find the source code on GitHub.

What MCP clients support Hybrid RAG Project?

Hybrid RAG Project works with any MCP-compatible client including Claude Desktop (Anthropic's official desktop app), Claude Code (CLI tool), Cursor, and other editors with MCP support.

How do I configure Hybrid RAG Project?

Configure Hybrid RAG Project by adding it to your MCP client's config file. The setup block at the top of this page generates a ready-to-paste config for Claude Code, Cursor, Codex, Windsurf, and Claude Desktop.

MCP server/search

Hybrid RAG Project MCP Server

Q: What tools does Hybrid RAG Project provide?

query: Performs a hybrid search across the document store using both semantic and keyword matching.. ingest: Ingests new documents from the data directory into the vector store..

Q: How do I install Hybrid RAG Project?

Install Hybrid RAG Project by running: git clone && cd hybrid-rag-project && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

A generalized RAG system with hybrid search capabilities for any documents.

gwyer/hybrid-rag-project ↗by gwyerupdated Apr 9, 2026

Manual setup required. The maintainer's config contains paths only you know - edit the placeholders below before adding it to Claude Code.

Prepare the server locally

Run this once before adding it to Claude Code.

git clone <your-repo-url>
cd hybrid-rag-project
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Register it in Claude Code

claude mcp add hybrid-rag-project -- python /path/to/hybrid-rag-project/scripts/mcp_server_claude.py

Replace any placeholder paths in the command with the real path on your machine.

Make your agent remember this setup

hybrid-rag-project's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.

npx conare@latest

Free · one command · indexes the sessions already on disk. Set up in the browser instead →

What it does

Combines semantic vector search with BM25 keyword matching
Uses Reciprocal Rank Fusion (RRF) for optimal retrieval accuracy
Supports multiple file formats including TXT, PDF, MD, DOCX, and CSV
Integrates with local Ollama LLM for private document querying
Persistent vector store using Chroma for faster subsequent queries

Tools 2

queryPerforms a hybrid search across the document store using both semantic and keyword matching.

ingestIngests new documents from the data directory into the vector store.

Try it

→Search the local documents for information regarding the project's architecture.

→Find relevant documents about the installation process using keyword matching.

→Query the document store for details on how the hybrid fusion method works.

Original README from gwyer/hybrid-rag-project

Hybrid RAG Project

A generalized Retrieval-Augmented Generation (RAG) system with hybrid search capabilities that works with any documents you provide. Combines semantic (dense vector) search and keyword (sparse BM25) search for optimal document retrieval, with an MCP server API for easy integration.

🎯 Key Features: Multi-format support • Local LLM • Claude Desktop integration • Structured data queries • Document-type-aware retrieval

🚀 Quick Start (No MCP Required!)

You don't need Claude Desktop or MCP to use this project! Just run:

# 1. Make sure Ollama is running
ollama serve

# 2. Activate virtual environment
source .venv/bin/activate

# 3. Start conversational demo (recommended)
python scripts/demos/conversational.py

# Or use the shortcut
./scripts/bin/ask.sh

That's it! Ask questions about the 43,835 document chunks in the sample dataset.

📖 See Quick Start Guide for complete usage instructions. 📚 Browse all documentation in the docs/ folder or start with docs/README.md.

Overview

This project implements a hybrid RAG system that combines:

Semantic Search: Dense vector embeddings for understanding meaning and context
Keyword Search: BM25 sparse retrieval for exact keyword matching
Hybrid Fusion: Reciprocal Rank Fusion (RRF) to combine results from both methods
MCP Server: Both REST API and Model Context Protocol server for Claude integration
Multi-format Support: Automatically loads documents from various file formats

The hybrid approach ensures better retrieval accuracy by leveraging the strengths of both search methods.

Features

Vector-based semantic search using Chroma and Ollama embeddings
BM25 keyword search for exact term matching
Ensemble retriever with Reciprocal Rank Fusion (RRF)
Integration with local Ollama LLM for answer generation
Support for multiple document formats (TXT, PDF, MD, DOCX, CSV)
Automated document loading from data directory
RESTful API server with /ingest and /query endpoints
Model Context Protocol (MCP) server for Claude Desktop/API integration
Configuration-driven architecture (no hardcoded values)
Persistent vector store for faster subsequent queries

Architecture

User Documents → data/ directory
                      ↓
            Document Loader
                      ↓
Query → Hybrid Retriever → [Vector Retriever + BM25 Retriever]
                         → RRF Fusion
                         → Retrieved Context
                         → LLM (Ollama)
                         → Final Answer

Prerequisites

Python 3.9+
Ollama installed and running locally
Required Ollama models:
- llama3.1:latest (or another LLM model)
- nomic-embed-text (or another embedding model)

Installing Ollama

Visit ollama.ai to download and install Ollama for your platform.

After installation, pull the required models:

ollama pull llama3.1:latest
ollama pull nomic-embed-text

Verify Ollama is running:

curl http://localhost:11434/api/tags

Installation

Clone the repository:

git clone <your-repo-url>
cd hybrid-rag-project

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Project Structure

hybrid-rag-project/
├── src/
│   └── hybrid_rag/            # Core application package
│       ├── __init__.py        # Package initialization
│       ├── document_loader.py # Document loading utility
│       ├── structured_query.py# CSV query engine
│       └── utils.py           # Logging and utility functions
├── scripts/
│   ├── run_demo.py            # Main demonstration script
│   ├── mcp_server.py          # REST API server
│   └── mcp_server_claude.py   # MCP server for Claude integration
├── config/
│   ├── config.yaml            # Configuration file
│   └── claude_desktop_config.json # Sample Claude Desktop MCP config
├── docs/
│   ├── INSTALLATION.md        # Detailed installation guide
│   ├── STRUCTURED_QUERIES.md  # CSV query documentation
│   ├── ASYNC_INGESTION.md     # Async ingestion guide
│   └── SHUTDOWN.md            # Shutdown handling guide
├── data/                      # Sample data files (13 files included)
│   ├── *.csv                  # 7 CSV files (structured data)
│   ├── *.md                   # 5 Markdown files (unstructured)
│   └── *.txt                  # 1 Text file (technical specs)
├── chroma_db/

Frequently Asked Questions

What are the key features of Hybrid RAG Project?

Combines semantic vector search with BM25 keyword matching. Uses Reciprocal Rank Fusion (RRF) for optimal retrieval accuracy. Supports multiple file formats including TXT, PDF, MD, DOCX, and CSV. Integrates with local Ollama LLM for private document querying. Persistent vector store using Chroma for faster subsequent queries.

What can I use Hybrid RAG Project for?

Querying large collections of technical documentation for specific implementation details. Performing hybrid searches across mixed structured CSV data and unstructured markdown files. Building a private, local-only RAG pipeline for sensitive document analysis. Enhancing Claude's context with domain-specific knowledge from local files.

How do I install Hybrid RAG Project?

Install Hybrid RAG Project by running: git clone <your-repo-url> && cd hybrid-rag-project && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

What MCP clients work with Hybrid RAG Project?

Hybrid RAG Project works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Conare · memory for coding agents

Turn this server into reusable context

Keep Hybrid RAG Project docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Set up free$npx conare@latest