rag-memory-lab

What it is

RAG Memory Lab is a practical project to learn local RAG retrieval end-to-end without calling external generation services or API keys. It guides users through Markdown chunking, local embedding, indexing, recall, reordering, and creating Evidence Cards that include sources and provenance.

How it works

The project outlines a pipeline across multiple steps:

• Markdown parsing and sentence splitting
• SQLite FTS5 with BM25 inverted index
• Local embeddings with NumPy and Milvus Lite index
• Hybrid recall using Reciprocal Rank Fusion (RRF)
• Cross-Encoder reordering
• Evidence Card construction with sources and ranking trail

Files and modules map to these stages:

• src/chunking.py uses MarkdownNodeParser and SentenceSplitter to chunk Markdown with metadata
• src/run_chunking.py generates chunks.jsonl and doc statistics
• src/fts5_index.py builds chunks table and FTS5 virtual table and runs BM25 searches
• src/vector_search.py handles embeddings, NumPy cosine similarity, Milvus Lite
• src/run_vector_index.py builds FTS5, vector files, and Milvus Lite indexes
• src/evaluation.py / src/run_evaluation.py read Goldens and compute Recall@K, Precision@K, Hit@K, MRR
• src/hybrid_search.py / src/run_hybrid_search.py fuse BM25 and vector ranks via RRF
• src/reranker.py / src/run_reranking.py perform local Cross-Encoder reordering
• src/evidence.py / src/run_evidence.py package results into Evidence Cards

Getting started

• In project root, run:

# 1. Install locked dependencies and create virtualenv
make setup

# 2. Register Jupyter kernel (one-time)
make kernel

# 3. Start JupyterLab
make lab

If make is unavailable, copy the uv run commands from the Makefile sections into the terminal to run them directly.

处置步骤（逐步执行）

# 1. 15 Markdown → ~210 Chunk
make chunk-real

# 2. Build indexes and embeddings
make vector-real

# 3. Evaluate single-path recall
make eval-retrieval

# 4. Hybrid recall with RRF and evaluation
make eval-hybrid

# 5. Rerank with local Cross-Encoder and evaluate
make eval-rerank

# 6. Build Evidence Cards with provenance and ranking history
make build-evidence

Notebook aliases exist, e.g., make run-01, make run-03, make run-06; run-02 to run-07 require kernel registration first.

Recent releases

• none

Traction

• 29 stars, 1 fork, 0 open issues

License

• MIT

Data, models and licensing

• Raw data located in knowledge-base/openai-cookbook with SOURCE.json and license preserved
• Code and notebooks under MIT License at repository root
• First run downloads sentence-transformers paraphrase-m multilingual model and BAAI bge-reranker model to local cache; not included in the repo

Age

• Created: 2026-07-12
• Last push: 2026-07-12