Kwipu

English | 简体中文 | Tiếng Việt

Kwipu turns a folder of documents into a property-graph RAG index that you can explore and query from an interactive terminal, a 3D web interface, or an MCP client. It works with ordinary knowledge folders and Obsidian-style vaults.

About “fully local”: Kwipu can run fully locally when you select a local Ollama LLM and embedding model. The intentional default LLM is gpt-oss:20b-cloud, which can send document chunks, retrieved context, and questions to its provider. Choose cloud or local before indexing.

Choose your path

What Kwipu does

• Builds a property graph from .md, .txt, .pdf, and .docx documents.
• Extracts semantic relations with an LLM and structural relations from wikilinks and YAML frontmatter.
• Combines vector similarity, BM25, temporal metadata, and optional synonym retrieval.
• Grounds answers in source chunks and returns citations.
• Visualizes entities, documents, and relations in an interactive 3D graph.
• Watches the source folder and updates persisted storage safely.
• Supports English, Italian, French, German, Spanish, and Portuguese patterns.
• Exposes the same knowledge through the terminal, web API, and MCP.

Web interface

1. Ask a grounded question and open its sources

2. Reconstruct changes across meetings and reviews

3. Compare people, roles, and supporting documents

Terminal interface

Use Kwipu directly from the command line while keeping your notes open in Obsidian. The terminal returns grounded answers from the graph and continues watching the knowledge folder for changes.

Ask about roles, tasks, and project context

Query meeting decisions and rebuild after note changes

For installation and commands, see Terminal-only use.

Choose cloud or local

Kwipu connects to an Ollama-compatible endpoint, which defaults to http://localhost:11434. A local endpoint does not by itself guarantee local model execution.

Both modes use the local embedding model in the default configuration:

ollama pull nomic-embed-text

A remote Ollama endpoint sends data to that host. Kwipu requires HTTPS for non-loopback endpoints unless insecure HTTP is explicitly enabled for a trusted network.

Quick start: web UI

The guided setup below targets Windows PowerShell. Linux and macOS equivalents follow it. If you only want the terminal interface, follow steps 1–6 and stop before starting the bridge and frontend.

1. Install and verify the prerequisites

Install:

• Git or download the repository as a ZIP.
• Python 3.12 or later.
• Ollama.
• Node.js with npm only if you want the web interface.

Open PowerShell and verify the commands you need:

git --version
py -3.12 --version
ollama --version
node --version
npm --version

If one command is not found, install that prerequisite, open a new PowerShell window, and run the check again. Terminal-only users do not need Node.js or npm.

2. Download Kwipu and install its runtime

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

# Web interface only:
npm --prefix .\frontend ci

bridge/requirements.txt includes the core terminal dependencies, so one Python installation supports both interfaces. If you downloaded a ZIP, extract it and run the commands after git clone from the extracted Kwipu folder.

If PowerShell blocks virtual-environment activation, use this process-only policy and retry:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

3. Add documents

The repository already includes a small demo under knowledge_base/examples. To use your own files, copy .md, .txt, .pdf, or .docx files into knowledge_base before starting the indexer.

Kwipu/
└── knowledge_base/
    ├── examples/
    └── your-notes/
        ├── project.md
        └── meeting-notes.pdf

Kwipu reads source documents but does not rewrite them.

4. Make the models available

Make sure Ollama is running. The Ollama desktop application may already run the service; otherwise keep this command open in Terminal 1:

ollama serve

In another PowerShell window, pull the embedding model and exactly one LLM:

ollama pull nomic-embed-text

# Cloud default:
ollama pull gpt-oss:20b-cloud

# OR local-only example:
# ollama pull qwen2.5:7b

A cloud model may ask you to complete Ollama account or sign-in steps. Do not index sensitive documents until you have selected the intended execution mode.

5. Use one consistent configuration

Settings are read when each process starts. PowerShell $env: values apply only to the current window, so paste the following block into both the indexer terminal and the bridge terminal.

Set-Location "C:\path\to\Kwipu" # replace with your actual folder
.\.venv\Scripts\Activate.ps1

$env:KWIPU_ROOT_DIR = (Get-Location).Path
$env:KWIPU_KNOWLEDGE_DIR = "knowledge_base"
$env:KWIPU_STORAGE_DIR = "storage_graph"
$env:KWIPU_EMBED_MODEL = "nomic-embed-text"
$env:KWIPU_OLLAMA_BASE_URL = "http://localhost:11434"
$env:KWIPU_QUERY_MAX_LENGTH = "4000"

# Run exactly one of these two lines:
$env:KWIPU_LLM_MODEL = "gpt-oss:20b-cloud" # cloud default
# $env:KWIPU_LLM_MODEL = "qwen2.5:7b"       # local example

If you choose the local model, comment out the cloud line and uncomment the local line in both terminals.

For a shared terminal/web setup, prefer environment variables over geode_graph.py --llm-model. CLI flags configure only that terminal process; they do not configure the bridge.

6. Start the indexer and terminal interface — Terminal 2

After applying the configuration block:

python .\geode_graph.py --fast

Keep this process running. On first use, wait for:

Graph built and saved successfully.

When existing storage is reused, the equivalent message is:

Graph loaded successfully.

The process then displays:

Type your question, or 'exit' to quit.
>

You can already use Kwipu entirely from this terminal: type a question after >, press Enter, read the grounded answer, and enter exit when finished. For example:

> Who works on Project Alpha, and what are their roles?

If you only need the terminal interface, setup is complete: you do not need the bridge, Node.js, or frontend. Keep the terminal open if you want Kwipu to watch the document folder for changes.

If the indexer prints No files found. Waiting for documents..., confirm that your files are under the configured KWIPU_KNOWLEDGE_DIR.

7. Start the API bridge — Terminal 3

To use the browser UI, open another PowerShell window, paste the same configuration block from step 5, then run:

$env:BRIDGE_HOST = "127.0.0.1"
$env:BRIDGE_PORT = "8765"
python -m bridge

Keep the bridge running. A successful startup includes:

Uvicorn running on http://127.0.0.1:8765

8. Check health and start the frontend — Terminal 4

From the repository root:

$health = Invoke-RestMethod -Uri "http://127.0.0.1:8765/health"
$health | ConvertTo-Json -Depth 6

Before continuing, check that the top-level status, property_graph.status, and ollama.status are all ok. Then start the UI:

npm --prefix .\frontend run dev

Open http://localhost:5173 in your b