Repolode
Submit
pguso

pguso/rag-from-scratch

A step-by-step educational project that builds Retrieval-Augmented Generation from scratch in JavaScript using local LLMs and no cloud APIs.

View on GitHub
Stars
1,646
Forks
205
Open issues
1
Last commit
7 months ago

What is it?

RAG from Scratch is a learning project that walks developers through building Retrieval-Augmented Generation by hand. Instead of relying on a framework, each stage is implemented in small, commented JavaScript examples: loading and chunking documents, generating embeddings, storing vectors, retrieving context, and feeding that context into a local LLM for grounded answers.

The examples cover the full pipeline in a fixed order, starting with a minimal under-70-line RAG flow and moving on to an in-memory vector store, cosine similarity, and metadata filtering. Later examples add query preprocessing, hybrid keyword and vector search with BM25, multi-query retrieval with reciprocal rank fusion, and query rewriting using either heuristics or a local Qwen model through node-llama-cpp.

The repository also contains a reusable library under src/ with loaders (text, PDF, directory), text splitters, embedding and cache wrappers, vector stores including LanceDB and Qdrant, retrievers, and chains. Several planned topics such as reranking, evaluation metrics, and streaming are listed as upcoming work.

Key features

  • 01Step-by-step examples that build RAG from embeddings to generation
  • 02Local LLM inference via node-llama-cpp with no cloud API required
  • 03In-memory vector store with nearest-neighbor search and metadata filtering
  • 04Hybrid search combining vector similarity and BM25 keyword scoring
  • 05Multi-query retrieval with reciprocal rank fusion and deduplication
  • 06Reusable library with loaders, text splitters, and LanceDB or Qdrant stores

Use cases

  • Learning how retrieval, embeddings, and prompt augmentation fit together
  • Prototyping a document question-answering flow that runs fully offline
  • Comparing retrieval strategies such as vector, keyword, and hybrid search
  • Teaching RAG internals to a team before adopting a larger framework

Things to know

  • The README gives no install or run commands, so setup steps could not be confirmed from it.
  • Several sections are still planned, such as rank results, post-retrieval reranking, and the templates, so parts of the learning path are incomplete.
  • It is an educational walkthrough rather than a production RAG library.

Topics

#rag#embeddings#vector-search#llm#node-llama-cpp#javascript#tutorial#local-llm#agents#ai-agents

FAQ

What is rag-from-scratch?
A step-by-step educational project that builds Retrieval-Augmented Generation from scratch in JavaScript using local LLMs and no cloud APIs. RAG from Scratch is a learning project that walks developers through building Retrieval-Augmented Generation by hand. Instead of relying on a framework, each stage is implemented in small, commented JavaScript examples: loading and chunking documents, generating embeddings, storing vectors, retrieving context, and feeding that context into a local LLM for grounded answers.
Is rag-from-scratch free to use? What license does it have?
rag-from-scratch is open source under the MIT license. Check the license terms before using it in commercial products.
Is rag-from-scratch still maintained?
No commits for 6+ months. The last commit to rag-from-scratch was on Mar 11, 2026.
What can I use rag-from-scratch for?
Learning how retrieval, embeddings, and prompt augmentation fit together Prototyping a document question-answering flow that runs fully offline Comparing retrieval strategies such as vector, keyword, and hybrid search Teaching RAG internals to a team before adopting a larger framework
Where can I get rag-from-scratch?
The source code and installation instructions are on GitHub: https://github.com/pguso/rag-from-scratch

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects