benmaster82/Kwipu

What it solves

Keeping your knowledge in plain files—like Markdown notes or an Obsidian vault—is great for storage but makes it hard to see connections and ask questions like "Who works on Project Alpha?" or "What was decided in the January meeting?". Kwipu turns a folder of documents into a searchable, connected graph where notes become entities, links between them become relations, and every answer comes back with citations to the exact source chunks.

How it works

Kwipu reads .md, .txt, .pdf, and .docx files and builds a property graph — a network where each note is a node and connections between nodes come from two sources:

• Structural relations, extracted automatically from YAML frontmatter (tags, role, project fields) and from [[wikilinks]] (e.g., "Collaborates with [[Bob]]" becomes a "Collaborates with" relation). These relations record their origin: which file, which frontmatter field or line, and a content hash.
• Semantic relations, extracted by an LLM from the text itself (e.g., "Alice specializes in React" gets a "Specializes in" edge). These keep a link to their source chunk so answers can cite them.

The graph and its vectors are persisted to a storage directory. The system watches your source folder: new files cause incremental insertion, while edits or deletions trigger a full rebuild for the batch. Changes are published atomically with a revision manifest, and all components (terminal, bridge, MCP) reload a newly committed generation automatically.

When you ask a question, Kwipu retrieves relevant context using a combination of vector similarity, BM25 keyword search, temporal metadata, and optional synonym retrieval (synonym retrieval is disabled in --fast mode, MCP, and bridge queries). The LLM then crafts an answer grounded in that context, with citations back to the source chunks.

You can interact through three interfaces — all sharing the same knowledge:

• Terminal (Core CLI): asks questions, watches the folder, prints grounded answers directly.
• Web browser: an interactive 3D graph visualization where you click nodes for context cards (frontmatter, links with their originating lines, backlinks, LLM relations, and source chunks) and ask questions in a UI.
• MCP server: exposes query_graph and query_graph_detailed over stdio so AI clients can query the same index.

Who it's for

People who keep notes, meeting minutes, project docs, or research in plain files or Obsidian vaults and want to query them conversationally. Whether you work alone or in a team, Kwipu fits if you want answers with sources rather than raw documents. Terminal-only users need Python and Ollama; the web UI additionally requires Node.js. You can run everything fully locally with local models, or use a cloud LLM if you're comfortable with its data policies.

Highlights

• Turns a folder of notes into a property-graph RAG index — no manual tagging or graph modeling needed.
• Entities are the notes themselves: aliases, renames, and path-qualified names (e.g., People/Alice vs Archive/Alice) all resolve to the same node.
• Answers are always grounded in source chunks and come with citations.
• Terminal-only mode is a complete interface — no browser or Node.js required.
• Interactive 3D web visualization with context cards showing exact line origins for every relation.
• Watches the source folder and updates the index incrementally for new files; rebuilds safely on edits or deletions.
• Fully local option with Ollama (e.g., qwen2.5:7b + nomic-embed-text) or cloud default (gpt-oss:20b-cloud) — the choice is made before indexing, and remote endpoints require HTTPS unless explicitly allowed.
• Supports English, Italian, French, German, Spanish, and Portuguese.
• Exposes the same knowledge through terminal, REST bridge API, and MCP server.