Top AI Repos — open-source AI, indexed and scored

Top AI Repos tracks AI repositories on GitHub and answers two different questions about each one: is it moving right now, and would you bet a product on it.

benmaster82/Kwipu

Ask questions across your Markdown notes using a fully local Graph RAG engine. Built for Obsidian vaults, works with any folder of Markdown files. Extracts entity-relation triples from wikilinks & YAML frontmatter, retrieves answers via hybrid search (vector + BM25 + temporal). Multilingual. No cloud. Runs on Ollama.

69MITPython

View on GitHub

Stars: 609
Forks: 60
Watchers: 1
Open issues: 1
Contributors: 2

Star history, last 90 days+344 over 21 snapshots

2026-07-31 · 2652026-09-20 · 609

Star history, last 90 days
Date	Stars
2026-07-31	265
2026-08-01	266
2026-08-06	266
2026-08-07	266
2026-08-14	266
2026-08-15	266
2026-08-18	266
2026-08-20	267
2026-09-01	266
2026-09-06	267
2026-09-07	268
2026-09-08	475
2026-09-09	553
2026-09-10	585
2026-09-11	595
2026-09-12	601
2026-09-13	605
2026-09-15	606
2026-09-16	607
2026-09-18	609
2026-09-20	609

Today

— stars today

This week

+4 stars this week

This month

+342 stars this month

Momentum

4.0

growth rate 0.66%/day

From the README

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

I want to…	Start here
Ask my notes directly in a terminal	Terminal-only use
Explore the graph and ask from a browser	Quick start: web UI
Use my own notes or Obsidian vault	Use your own document folder
Connect an AI client over MCP	MCP server
Configure or deploy the system	Configuration reference
Run tests or contribute code	Developer setup

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.

Mode	LLM	Data behavior	Before first use
Cloud default	`gpt-oss:20b-cloud`	Ollama can forward context and questions to the model provider. Review that provider's privacy, retention, and data-location policies.	`ollama pull gpt-oss:20b-cloud`
Local example	`qwen2.5:7b`	Inference remains on the machine when both models and the Ollama endpoint are local.	`ollama pull qwen2.5:7b`

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 browser. Try this question with the included demo documents:

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

Use Ctrl+C in each terminal to stop its process. A normal web session keeps four processes running: Ollama (unless its desktop service is already running), the Kwipu indexer/terminal, the bridge, and Vite.

Terminal-only use

The terminal is a complete Kwipu interface, not only a background indexer. It builds or loads the graph, watches documents, accepts questions, and prints answers directly. It needs Python and Ollama, but it does not need FastAPI, Node.js, or a browser.

After completing the common model and configuration steps above, run:

.\.venv\Scripts\Activate.ps1
python .\geode_graph.py --fast

Then ask questions at the prompt:

> What decisions were made in the January 15 meeting?
> How did Project Alpha change between the two meetings?
> Who is responsible for the API deployment?

Commands and behavior:

Enter a question and press Enter to query the graph.
Enter exit, quit, or esci to close Kwipu.
Press Ctrl+C to stop it.
Leave it running to detect newly created, modified, or deleted documents.
Omit --fast to enable the additional LLM synonym retriever for terminal queries.

For a terminal-only installation, python -m pip install -r .\requirements.txt is sufficient. The broader bridge requirements used in the web quick start also include these core dependencies.

Linux and macOS command equivalents

The process order is the same: Ollama → indexer/terminal → bridge → frontend. Replace the Windows setup and environment syntax with:

git clone https://github.com/benmaster82/Kwipu.git
cd Kwipu

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip==25.1.1
python -m pip install -r bridge/requirements.txt
npm --prefix frontend ci # web interface only

export KWIPU_ROOT_DIR="$PWD"
export KWIPU_KNOWLEDGE_DIR="knowledge_base"
export KWIPU_STORAGE_DIR="storage_graph"
export KWIPU_EMBED_MODEL="nomic-embed-text"
export KWIPU_OLLAMA_BASE_URL="http://localhost:11434"
export KWIPU_QUERY_MAX_LENGTH="4000"
export KWIPU_LLM_MODEL="gpt-oss:20b-cloud" # or qwen2.5:7b

Repeat the export block in the indexer and bridge shells, then use only the processes you need:

# Complete terminal interface and watcher
python geode_graph.py --fast

# Web API, in another shell
python -m bridge

# Web frontend, in another shell
npm --prefix frontend run dev

Install and start Ollama using the instructions for your operating system. On macOS, the Ollama application can provide the service without a separate ollama serve terminal.

Use your own document folder

You may keep notes outside the repository. Use an absolute source path and a separate generated-storage path, and repeat the same values for the terminal/indexer, bridge, and MCP server:

$env:KWIPU_ROOT_DIR = "D:\KwipuData"
$env:KWIPU_KNOWLEDGE_DIR = "D:\Notes\MyVault"
$env:KWIPU_STORAGE_DIR = "graph-index"
$env:KWIPU_LLM_MODEL = "qwen2.5:7b"
$env:KWIPU_EMBED_MODEL = "nomic-embed-text"
python .\geode_graph.py --fast

Relative knowledge and storage paths resolve under KWIPU_ROOT_DIR. The source directory and generated storage must be separate; Kwipu rejects nested or overlapping layouts to protect source documents.

Document updates

Filesystem change	Index action
Initial startup without storage	Full build
Only newly created files	Incremental insertion
Any modified file	One full rebuild for the batch
Any deleted file	One full rebuild for the batch
Event without a content-hash change	Ignored

An editor's atomic save can appear as delete plus create and therefore trigger a full rebuild. Run one core CLI watcher for each storage directory.

Core CLI reference

Fast mode disables the per-query LLM synonym retriever:

python .\geode_graph.py --fast

CLI-only model overrides are available for standalone use:

python .\geode_graph.py --llm-model qwen2.5:7b --embed-model nomic-embed-text

These flags do not propagate to the bridge or MCP server. Use environment variables when multiple components share the same storage.

How it works

Documents (.md/.txt/.pdf/.docx)
        │
        ▼
Structural preprocessing (wikilinks/frontmatter) + LLM path extraction
        │
        ▼
Persisted property graph and vectors (shared storage + revision manifest)
        │
        ▼
Synonym* + vector + BM25 + temporal retrieval
        │
        ▼
LLM answer with source context and citations

* Synonym retrieval is disabled in --fast mode, MCP, and bridge queries.

Components

Core CLI builds and queries the graph, then watches the knowledge directory.
MCP server exposes query_graph and query_graph_detailed over MCP stdio.
Bridge exposes versioned JSON APIs for health, graph snapshots, read-only queries, and source expansion.
Frontend renders the graph with 3d-force-graph and calls the bridge through a configurable API base.

Storage and process model

The CLI is the designated writer. The bridge is read-only and returns HTTP 503 until the CLI has published usable storage. MCP can build storage when it is absent, but it does not start a watcher.

All components use a shared inter-process lock and revision manifest. Queries compare storage_revision and reload a newly committed generation automatically. Persist operations prepare a sibling staging generation, retain the previous generation temporarily as backup, and atomically publish the new generation.

Do not run multiple watchers against one storage directory. Do not delete storage_graph, .storage_graph.staging, .storage_graph.backup, or the sibling lock while a process is using them.

Configuration reference

Settings are read from environment variables when each process starts. Restart the affected process after changing a value.

Core configuration

Variable	Default	Meaning
`KWIPU_ROOT_DIR`	Repository directory	Base for default and relative data paths.
`KWIPU_LIVE_DIR`	—	Compatibility alias for `KWIPU_ROOT_DIR`; `KWIPU_ROOT_DIR` wins.
`KWIPU_KNOWLEDGE_DIR`	`knowledge_base` under root	Source document directory.
`KWIPU_STORAGE_DIR`	`storage_graph` under root	Generated persisted index directory.
`KWIPU_LLM_MODEL`	`gpt-oss:20b-cloud`	LLM used for extraction and answers; the default can execute in the cloud.
`KWIPU_MODEL_NAME`	—	Compatibility alias for `KWIPU_LLM_MODEL`; the latter wins.
`KWIPU_EMBED_MODEL`	`nomic-embed-text`	Embedding model used for stored vectors.
`KWIPU_OLLAMA_BASE_URL`	`http://localhost:11434`	Absolute HTTP(S) Ollama endpoint.
`KWIPU_OLLAMA_TIMEOUT`	`300` seconds	Positive model-request timeout.
`KWIPU_STORAGE_LOCK_TIMEOUT`	`30` seconds	Positive wait limit for the shared storage lock.
`KWIPU_QUERY_MAX_LENGTH`	`4000` characters	Maximum normalized question length.
`KWIPU_MAX_SOURCE_BYTES`	`10485760` bytes	Maximum source-file and extracted-text size for bridge expansion.
`KWIPU_ALLOW_INSECURE_REMOTE_OLLAMA`	disabled	Allows plaintext HTTP to a non-loopback host when set to `1`, `true`, `yes`, or `on`.

Changing the embedding model requires a new storage index. Changing only the LLM permits loading existing vectors, although a later full rebuild can produce different extracted relations.

Bridge configuration

Variable	Default	Meaning
`BRIDGE_HOST`	`127.0.0.1`	Bind address used by `python -m bridge`.
`BRIDGE_PORT`	`8765`	Validated port from 1 through 65535.
`BRIDGE_CORS_ORIGINS`	`http://127.0.0.1:5173,http://localhost:5173`	Comma-separated browser origins; wildcards are rejected.
`BRIDGE_ALLOWED_HOSTS`	`localhost,127.0.0.1,testserver`	Accepted `Host` values; wildcards are rejected.
`BRIDGE_HEALTH_OLLAMA_TIMEOUT`	`2` seconds	Ollama timeout used by `/health`.

The bridge also uses every core setting above. python -m bridge consumes BRIDGE_HOST and BRIDGE_PORT; when invoking Uvicorn directly, pass them as CLI values:

uvicorn bridge.app:app --reload --host $env:BRIDGE_HOST --port $env:BRIDGE_PORT

See bridge/README.md for API contracts and deployment notes.

Frontend configuration

Variable	Default	Meaning
`VITE_API_BASE`	`/api`	Browser API base; relative values use the Vite proxy.
`VITE_BRIDGE_TARGET`	`http://127.0.0.1:8765`	Development proxy target.

With the defaults, Vite rewrites /api/health to /health on the bridge. A production static deployment must provide an equivalent reverse proxy or use an absolute VITE_API_BASE; direct browser access must also match BRIDGE_CORS_ORIGINS.

MCP server

Use an absolute Python interpreter and script path in the MCP client configuration. Environment variables configure the model and paths because CLI flags apply only to geode_graph.py.

{
  "mcpServers": {
    "kwipu": {
      "command": "C:/path/to/Kwipu/.venv/Scripts/python.exe",
      "args": ["C:/path/to/Kwipu/kwipu_mcp_server.py"],
      "env": {
        "KWIPU_KNOWLEDGE_DIR": "C:/path/to/vault",
        "KWIPU_LLM_MODEL": "qwen2.5:7b",
        "KWIPU_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

The MCP server runs in fast retrieval mode and starts no watcher. It exposes:

query_graph(question) — returns the answer as text.
query_graph_detailed(question) — returns {"answer": "...", "citations": [...]} with citations deduplicated by node ID.

Selecting gpt-oss:20b-cloud carries the cloud privacy implications described above. Use installed local models when local-only execution is required.

Bridge API and source expansion

The main bridge endpoints are:

Endpoint	Purpose
`GET /health`	Check storage, configured models, and Ollama connectivity.
`GET /graph/snapshot`	Return the graph used by the 3D interface.
`POST /query`	Ask a question and receive an answer plus citations.
`GET /expand?node_id=<opaque-id>`	Read the cited source represented by a graph node.

Source expansion reads UTF-8 Markdown/text directly and extracts PDF/DOCX text without invoking an LLM. Oversized input returns 413; unsupported formats return 415; invalid UTF-8 or failed structured extraction returns 422; transient source I/O returns 503.

Troubleshooting

Symptom	What to check
`python`, `ollama`, `node`, or `npm` is not recognized	Install the missing prerequisite, open a new terminal, and run its `--version` command.
`Activate.ps1` is blocked	Run `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`, then activate the environment again.
`Ollama is not running`	Start the Ollama application or run `ollama serve`; verify `http://localhost:11434/api/tags`.
`Missing model(s)`	Run the exact `ollama pull <model>` commands printed by Kwipu. Make sure indexer and bridge use the same model names.
`No files found. Waiting for documents...`	Put supported files under `KWIPU_KNOWLEDGE_DIR` and confirm the path printed in the CLI header.
Browser does not open	Keep Vite running and open `http://localhost:5173` manually.
Health is `degraded`	Inspect `property_graph.detail`, `ollama.detail`, and the `models` list in `/health`.
Query returns `503`	Start the CLI/indexer first and wait for a successful graph build/load. Also check storage path, lock, and embedding compatibility.
Query returns `502`	Check bridge logs and Ollama availability; the query engine or model request failed. Retrying should not be used to hide a persistent error.
Query returns `400 Question is too long`	The backend reports the active limit. The default is `4000`; a different value, such as `99`, means `KWIPU_QUERY_MAX_LENGTH` was overridden. Set it before starting the bridge and restart the bridge.
Port `8765` or `5173` is already in use	Stop the existing process or change the bridge/Vite settings consistently.
Embedding-model mismatch	Stop all Kwipu processes, restore the model used to build storage, or move the generated storage aside and let the CLI rebuild it. Never remove your source document directory.

Inspect a PowerShell override with:

Get-ChildItem Env:KWIPU_QUERY_MAX_LENGTH

Set the documented default for the current terminal and restart the bridge with:

$env:KWIPU_QUERY_MAX_LENGTH = "4000"
python -m bridge

Project structure

Kwipu/
├── geode_graph.py                # Core engine, interactive CLI, and watcher
├── kwipu_config.py               # Canonical environment configuration
├── kwipu_storage.py              # Inter-process lock and atomic JSON helpers
├── kwipu_mcp_server.py           # MCP stdio server
├── lang_config.py                # Multilingual patterns and date/relation helpers
├── requirements.txt              # Core/terminal and MCP dependencies
├── requirements-dev.txt          # Bridge/runtime/test dependency inputs
├── requirements-dev.lock         # Hashed Python 3.12 Linux CI lock
├── requirements-dev-windows.lock # Hashed Python 3.12 Windows CI lock
├── bridge/                       # FastAPI app and read-only query adapter
├── frontend/                     # TypeScript/Vite 3D client
├── knowledge_base/examples/      # Example source documents
├── img/                          # Logo and screenshots
├── tests/                        # Standard-library unittest suite
└── storage_graph/                # Generated active index, gitignored

Generated staging and backup siblings are also gitignored and managed automatically.

Developer setup

Use the platform-specific hashed lock for the complete bridge/runtime/test environment.

Windows, Python 3.12

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip==25.1.1
python -m pip install --require-hashes -r .\requirements-dev-windows.lock
python -m unittest discover -s tests -p "test_*.py" -v

Linux CI environment, Python 3.12

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip==25.1.1
python -m pip install --require-hashes -r requirements-dev.lock
python -m unittest discover -s tests -p "test_*.py" -v

Frontend validation commands are:

npm --prefix .\frontend ci
npm --prefix .\frontend run typecheck
npm --prefix .\frontend run build
npm --prefix .\frontend audit

Regenerate dependency locks only from requirements-dev.txt with the pinned workflow documented in CONTRIBUTING.md, then review the complete diff. See that guide for all contribution and validation requirements.

License

MIT

Rendered by GitHub from the current README

Read on GitHub

Top contributors2 shown

benmaster82
23
dhruval30
1

Quality score

Would you bet a product on this? Bounded 0–100 and slow moving.

69/10069

Maintenance: 90%; How recently the default branch was pushed to
Releases: 25%; Recency and cadence of tagged releases
Community: 9%; Contributor breadth and bus factor
Issue backlog: 100%; Open issues measured against the size of the audience
Documentation: 99%; README depth, plus a homepage and topics
Licensing: 100%; How freely the code can be adopted

What to know before adopting

No tagged releases
Bus factor of 1 — one contributor dominates
Usable in commercial products with attribution.

Details

Created: 5 months ago
Last push: 13 days ago
Last release: none
Release tag: —
Releases in the last year: 0
Default branch: main
Size: 1.1k KB
Owner type: User
Owner location: Modena
Discovered via: phrase:ollama
First indexed: 2 months ago
Last synced: 5 days ago

benmaster82/Kwipu

69MITPython

View on GitHub

Stars: 609
Forks: 60
Watchers: 1
Open issues: 1
Contributors: 2

Star history, last 90 days+344 over 21 snapshots

2026-07-31 · 2652026-09-20 · 609

Star history, last 90 days
Date	Stars
2026-07-31	265
2026-08-01	266
2026-08-06	266
2026-08-07	266
2026-08-14	266
2026-08-15	266
2026-08-18	266
2026-08-20	267
2026-09-01	266
2026-09-06	267
2026-09-07	268
2026-09-08	475
2026-09-09	553
2026-09-10	585
2026-09-11	595
2026-09-12	601
2026-09-13	605
2026-09-15	606
2026-09-16	607
2026-09-18	609
2026-09-20	609

Today

— stars today

This week

+4 stars this week

This month

+342 stars this month

Momentum

4.0

growth rate 0.66%/day

From the README

Kwipu

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

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

I want to…	Start here
Ask my notes directly in a terminal	Terminal-only use
Explore the graph and ask from a browser	Quick start: web UI
Use my own notes or Obsidian vault	Use your own document folder
Connect an AI client over MCP	MCP server
Configure or deploy the system	Configuration reference
Run tests or contribute code	Developer setup

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.

Mode	LLM	Data behavior	Before first use
Cloud default	`gpt-oss:20b-cloud`	Ollama can forward context and questions to the model provider. Review that provider's privacy, retention, and data-location policies.	`ollama pull gpt-oss:20b-cloud`
Local example	`qwen2.5:7b`	Inference remains on the machine when both models and the Ollama endpoint are local.	`ollama pull qwen2.5:7b`

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

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 browser. Try this question with the included demo documents:

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

Terminal-only use

After completing the common model and configuration steps above, run:

.\.venv\Scripts\Activate.ps1
python .\geode_graph.py --fast

Then ask questions at the prompt:

> What decisions were made in the January 15 meeting?
> How did Project Alpha change between the two meetings?
> Who is responsible for the API deployment?

Commands and behavior:

Enter a question and press Enter to query the graph.
Enter exit, quit, or esci to close Kwipu.
Press Ctrl+C to stop it.
Leave it running to detect newly created, modified, or deleted documents.
Omit --fast to enable the additional LLM synonym retriever for terminal queries.

For a terminal-only installation, python -m pip install -r .\requirements.txt is sufficient. The broader bridge requirements used in the web quick start also include these core dependencies.

Linux and macOS command equivalents

The process order is the same: Ollama → indexer/terminal → bridge → frontend. Replace the Windows setup and environment syntax with:

git clone https://github.com/benmaster82/Kwipu.git
cd Kwipu

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip==25.1.1
python -m pip install -r bridge/requirements.txt
npm --prefix frontend ci # web interface only

export KWIPU_ROOT_DIR="$PWD"
export KWIPU_KNOWLEDGE_DIR="knowledge_base"
export KWIPU_STORAGE_DIR="storage_graph"
export KWIPU_EMBED_MODEL="nomic-embed-text"
export KWIPU_OLLAMA_BASE_URL="http://localhost:11434"
export KWIPU_QUERY_MAX_LENGTH="4000"
export KWIPU_LLM_MODEL="gpt-oss:20b-cloud" # or qwen2.5:7b

Repeat the export block in the indexer and bridge shells, then use only the processes you need:

# Complete terminal interface and watcher
python geode_graph.py --fast

# Web API, in another shell
python -m bridge

# Web frontend, in another shell
npm --prefix frontend run dev

Install and start Ollama using the instructions for your operating system. On macOS, the Ollama application can provide the service without a separate ollama serve terminal.

Use your own document folder

You may keep notes outside the repository. Use an absolute source path and a separate generated-storage path, and repeat the same values for the terminal/indexer, bridge, and MCP server:

$env:KWIPU_ROOT_DIR = "D:\KwipuData"
$env:KWIPU_KNOWLEDGE_DIR = "D:\Notes\MyVault"
$env:KWIPU_STORAGE_DIR = "graph-index"
$env:KWIPU_LLM_MODEL = "qwen2.5:7b"
$env:KWIPU_EMBED_MODEL = "nomic-embed-text"
python .\geode_graph.py --fast

Document updates

Filesystem change	Index action
Initial startup without storage	Full build
Only newly created files	Incremental insertion
Any modified file	One full rebuild for the batch
Any deleted file	One full rebuild for the batch
Event without a content-hash change	Ignored

An editor's atomic save can appear as delete plus create and therefore trigger a full rebuild. Run one core CLI watcher for each storage directory.

Core CLI reference

Fast mode disables the per-query LLM synonym retriever:

python .\geode_graph.py --fast

CLI-only model overrides are available for standalone use:

python .\geode_graph.py --llm-model qwen2.5:7b --embed-model nomic-embed-text

These flags do not propagate to the bridge or MCP server. Use environment variables when multiple components share the same storage.

How it works

Documents (.md/.txt/.pdf/.docx)
        │
        ▼
Structural preprocessing (wikilinks/frontmatter) + LLM path extraction
        │
        ▼
Persisted property graph and vectors (shared storage + revision manifest)
        │
        ▼
Synonym* + vector + BM25 + temporal retrieval
        │
        ▼
LLM answer with source context and citations

* Synonym retrieval is disabled in --fast mode, MCP, and bridge queries.

Components

Core CLI builds and queries the graph, then watches the knowledge directory.
MCP server exposes query_graph and query_graph_detailed over MCP stdio.
Bridge exposes versioned JSON APIs for health, graph snapshots, read-only queries, and source expansion.
Frontend renders the graph with 3d-force-graph and calls the bridge through a configurable API base.

Storage and process model

The CLI is the designated writer. The bridge is read-only and returns HTTP 503 until the CLI has published usable storage. MCP can build storage when it is absent, but it does not start a watcher.

Do not run multiple watchers against one storage directory. Do not delete storage_graph, .storage_graph.staging, .storage_graph.backup, or the sibling lock while a process is using them.

Configuration reference

Settings are read from environment variables when each process starts. Restart the affected process after changing a value.

Core configuration

Variable	Default	Meaning
`KWIPU_ROOT_DIR`	Repository directory	Base for default and relative data paths.
`KWIPU_LIVE_DIR`	—	Compatibility alias for `KWIPU_ROOT_DIR`; `KWIPU_ROOT_DIR` wins.
`KWIPU_KNOWLEDGE_DIR`	`knowledge_base` under root	Source document directory.
`KWIPU_STORAGE_DIR`	`storage_graph` under root	Generated persisted index directory.
`KWIPU_LLM_MODEL`	`gpt-oss:20b-cloud`	LLM used for extraction and answers; the default can execute in the cloud.
`KWIPU_MODEL_NAME`	—	Compatibility alias for `KWIPU_LLM_MODEL`; the latter wins.
`KWIPU_EMBED_MODEL`	`nomic-embed-text`	Embedding model used for stored vectors.
`KWIPU_OLLAMA_BASE_URL`	`http://localhost:11434`	Absolute HTTP(S) Ollama endpoint.
`KWIPU_OLLAMA_TIMEOUT`	`300` seconds	Positive model-request timeout.
`KWIPU_STORAGE_LOCK_TIMEOUT`	`30` seconds	Positive wait limit for the shared storage lock.
`KWIPU_QUERY_MAX_LENGTH`	`4000` characters	Maximum normalized question length.
`KWIPU_MAX_SOURCE_BYTES`	`10485760` bytes	Maximum source-file and extracted-text size for bridge expansion.
`KWIPU_ALLOW_INSECURE_REMOTE_OLLAMA`	disabled	Allows plaintext HTTP to a non-loopback host when set to `1`, `true`, `yes`, or `on`.

Changing the embedding model requires a new storage index. Changing only the LLM permits loading existing vectors, although a later full rebuild can produce different extracted relations.

Bridge configuration

Variable	Default	Meaning
`BRIDGE_HOST`	`127.0.0.1`	Bind address used by `python -m bridge`.
`BRIDGE_PORT`	`8765`	Validated port from 1 through 65535.
`BRIDGE_CORS_ORIGINS`	`http://127.0.0.1:5173,http://localhost:5173`	Comma-separated browser origins; wildcards are rejected.
`BRIDGE_ALLOWED_HOSTS`	`localhost,127.0.0.1,testserver`	Accepted `Host` values; wildcards are rejected.
`BRIDGE_HEALTH_OLLAMA_TIMEOUT`	`2` seconds	Ollama timeout used by `/health`.

The bridge also uses every core setting above. python -m bridge consumes BRIDGE_HOST and BRIDGE_PORT; when invoking Uvicorn directly, pass them as CLI values:

uvicorn bridge.app:app --reload --host $env:BRIDGE_HOST --port $env:BRIDGE_PORT

See bridge/README.md for API contracts and deployment notes.

Frontend configuration

Variable	Default	Meaning
`VITE_API_BASE`	`/api`	Browser API base; relative values use the Vite proxy.
`VITE_BRIDGE_TARGET`	`http://127.0.0.1:8765`	Development proxy target.

MCP server

Use an absolute Python interpreter and script path in the MCP client configuration. Environment variables configure the model and paths because CLI flags apply only to geode_graph.py.

{
  "mcpServers": {
    "kwipu": {
      "command": "C:/path/to/Kwipu/.venv/Scripts/python.exe",
      "args": ["C:/path/to/Kwipu/kwipu_mcp_server.py"],
      "env": {
        "KWIPU_KNOWLEDGE_DIR": "C:/path/to/vault",
        "KWIPU_LLM_MODEL": "qwen2.5:7b",
        "KWIPU_EMBED_MODEL": "nomic-embed-text"
      }
    }
  }
}

The MCP server runs in fast retrieval mode and starts no watcher. It exposes:

query_graph(question) — returns the answer as text.
query_graph_detailed(question) — returns {"answer": "...", "citations": [...]} with citations deduplicated by node ID.

Selecting gpt-oss:20b-cloud carries the cloud privacy implications described above. Use installed local models when local-only execution is required.

Bridge API and source expansion

The main bridge endpoints are:

Endpoint	Purpose
`GET /health`	Check storage, configured models, and Ollama connectivity.
`GET /graph/snapshot`	Return the graph used by the 3D interface.
`POST /query`	Ask a question and receive an answer plus citations.
`GET /expand?node_id=<opaque-id>`	Read the cited source represented by a graph node.

Troubleshooting

Symptom	What to check
`python`, `ollama`, `node`, or `npm` is not recognized	Install the missing prerequisite, open a new terminal, and run its `--version` command.
`Activate.ps1` is blocked	Run `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`, then activate the environment again.
`Ollama is not running`	Start the Ollama application or run `ollama serve`; verify `http://localhost:11434/api/tags`.
`Missing model(s)`	Run the exact `ollama pull <model>` commands printed by Kwipu. Make sure indexer and bridge use the same model names.
`No files found. Waiting for documents...`	Put supported files under `KWIPU_KNOWLEDGE_DIR` and confirm the path printed in the CLI header.
Browser does not open	Keep Vite running and open `http://localhost:5173` manually.
Health is `degraded`	Inspect `property_graph.detail`, `ollama.detail`, and the `models` list in `/health`.
Query returns `503`	Start the CLI/indexer first and wait for a successful graph build/load. Also check storage path, lock, and embedding compatibility.
Query returns `502`	Check bridge logs and Ollama availability; the query engine or model request failed. Retrying should not be used to hide a persistent error.
Query returns `400 Question is too long`	The backend reports the active limit. The default is `4000`; a different value, such as `99`, means `KWIPU_QUERY_MAX_LENGTH` was overridden. Set it before starting the bridge and restart the bridge.
Port `8765` or `5173` is already in use	Stop the existing process or change the bridge/Vite settings consistently.
Embedding-model mismatch	Stop all Kwipu processes, restore the model used to build storage, or move the generated storage aside and let the CLI rebuild it. Never remove your source document directory.

Inspect a PowerShell override with:

Get-ChildItem Env:KWIPU_QUERY_MAX_LENGTH

Set the documented default for the current terminal and restart the bridge with:

$env:KWIPU_QUERY_MAX_LENGTH = "4000"
python -m bridge

Project structure

Kwipu/
├── geode_graph.py                # Core engine, interactive CLI, and watcher
├── kwipu_config.py               # Canonical environment configuration
├── kwipu_storage.py              # Inter-process lock and atomic JSON helpers
├── kwipu_mcp_server.py           # MCP stdio server
├── lang_config.py                # Multilingual patterns and date/relation helpers
├── requirements.txt              # Core/terminal and MCP dependencies
├── requirements-dev.txt          # Bridge/runtime/test dependency inputs
├── requirements-dev.lock         # Hashed Python 3.12 Linux CI lock
├── requirements-dev-windows.lock # Hashed Python 3.12 Windows CI lock
├── bridge/                       # FastAPI app and read-only query adapter
├── frontend/                     # TypeScript/Vite 3D client
├── knowledge_base/examples/      # Example source documents
├── img/                          # Logo and screenshots
├── tests/                        # Standard-library unittest suite
└── storage_graph/                # Generated active index, gitignored

Generated staging and backup siblings are also gitignored and managed automatically.

Developer setup

Use the platform-specific hashed lock for the complete bridge/runtime/test environment.

Windows, Python 3.12

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip==25.1.1
python -m pip install --require-hashes -r .\requirements-dev-windows.lock
python -m unittest discover -s tests -p "test_*.py" -v

Linux CI environment, Python 3.12

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip==25.1.1
python -m pip install --require-hashes -r requirements-dev.lock
python -m unittest discover -s tests -p "test_*.py" -v

Frontend validation commands are:

npm --prefix .\frontend ci
npm --prefix .\frontend run typecheck
npm --prefix .\frontend run build
npm --prefix .\frontend audit

License

MIT

Rendered by GitHub from the current README

Read on GitHub

Top contributors2 shown

benmaster82
23
dhruval30
1

Quality score

Would you bet a product on this? Bounded 0–100 and slow moving.

69/10069

Maintenance: 90%; How recently the default branch was pushed to
Releases: 25%; Recency and cadence of tagged releases
Community: 9%; Contributor breadth and bus factor
Issue backlog: 100%; Open issues measured against the size of the audience
Documentation: 99%; README depth, plus a homepage and topics
Licensing: 100%; How freely the code can be adopted

What to know before adopting

No tagged releases
Bus factor of 1 — one contributor dominates
Usable in commercial products with attribution.

Details

Created: 5 months ago
Last push: 13 days ago
Last release: none
Release tag: —
Releases in the last year: 0
Default branch: main
Size: 1.1k KB
Owner type: User
Owner location: Modena
Discovered via: phrase:ollama
First indexed: 2 months ago
Last synced: 5 days ago

Top AI Repos — open-source AI, indexed and scored

Trend

From the README

Kwipu

Choose your path

What Kwipu does

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

Ask about roles, tasks, and project context

Query meeting decisions and rebuild after note changes

Choose cloud or local

Quick start: web UI

1. Install and verify the prerequisites

2. Download Kwipu and install its runtime

3. Add documents

4. Make the models available

5. Use one consistent configuration

6. Start the indexer and terminal interface — Terminal 2

7. Start the API bridge — Terminal 3

8. Check health and start the frontend — Terminal 4

Terminal-only use

Linux and macOS command equivalents

Use your own document folder

Document updates

Core CLI reference

How it works

Components

Storage and process model

Configuration reference

Core configuration

Bridge configuration

Frontend configuration

MCP server

Bridge API and source expansion

Troubleshooting

Project structure

Developer setup

Windows, Python 3.12

Linux CI environment, Python 3.12

License

Top contributors2 shown

Quality score

What to know before adopting

Categories

Details

Trend

From the README

Kwipu

Choose your path

What Kwipu does

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

Ask about roles, tasks, and project context

Query meeting decisions and rebuild after note changes

Choose cloud or local

Quick start: web UI

1. Install and verify the prerequisites

2. Download Kwipu and install its runtime

3. Add documents

4. Make the models available

5. Use one consistent configuration

6. Start the indexer and terminal interface — Terminal 2

7. Start the API bridge — Terminal 3

8. Check health and start the frontend — Terminal 4

Terminal-only use

Linux and macOS command equivalents

Use your own document folder

Document updates

Core CLI reference

How it works

Components

Storage and process model

Configuration reference

Core configuration