Kwipu is a local Graph RAG engine designed to transform Markdown notes into a queryable knowledge graph. It addresses the need for private, natural language querying across personal knowledge bases, benefiting Obsidian users and anyone managing notes in Markdown folders. The system offers a fully local, multilingual solution without cloud reliance.

How It Works

Kwipu employs a property graph approach, extracting entity-relation triples from Markdown files. It parses Obsidian's [[wikilinks]] and YAML frontmatter, supplemented by LLM extraction for richer relationships. This structured data forms a knowledge graph index. Queries are processed via a hybrid retrieval system combining LLM synonym expansion, vector similarity search, BM25 keyword scoring, and temporal/metadata matching, before a final LLM response generation.

Quick Start & Requirements

• Install: pip install -r requirements.txt
• Prerequisites: Python 3.11+, Ollama running locally, an LLM model (e.g., llama3.1:8b), and an embedding model (default: nomic-embed-text).
• Setup: Requires pulling models via Ollama (ollama pull <model_name>).
• Docs: Project repository: https://github.com/benmaster82/Kwipu

Highlighted Details

• MCP Server: Integrates with AI agents (Claude Desktop, Cursor, Windsurf) via the Messaging Conversation Protocol (MCP), enabling agents to query the local graph.
• Incremental Updates: Edits to notes are updated in-place within seconds, avoiding full graph rebuilds for modified files.
• Multilingual: Supports English, Italian, French, German, Spanish, and Portuguese, with auto-detection.
• Hybrid Retrieval: Leverages four strategies (Synonym, Vector, BM25, Temporal) for comprehensive context retrieval.
• Fully Local: All processing, including LLM inference, occurs locally via Ollama, ensuring data privacy.

Maintenance & Community

Contributions are welcomed, with specific areas identified for improvement: CJK language support, retriever attribution logging, evaluation set creation, provenance inspector development, Telegram bot integration, and optimizing incremental updates for file modifications. A roadmap includes a Telegram bot for remote querying.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license is permissive, allowing for commercial use and integration into closed-source applications.

Limitations & Caveats

CPU-only inference for larger LLM models (7B+) is noted as "not practical" due to speed. While incremental updates are supported for edits, file deletion triggers a full graph rebuild. CJK language support requires further development.