canwhite/microrag

MicroRAG is a minimal working example of a Retrieval-Augmented Generation system, written entirely in plain Python without any AI or machine learning libraries. RAG is an approach where an AI first searches a knowledge base to find relevant information, then uses that information to generate an answer. This project builds both halves from scratch to show how the technique works at a low level. The retriever half converts questions and stored documents into 32-dimensional numerical vectors using a small embedding matrix, then finds the closest match by cosine similarity. It is trained using a technique called contrastive learning, where matching question-document pairs are pushed together and non-matching pairs are pushed apart. The generator half is a single-layer self-attention transformer that takes a question combined with the retrieved document text and produces a character-by-character response. All the gradient mathematics that normally come from a library like PyTorch are implemented by hand using only Python's standard library. The project includes a complete training and inference pipeline that you can run with a single command. In the example output shown in the README, the system correctly retrieves a relevant document about the sun and then generates an answer stating the surface temperature and core temperature. The README explicitly describes the scope limitations: the knowledge base contains only 8 fixed question-answer pairs, the tokenizer works at the character level with a vocabulary of around 60 symbols, the transformer has just one layer, and the maximum text length is 64 characters before position encodings wrap. This is described as a learning and demonstration project, not a production system. It is suited for someone who wants to understand how retrieval and generation fit together without the abstraction of a full-sized framework.