Retrieval quality is treated as something you check rather than hope for: evaluate_retrieval turns "is the search any good" into a pass or fail over query and expected-file pairs, and get_index_stats reports the cache hit rate and whether the embedding model actually loaded. The write path carries as much weight as the read one — a page can be pulled in from a URL as markdown, and a forced reindex picks up edits made outside the tools. If more than one person needs the same corpus, the same server runs over HTTP with a bearer token instead of one process per client.
A retrieval server over a documents folder on your own machine. Embeddings, the BM25 index and the cross-encoder reranker all run in-process, so nothing is sent to a cloud API after the first model download.
- Retrieval tunable per call: hybrid_alpha weights semantic against keyword, with search_method, min_score, snippet_mode, a result cap and a category filter alongside it
- 35 file formats parsed with chunking that respects the format — markdown splits at headers, code at function and class boundaries, notebooks skip their outputs, PDFs go through PyMuPDF
- Two ways in: add_document writes text you pass, add_from_url fetches a page, strips the HTML and converts it to markdown before indexing
- Reindexing with three modes that mean different things — force for changed files plus a BM25 rebuild, full_rebuild for a delete-and-re-embed, resume to pick up an interrupted run — running in the background with a progress poll
- Similarity by document rather than by query: search_similar takes a filepath and returns neighbours from that document's own embedding
- A retrieval test harness: evaluate_retrieval runs query and expected-file pairs and reports whether each expected document lands in the top results
- Index health in one call — document and chunk totals, embedding model name, BM25 status, query cache hit rate and file watcher status
- An HTTP mode for teams: SSE or streamable-http on port 8179 with a bearer token, sliding-window rate limiting, a /health probe and Prometheus metrics on 9179
Python 3.11 or newer and a documents folder on the same machine; knowledge-rag init scaffolds that folder and a config.yaml next to it. The first query downloads the ONNX embedding model once (about 200MB) and everything after that works offline — set HF_HUB_OFFLINE=1 to enforce it. No account and no key. Categories come from the folder layout rather than a fixed list, and five presets ship for common corpora: cybersecurity, developer, research, multilingual and general. Removing a document with delete_file set deletes the file from disk irreversibly. MIT.
One command — pip install knowledge-rag