hybrid-rag

Semantic search misses exact terms. Keyword search misses meaning. This uses both.

Local-first hybrid RAG engine for personal knowledge bases. No cloud, no API keys, no subscriptions.

🇮🇹 Versione italiana disponibile in fondo

query
  ├── ChromaDB (semantic HNSW cosine)  →  top-15 candidates
  ├── TF-IDF BM25 (keyword ngram 1-2)  →  top-15 candidates
  └── RRF merge (k=60)  →  CrossEncoder rerank  →  top-5 results

---

Why hybrid

Method	Strength	Weakness
Semantic only	Finds related concepts	Misses exact terms, codes, names
Keyword only	Exact match	Misses paraphrases, synonyms
Hybrid + rerank	Both	Slightly slower on large corpora

Reciprocal Rank Fusion merges both result lists without needing calibrated scores — the two retrievers work independently and still produce a coherent ranking.

---

Features

• Incremental indexing — manifest-based (mtime + size), rebuilds only changed files. First run: 3-5 min. Subsequent: <20 sec.
• Multilingual — paraphrase-multilingual-MiniLM-L12-v2 (IT/EN/DE/FR out of the box)
• CrossEncoder reranker — ms-marco-MiniLM-L-6-v2, two-stage: broad candidates → precise rerank
• Fully local — ChromaDB persisted on disk, TF-IDF pickled, no external calls
• Supported formats — .md .txt .py .json

---

Quick start

pip install chromadb sentence-transformers scikit-learn numpy

export DOCS_DIR=/path/to/your/documents   # Linux/Mac
set DOCS_DIR=C:\your\documents            # Windows

# Build index (first time or full rebuild)
python rag_engine.py --rebuild

# Incremental update (only changed files)
python rag_engine.py --incremental

# Search
python rag_engine.py "your query here"

# Stats
python rag_engine.py --stats

---

Configuration

CHUNK_SIZE     = 512    # chars — good for technical Q&A
CHUNK_STRIDE   = 200    # 61% overlap — balances context and precision
TOP_K          = 5      # final results returned
FETCH_K        = 15     # candidates before reranking
RRF_K          = 60     # RRF constant (higher = flatter score distribution)

---

Changelog

Version	Date	Status
v4.0	2026-05-28	ACTIVE — hybrid BM25+semantic+CrossEncoder+incremental
v3.0	2026-03	REPLACED by v4.0 — semantic only, no reranker, no incremental
v2.0	2026-02	REPLACED by v3.0 — ChromaDB basic, flat rebuild
v1.0	2025-12	REPLACED by v2.0 — plain TF-IDF, no semantic

---

Part of

TITANIUM_OS — personal cognitive OS. Full source: NODES/MENTE_RAG/rag_engine.py

---

Versione italiana

La ricerca semantica manca i termini esatti. La ricerca per parole chiave manca il significato. Questo usa entrambe.

RAG ibrido locale per knowledge base personali. Nessun cloud, nessuna API key.

Come funziona: ChromaDB (semantico) + TF-IDF BM25 (keyword) → merge RRF → CrossEncoder reranker → top-5 risultati.

Caratteristiche:

• Indicizzazione incrementale — ricostruisce solo i file modificati (mtime + size)
• Multilingua — italiano, inglese, tedesco, francese
• Completamente locale — nessuna chiamata esterna, nessun abbonamento
• Formati supportati: .md .txt .py .json

Codice sorgente: TITANIUM_OS → NODES/MENTE_RAG/rag_engine.py