WHAT IS IT?
Kwipu turns a folder of documents into a property-graph RAG index that you query from a terminal, a 3D web interface or an MCP client. It ingests .md, .txt, .pdf and .docx files, pulls semantic relations out of the text with an LLM, and reads structural relations from wikilinks and YAML frontmatter. Every answer comes back with citations and the matching source chunk.
WHY IS IT INTERESTING?
- Two sources of truth for the graph: the LLM extracts entity-relation triples from the text, while wikilinks and frontmatter supply the links you already wrote by hand. The graph does not rest solely on what the model happened to infer.
- Hybrid retrieval: vector similarity, BM25, temporal metadata and a per-query synonym retriever. The
--fastmode drops that last one, as do the MCP server and the bridge API. - Three interfaces over one index: an interactive CLI that watches the source folder, a versioned JSON API on FastAPI, and an MCP server exposing
query_graphandquery_graph_detailed. - Careful storage model: the CLI is the sole writer, and the read-only bridge returns 503 until usable storage has been published. Writes go through a staging generation published atomically, with an inter-process lock and the previous generation kept as a temporary backup.
- Local, but on your terms: the default LLM is
gpt-oss:20b-cloud, which forwards chunks to the model provider. The README spells out how to switch to a local Ollama model before the first index build, and HTTPS is required for any non-loopback endpoint. - Cited sources you can open: the
/expandendpoint reads the document behind a cited node, PDF and DOCX text extraction included, without another LLM call.
USE CASES
- Query an Obsidian vault in plain language while keeping your notes open in the editor
- Rebuild a project timeline out of meeting notes scattered across many files
- Wire an MCP client into your own notes so the agent answers by citing the original files
- Walk the links between entities and documents visually in the 3D graph frontend