Kwipu: a local Graph RAG index for Obsidian vaults and Markdown folders

The problem Kwipu solves: relationships that plain vector search flattens

A folder of linked notes is not a pile of independent chunks. When one note says a person owns a task and another note records a decision that reassigned it, the answer lives in the edges between files, not in any single passage. Chunk-and-embed pipelines discard that structure: they retrieve the three passages most similar to the question and let the model guess at the connections. Kwipu takes the opposite route. It builds a property graph first, then queries the graph alongside the text.

The audience is narrow and identifiable. Kwipu targets people who keep an Obsidian vault or an ordinary knowledge folder, want answers grounded in citations back to source chunks, and are unwilling to upload the corpus to a hosted retrieval service. The README frames this as "a property-graph RAG index that you can explore and query from an interactive terminal, a 3D web interface, or an MCP client." If your notes are flat prose with no wikilinks and no frontmatter, the graph half of the engine has little to work with, and you are paying the indexing cost for a feature you cannot use.

How the index is built: LLM triples plus structural edges from wikilinks and frontmatter

Kwipu ingests .md, .txt, .pdf and .docx files, and it does not rewrite them. According to the README, relation extraction happens on two tracks. Semantic relations come from an LLM. Structural relations come from wikilinks and YAML frontmatter, which means an Obsidian link like [[Project Alpha]] or a frontmatter field naming an owner becomes a graph edge without any model inference. That second track is the design decision worth noting: it is deterministic, cheap, and reproducible, whereas the LLM track is neither. Splitting the two lets a vault with disciplined linking get a usable graph even when the model's extraction is noisy.

Retrieval is hybrid by design. The README lists vector similarity, BM25, temporal metadata, and optional synonym retrieval as the combined signals. Temporal metadata matters for the meeting-notes and review use cases shown in the repository screenshots, where the question is often about sequence (what changed between two reviews) rather than similarity. Answers are grounded in source chunks and returned with citations. The 3D graph view is a separate surface over the same persisted store, so exploring entities and relations does not require a second index.

Getting it running: virtualenv, requirements file, and two model pulls

The documented path is Windows PowerShell first, with Linux and macOS equivalents referenced elsewhere in the README. Prerequisites are Git, Python 3.12 or later, and Ollama. Node.js and npm are needed only for the web interface; terminal-only users can skip them.

Clone and install:

git clone https://github.com/benmaster82/Kwipu.git Set-Location .\Kwipu py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip==25.1.1 python -m pip install -r .\bridge\requirements.txt npm --prefix .\frontend ci

The README notes that bridge/requirements.txt contains the core terminal dependencies, so one Python environment serves both interfaces. If PowerShell refuses to activate the virtual environment, the documented workaround is Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass followed by the activation command again.

Documents go into knowledge_base, which already ships with a small demo under knowledge_base/examples. Then pull the embedding model and exactly one LLM:

ollama pull nomic-embed-text ollama pull gpt-oss:20b-cloud

or, for the local-only example, ollama pull qwen2.5:7b. The Ollama endpoint defaults to http://localhost:11434, and the README states that Kwipu requires HTTPS for non-loopback endpoints unless insecure HTTP is explicitly enabled for a trusted network.

The cloud default is the sharpest edge in the setup

Kwipu markets itself as fully local, and the README is unusually direct about the caveat. The intentional default LLM is gpt-oss:20b-cloud, which per the README can send document chunks, retrieved context, and questions to its provider. The project's own framing is that a local endpoint does not by itself guarantee local model execution. Both default configurations use a local embedding model, nomic-embed-text, so embeddings stay on the machine while generation may not.

This is a configuration trap rather than a code defect. Someone who reads "fully local" and runs the quick start without reading the model table will index a private vault and route its contents through a cloud model on the first query. The README provides the escape hatch (pull qwen2.5:7b instead, and keep both the endpoint and the models local), but the escape hatch is opt-in. Treat the model choice as the first decision, not a later tuning step.

What the material does not establish

Several things a prospective adopter would want to know are absent from the supplied material. There are no retrieved releases, so there is no changelog to read for breaking changes or migration notes. There is no benchmark, no index-size figure, no statement about how extraction quality varies across the six supported languages (English, Italian, French, German, Spanish, Portuguese), and no guidance on how large a vault can grow before indexing or query latency becomes a problem. The README does not describe what happens when the LLM extracts a contradictory triple, or how conflicts between an LLM-derived edge and a wikilink-derived edge are resolved.

One architectural consequence is visible from the layout alone: the system is split into a bridge (Python, exposing an HTTP API) and a frontend (Node). The README does not mention authentication on the bridge. If you plan to expose it beyond localhost, that gap is worth confirming against the source before you rely on it. The file-watching behaviour is described as updating persisted storage safely, but the material does not specify the consistency model during a rebuild.

Where a plain chunk-and-embed pipeline is the better choice

LlamaIndex is the framework underneath Kwipu, and LlamaIndex on its own can do straightforward vector retrieval over the same document types with far less setup: no graph construction pass, no second model pull for extraction, no bridge process. The difference in approach is what you get back. A vector-only pipeline returns passages ranked by similarity to the question. Kwipu returns passages plus a traversable graph of entities and relations, which is what allows questions of the form "which decisions touched this project between these two dates" to be answered from edges and temporal metadata rather than from whatever text happens to embed close to the query.

The trade is cost and moving parts. Graph construction runs an LLM over your documents, so indexing is slower and, under the cloud default, sends content outward. If your corpus has no link structure and your questions are all of the "find the passage about X" kind, the graph adds an indexing pass and a graph store without changing the answers. A vector index over the same folder is the smaller system, and smaller is correct when the structure is not there.

Licence, maintenance and what adoption actually costs

Kwipu is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with no copyleft obligation on your own code. This is a statement about the licence text, not legal advice; if you are embedding Kwipu in a product, have counsel read the LICENSE file in the repository.

The ongoing cost is mostly model management, not code. You are responsible for keeping Ollama running, for the embedding model staying consistent between indexing and querying (the README names nomic-embed-text as the default), and for re-pulling or pinning whichever LLM you selected. Because there are no published releases, upgrades mean tracking the main branch, and the README's own warning about the cloud default means a configuration file can change your data path after an update. Pin the LLM name explicitly in your configuration rather than relying on the default, and re-read the model table after any pull from main.

Editorial conclusion

Kwipu is worth adopting if your knowledge lives in an Obsidian-style vault where wikilinks and YAML frontmatter already encode relationships, and you want queries over that structure without sending notes to a hosted index. It is the wrong tool if your documents are unstructured prose with no link graph, or if you need a shared multi-user service: the material describes a single-machine setup with no authentication layer for the bridge API. Before indexing anything private, verify which LLM you pulled, because the documented default is gpt-oss:20b-cloud, and confirm the Ollama endpoint in your configuration is loopback rather than a remote host.

Official sources

1. benmaster82/Kwipu on GitHub
2. Issues
3. License: MIT
4. README