💡 100 % local, privacy‑first Knowledge Base — Chat with your Joplin vault offline and under your full control.

Replace cloud Retrieval‑Augmented‑Generation services with a 100 % local stack:

• No vendor lock‑in – all components are open‑source, containerised, and easily swappable.

• Respect your data – nothing leaves your machine unless you enable the optional Telegram bridge.

• Optimised for commodity hardware – runs smoothly on an 8 GB RAM laptop, scales down to a Raspberry Pi 4 (via fast CLI) and up to a GPU workstation.

• Transparent plumbing – plain Python, Docker, and YAML; every step is auditable.

              ┌─────────────── ① ingestion ────────────────┐
Joplin Export │  Markdown / Attachments / Resources        │
              │           `joplin_sync.py`                 │
              └───────────────────┬────────────────────────┘
                                  │  batches of chunks
                                  ▼
                        ┌───────────────────────┐
                        │      Weaviate         │  ② retrieval
                        │  (BM25 + vectors)     │<──────────────┐
                        └───────────────────────┘               │
                                  ▲                             │
                                  │ GraphQL                     │
                                  │ ③ context                  │
                                  ▼                             │
                        ┌───────────────────────┐               │
                        │       Ollama          │  ④ answer     │
                        │ (local LLM/adapter)   │───────────────┘
                        └───────────────────────┘
                                  ▲
                                  │
    ┌───────────────┬─────────────┴───────────────┐
    │ Terminal CLI  │  Telegram (opt.)   │  Element / Matrix (WIP)
    └───────────────┴─────────────┬───────────────┘
                              Conversation

(† a minimal Flask gateway is planned for v2025‑Q3.)

1. Ingestion – joplin_sync.py scans export folders, slices Markdown into ~500 token chunks, OCRs images/PDFs, computes embeddings (dimension 384), and uploads JSON batches.

2. Storage – Chunks live in Weaviate with original note path, resource hash, timestamps, and tag list.

3. Retrieval – CLIs perform hybrid search (BM25 + cosine) with a configurable α blend, rerank hits with recency & ownership heuristics, and craft the final prompt.

4. Generation – A local Ollama model (e.g. llama3:8b‑instruct) produces the answer, including citations back to note source paths.

git clone https://github.com/luisriverag/joplin_weaviate_ollama/.git
cd joplin_weaviate_ollama
python -m venv .venv
source .venv/bin/activate   # Windows → .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

• Debian/Ubuntu

  sudo apt update
  sudo apt install tesseract-ocr libtesseract-dev poppler-utils
  sudo apt install tesseract-ocr-eng tesseract-ocr-spa  # language packs

• Arch

  sudo pacman -S tesseract tesseract-data-eng tesseract-data-spa

• macOS (Homebrew)

  brew install tesseract poppler
  brew install tesseract-lang   # add packs as needed

• Windows

  1. Install Tesseract and add to PATH.

  2. WSL2 users: run Weaviate inside WSL or in a Docker Desktop Linux container.

Install CUDA 12 + cuDNN 8 or Apple Metal plugins → restart Ollama. ollama pull llama3:8b will auto‑detect GPU and quantise accordingly.

Copy .env and tweak:

cp sample.env .env
nano .env

docker compose up -d
# wait for readiness
until docker compose logs --tail 5 weaviate | grep -q "Startup complete"; do sleep 2; done

ollama serve &
ollama pull llama3:8b   # first time only

Tip: Put ollama serve in a systemd user service for autostart.

python rag_query.py
🧠 > ¿Tengo la factura de la lavadora?

Ideal for constrained hardware; same usage minus memory & reranking:

python rag_query-fast.py --config patterns.yaml

Hot‑reload config: :reload inside CLI re‑reads the YAML without restart.

python telegram_rag_bot.py &

1. Set TELEGRAM_BOT_TOKEN and TELEGRAM_USER_ID in .env.

2. Send /start to your bot.

3. Use Markdown or plain text; answers cite note paths like notebooks/Finanzas/2023-IRPF.md.

Security note: The bot rejects messages from any ID except the whitelisted one.

Note: ragbot_elementmatrix.py is untested, pull requests welcome

Logs:

• sync_errors.log – ingestion issues

• ~/.ollama/logs – LLM server

• weaviate-data/logs – DB warnings

• Network isolation – Weaviate listens on localhost by default. Use firewall rules or Docker network to restrict.

• Encrypted volume – Store weaviate-data/ on an encrypted partition if note content is sensitive.

• No telemetry – ENABLE_TELEMETRY=false in compose file.

• Telegram bridge – Remember all traffic goes through Telegram’s servers; dont run the telegram ragbot if strict privacy is required.

• Why two CLIs? — rag_query.py aims for maximal context awareness; rag_query-fast.py boots in seconds, fitting IoT / Pi devices.

• Does any data leave my machine? — No, unless you enable the Telegram bot or point WEAVIATE_URL to a remote host.

• How do I wipe and rebuild the index? — docker compose down -v to drop shards, delete note_cache.json, then run a fresh sync.

• Can I disable OCR? — Yes: --no-ocr skips image/PDF text extraction.

MIT