Orb

Your knowledge, on your machine.

Notes, voice, images, and documents become a searchable knowledge graph.
Chat across it. No Docker. No cloud required.

Download  ·  Install guide  ·  Build from source  ·  Privacy

---

Write notes the way you already do — text, voice, photos, PDFs. Orb extracts entities and relationships into a knowledge graph, indexes them for search, and answers multi-hop questions in chat. Everything runs locally through the desktop app: your vault, your models, your machine.

Note

End users install the Orb desktop app. You do not need Docker, Ollama, or a separate model server. Local chat, embedding, reranking, Florence, Whisper, and Marlin all load in-process in the API.

---

Features

Notes & vault

• Per–knowledge-base markdown vaults (note bodies live as real .md files, not in SQLite)
• Attachments stay in the vault — images, audio, PDFs, documents
• Entity highlighting and autocomplete from the graph as you write
• In-app voice recording and file attach on save

Multimedia ingest

On save, Orb enriches the note before graph indexing:

• PDF — native text plus Florence on embedded images and sparse page renders
• Images — Florence captions / OCR-style descriptions
• Audio / video — Whisper transcription; video also runs Marlin for visual understanding
• Enrichment is written into the vault markdown, then ingested into the graph

Chat & retrieval

• Multi-hop research loop over the knowledge graph (not a single vector lookup)
• Hybrid retrieval: entity lookup, keyword (Meilisearch), and vectors (Qdrant)
• Cross-encoder reranking with a local GGUF
• Inline source citations and optional model thinking

Knowledge graph

• Embedded Kuzu property graph with Leiden communities
• 3D graph explorer and node detail panels
• Multiple isolated knowledge bases (separate vault, vectors, keyword index, and graph)

Finance

• Per-KB Firefly III administrations — accounts and transactions stay scoped to a vault

Local models

• First-run wizard chooses data dir and models dir (NAS / OneDrive friendly)
• GGUF chat, embed, and rerank via llama-cpp-python in the API process
• Only one heavy model resident at a time (chat or embed or rerank or Florence/Whisper/Marlin)
• Cloud providers (Gemini, OpenAI, Anthropic, …) remain available if you want them

---

Screenshots

Chat	Notes editor

Knowledge bases	Model settings

---

Download

Installers ship as macOS .dmg and Windows .exe from GitHub Releases (tags desktop-v*).

---

Installation

macOS

1. Download the latest .dmg from Releases (arm64 for Apple Silicon, x64 for Intel)
2. Open it and drag Orb into Applications
3. Launch Orb
4. Complete the first-run wizard — pick a data directory and a models directory

On first launch the app downloads Qdrant and Meilisearch into your data dir, and you can pull GGUF models from Setup.

If macOS says the app is damaged (common for unsigned downloads), clear quarantine then reopen:

xattr -cr /Applications/Orb.app
open /Applications/Orb.app

Windows

1. Download the latest .exe installer from Releases
2. Run the installer and open Orb
3. Complete the first-run wizard (data dir + models dir)

Tip

Unsigned builds may need an extra click through Gatekeeper / SmartScreen until notarization and Authenticode are enabled. Prefer v0.2.0+ — faster ingest/retrieval, Obsidian-style wikilinks, and Firefly upgrade fixes. Avoid v0.1.0 Mac builds (could show “damaged” from broken Node helper symlinks in CI).

---

Build from source

Prefer to run or package Orb yourself? Use the Electron shell under desktop/.

Prerequisites

• Node.js 20+
• Python 3.11+ (dev uses the repo backend/.venv when present)
• macOS: Xcode CLT + cmake for Metal llama-cpp-python when packaging
• ffmpeg (audio transcoding)

Develop

git clone https://github.com/josetseph/Orb.git
cd Orb/desktop
npm install
npm start

This starts the supervisor with the repo backend and next dev frontend. Ports: UI 17400, API 17401, Qdrant 17433, Meilisearch 17470.

More detail: desktop/README.md.

Package installers

cd desktop
npm install
npm run prepare-dist   # bundle Python + Node + frontend (~10–20 min)
npm run dist:mac       # or dist:win on Windows

Full packaging notes: desktop/PACKAGING.md.

Contributors — optional Docker infra

docker-compose.yml can still bring up Postgres, Qdrant, Meilisearch, API, and UI for contributor stacks. It is not the product install path and does not run model HTTP sidecars — multimodal and GGUF inference stay in-process in the API. The Electron app always supervises local binaries (npm start in desktop/); do not wire Docker through the desktop shell.

# Optional contributor path only
docker compose up -d

---

Privacy

Orb is local-first. Notes, vault files, vectors, and models live under the directories you chose (or Application Support / %APPDATA%\Orb). Nothing is uploaded unless you explicitly configure a cloud LLM provider.

---

Benchmarks

Retrieval and HotPotQA evaluation reports live under Results/. They document earlier pipeline experiments; the shipping product path is the desktop app above.

---

License

Orb is released under the MIT License.