HilbertRaum is a private AI workspace that runs locally on your computer and can operate entirely offline. Chat with a local AI, ask questions about your documents, and keep your data under your control. There is no cloud fallback, no web search, and no telemetry. Your prompts, documents, embeddings, and chat history stay on local storage.

The workspace is encrypted and portable. The app, models, and data can all live on a hard drive or USB drive, allowing you to move the entire setup between machines.

HilbertRaum is open source and designed to run on a wide range of hardware, from CPU-only systems to single-GPU and unified-memory machines. The model catalog is intentionally small: we test each model for quality, speed, and hardware compatibility. HilbertRaum then selects an appropriate model for your machine, so you don't need to compare models or tune technical settings.

• 🔒 Private by design. No cloud, no telemetry, no analytics. Nothing you type or import is uploaded.
• 🧳 Portable and encrypted. Keep models and a password-encrypted workspace on an external drive

• 🧠 Local models. A llama.cpp runtime with GGUF models from a curated open-weight catalog

• 📄 Document Q&A with citations. Import PDFs, Word files, or text, ask questions, and get

• 📚 Knowledge packs — an offline Wikipedia (optional). Register ZIM archives — Wikipedia in ~100 languages,

• 🖼️ Image understanding. Ask questions about a picture with a local vision model. The analysis

• 🎙️ Audio and voice. Transcribe audio files with Whisper, dictate prompts, and OCR scanned pages.
• 🌐 Translation. A dedicated screen for text and whole documents (local TranslateGemma sidecar,

• ✅ Evidence review. Turn a document answer into a reviewable record: every statement is checked

• 🛠️ Document tasks and skills. Summarize, translate, and compare documents, or install reusable

• 🪟 Cross-platform. Runs on Windows, macOS, and Linux.
• 🔌 Local API (opt-in). Other programs on the same computer can use your running model through

Table of contents

• Status
• Which path are you on?
• What you need
• Getting started (DIY / from source)
• Supported models
• Knowledge packs — an offline Wikipedia
• Two distribution paths
• Documentation
• For developers
• Privacy & security
• Contributing
• License

Status

The app is feature-complete. You can explore the whole interface without downloading a model, and real AI answers start as soon as you add one (step 2 below). What remains before the first polished release is manual release testing: signed installers and a live demo run. BUILD_STATE.md tracks the details, and docs/known-limitations.md lists the gaps we have accepted for now.

Which path are you on?

• You set it up yourself (free, open source). Keep reading: you install the app, download

• You want it ready-made. We are preparing the HilbertRaum AI Kit, a preconfigured drive with

What you need

• A computer running Windows, macOS, or Linux, with at least 8 GB of RAM.

• Memory decides which model you get. The app detects your RAM and graphics memory (VRAM)

| RAM (no usable graphics card) | Recommended model | |---|---| | 8-11 GB | Qwen3.5 4B | | 12-15 GB | Gemma 4 E2B | | 16-23 GB | Qwen3.5 9B | | 24 GB | Qwen3.8 27B (UD-Q4_K_M) | | 32 GB and up | Qwen3.8 27B (UD-Q5_K_M) |

These are best-fit recommendations, not hard minimums. Each model's actual floor is the Min RAM column in the model table below; Qwen3.5 9B, for example, already runs from 12 GB. The MoE models stay opt-in.

• Disk space: about 3 GB for the smallest hand-built setup (the 4B chat model plus the

• To build from source: Node.js 22.12 or newer (24 recommended; 22.15+ enables the

• The AI itself is a GGUF model file plus the llama.cpp llama-server binary. Neither

Getting started (DIY / from source)

0. Download a prebuilt app (skip building from source)

Prebuilt packages are published on the Releases page: a portable Windows .exe, a macOS (Apple Silicon) .app.zip, and a Linux AppImage, each with SHA-256 checksums. If no release is listed yet, build from source below; the result is the same app. On Linux, run chmod +x HilbertRaum-.AppImage once before starting it; if it does not start, see Linux: the AppImage does not start.

• The download is the app only. A working chat needs two more downloads, both offered on the

• Windows: the build is unsigned for now, so SmartScreen shows "Windows protected your PC".

• macOS: the .app is unsigned too. If Gatekeeper blocks the first launch, allow it under

Details for both flows live in docs/troubleshooting.md. With a prebuilt app and no repo, the in-app installs above are all you need; with the repo, skip step 1 and continue at step 2 to provision a drive up front.

1. Run the app (no models needed yet)

git clone <this-repo>
cd HilbertRaum
npm ci             # one-time; downloads the Electron binary (needs internet once)
npm run dev        # launches the app

With no model files present you can still explore the whole interface: open AI Model and click Try in demo mode on a chat model (offered in developer mode, the dev default). Chat, document import, Q&A with citations, the benchmark, and the privacy screen all work in demo mode. Demo answers are simulated placeholders that echo your input; they are not real AI. Add a real model (step 2) for genuine answers.

The dependency install is the only step that touches the network. The app itself makes no

network calls in its core path.

2. Download the models (the real AI)

The app reads model weights and the llama-server binary from a drive root, which is any folder: an external drive, or a folder on your disk. Lay one out and download the AI in one command:

# Windows
.\scripts\prepare-drive.ps1 -Target E:\ -WithAssets -AcceptLicense   # layout + download + verify
.\scripts\verify-models.ps1  -Target E:\ -Generate                   # record the real hashes

# macOS / Linux
scripts/prepare-drive.sh --target /Volumes/HILBERTRAUM --with-assets --accept-license
scripts/verify-models.sh  --target /Volumes/HILBERTRAUM --generate

To keep setup fast, -WithAssets downloads a small but complete default set, not the whole catalog. It fetches the benchmark-winning mid-tier chat model (Ministral 3 8B, ~5 GB; on a machine with 12 GB or less you may prefer the smaller bundled Qwen3-4B, which you add with -AllModels or from the AI Model screen), the embeddings model (for document Q&A), the reranker, the Whisper transcriber model, and the vision model (for image understanding), plus both sidecar runtimes (llama.cpp for chat and embeddings, whisper.cpp for audio) and the OCR language files (deu/eng, ~4 MB, for scanned-PDF and photo text recognition). That is enough to chat, ask questions about your documents, get higher-quality retrieval, transcribe audio, understand images, and OCR scanned documents out of the box. Any other models (larger chat models) can be downloaded from inside the app later, on demand. To provision every model up front instead, add -AllModels (Windows) / --all-models (macOS/Linux). The sidecar runtimes and OCR files are fetched either way.

Whatever it fetches, the script verifies against the manifest via SHA-256 and copies the manifests and config onto the drive. Downloads resume if interrupted, and re-running skips what is already there. You can also fetch piecemeal (fetch-models / fetch-runtime, with --only for a single model) or drop the files into models/ and runtime/llama.cpp// by hand; see docs/packaging.md.

The whisper.cpp runtime ships prebuilt for Windows only. On a macOS/Linux build host,

-WithAssets skips it with a note; build it from source as described in

docs/packaging.md.

runtime-sources.yaml pins all three sidecar families — llama.cpp, whisper.cpp, and the

optional kiwix-tools — plus the OCR language-file block, each with real per-OS URLs and

SHA-256 checksums. The llama.cpp block is pinned to a real release (b11146, the build behind

upstream's stable v0.5.0, bumped from b9849 on 2026-09-27, #512) from the official GitHub

Releases API digest metadata. fetch-runtime downloads, verifies, extracts (zip and tar.gz), and flattens the

binaries for all three OSes from any host — fetch-runtime --family kiwix_tools fetches the

optional knowledge-pack tools the same way. Model weight URLs are real Hugging Face links, and

the bundled manifests carry real pinned SHA-256 hashes (captured from verified downloads with

verify-models --generate), so fetch-models checks every weight against them. To bump a

runtime later, see docs/model-policy.md.

3. Point the app at your models

The app uses whatever folder HILBERTRAUM_DRIVE_ROOT names (a prepared folder contains config/drive.json). On a preconfigured drive the launcher sets this automatically; from source you set it yourself, then launch:

$env:HILBERTRAUM_DRIVE_ROOT = 'E:\'; npm run dev    # Windows

HILBERTRAUM_DRIVE_ROOT=/Volumes/HILBERTRAUM npm run dev    # macOS / Linux

Open AI Model, press Use this model on the recommended model, and chat for real. To ship a portable build instead of npm run dev, see npm run package:win in docs/packaging.md.

Run tests / type-check: npm test, npm run typecheck.

Supported models

The scripts above download these (or add your own via a manifest). Weights are never in the repo; the per-model details live in model-manifests/ and the full schema and license policy in docs/model-policy.md.

The default set (-WithAssets) is enough for everyday use: a chat model plus embeddings (document Q&A), reranker (retrieval quality), and Whisper (audio). The benchmark auto-recommends the newest-generation chat model that fits your memory, following the tier table in What you need; the Min RAM column below is each model's lower hard floor. The MoE models (Qwen3 30B-A3B, Qwen3.5 35B-A3B) are opt-in: roughly 30B quality at roughly 3B active parameters per token, which means near-small-model CPU speed if the 18-22 GB of weights fits in RAM.

Chat models

| Model | Note | Size | Min RAM | License | |---|---|---|---|---| | Qwen3 4B Instruct Q4 | Bundled default on the preconfigured drive and the weak-laptop fallback; smallest ranked model that keeps the Deep answer mode | ~2.7 GB | 8 GB | Apache-2.0 | | Qwen3 4B Instruct 2507 Q4 | Better 4B quality (no Deep) | ~2.5 GB | 8 GB | Apache-2.0 | | Qwen3.5 4B (UD-Q4_K_XL) | Recommended below 12 GB: newest-generation 4B | ~2.9 GB | 8 GB | Apache-2.0 | | Gemma 4 E2B Instruct QAT Q4_0 | Recommended for 12-15 GB: fastest small-tier decode we measured; also where a slow 16-23 GB machine's recommendation steps down to | ~3.3 GB | 8 GB | Apache-2.0 | | Qwen3.5 0.8B Q6_K | Fast tier, selectable but never auto-recommended. Smallest runnable chat model and the fastest CPU decode in the catalog; the surviving fast-tier candidate of our grounded-QA eval (docs/model-benchmarks.md §9), with better F1 and unanswerable-question discipline than the 2B below | ~0.6 GB | 8 GB | Apache-2.0 | | Qwen3.5 2B (UD-Q4_K_XL) | Fast tier; failed its evaluation bar (scored below the 0.8B on F1 with the worst unanswerable-question discipline of the 13 models tested). Downloadable for completeness only | ~1.3 GB | 8 GB | Apache-2.0 | | Qwen3 8B Instruct Q4 | For laptops with 12 GB and more | ~5.0 GB | 12 GB | Apache-2.0 | | Ministral 3 8B Instruct (2512) Q4 | 8B benchmark winner and the DIY --with-assets default chat model (selectable; the 16-23 GB pick is Qwen3.5 9B) | ~5.2 GB | 12 GB | Apache-2.0 | | Qwen3.5 9B (UD-Q4_K_XL) | Recommended for 16-23 GB: newest-generation 9B | ~6.0 GB | 12 GB | Apache-2.0 | | Granite 4.1 8B Q4 | Challenger (selectable, not auto-recommended) | ~5.3 GB | 12 GB | Apache-2.0 | | Gemma 4 E4B Instruct QAT Q4_0 | 8B-tier challenger (selectable, not auto-recommended) | ~5.2 GB | 12 GB | Apache-2.0 | | Gemma 4 12B Instruct QAT Q4_0 | 12-14B benchmark winner; has Deep (selectable; the 24 GB pick is Qwen3.8 27B) | ~7.0 GB | 14 GB | Apache-2.0 | | Qwen3 14B Instruct Q4 | Dense, for 32 GB and more | ~9.3 GB | 14 GB | Apache-2.0 | | Gemma 4 26B-A4B Instruct QAT Q4_0 | MoE (~3.8B active): the 24 GB tier's ranked runner-up at about four times the pick's speed, never the auto-pick | ~14.4 GB | 20 GB | Apache-2.0 | | Qwen3.6 27B Q4_K_M | Former 24 GB pick; still ranked and selectable | ~16.8 GB | 20 GB | Apache-2.0 | | Qwen3.6 27B Q5_K_M | Former 32 GB pick; still holds the all-time top score of our grounded-QA eval | ~19.5 GB | 24 GB | Apache-2.0 | | Qwen3.8 27B UD-Q4_K_M | Recommended for 24 GB: newest generation, zero hallucinations in our quality eval. Decodes about 19 % slower than the withdrawn static Q4_K_M it replaces; measured and accepted | ~16.5 GB | 21 GB | Apache-2.0 | | Qwen3.8 27B UD-Q5_K_M | Recommended for 32 GB and up: the same zero-hallucination profile at a richer quant; reproduces the withdrawn Q5_K_M's envelope (4 % slower decode, same VRAM) | ~19.8 GB | 23 GB | Apache-2.0 | | Qwen3.8 27B UD-Q6_K | Quality ceiling for 24 GB GPUs (selectable, never auto-recommended; fully fits a 24 GB card at 8k context with a 21.8 GiB peak) | ~22.0 GB | 26 GB | Apache-2.0 | | Qwen3.8 27B Q4_K_M · Q5_K_M · Q6_K (static) | Upstream deleted these three files on 2026-08-20 (issue #196). Kept so a drive that already has one keeps working: it still verifies and runs, but it can no longer be downloaded, and the app says so instead of offering a Download button. Succeeded by the three UD rows above | ~17.1 / 19.8 / 22.9 GB | 21 / 23 / 26 GB | Apache-2.0 | | Qwen3 30B-A3B (MoE) Q4 | Roughly 30B quality at roughly 3B speed (opt-in) | ~18.6 GB | 24 GB | Apache-2.0 | | Qwen3.5 27B (UD-Q4_K_XL) | Dense challenger (selectable, not auto-recommended) | ~17.6 GB | 24 GB | Apache-2.0 | | Gemma 4 31B Instruct QAT Q4_0 | Dense ceiling (opt-in, selectable; slow on CPU) | ~17.7 GB | 24 GB | Apache-2.0 | | Qwen3.5 35B-A3B (UD-Q4_K_XL) | MoE (~3B active): rank 1 in our eval and the ranked speed alternative for 32 GB and up, never the auto-pick | ~22.2 GB | 24 GB | Apache-2.0 |

Supporting models (non-chat)

| Model | Role | What it powers | Min RAM | License | |---|---|---|---|---| | Multilingual E5 Small (F16) | Embeddings | Document search / RAG (required for Q&A) | 4 GB | MIT | | BGE Reranker v2 M3 (F16) | Reranker | Higher-quality retrieval ordering | 6 GB | Apache-2.0 | | Whisper Small (multilingual) | Transcriber | Audio-file transcription and dictation | 4 GB | MIT | | Qwen2.5-VL 3B Instruct Q4 | Vision | Image understanding (in the --with-assets default set; otherwise an in-app download) | 12 GB | Apache-2.0 | | TranslateGemma 12B (Q4_K_M) | Translation | Document and text translation (opt-in; in-app download behind a license prompt) | 13 GB | Gemma Terms |

Document Q&A needs the embeddings model; chat needs one of the chat models. Bigger dense models are smarter but slower on CPU, so pick by your RAM. Benchmark methodology and measured numbers are in docs/model-benchmarks.md.

Knowledge packs — an offline Wikipedia

HilbertRaum can answer from ZIM archives: compressed, self-contained offline copies of reference sites. The Kiwix project publishes thousands at library.kiwix.org — Wikipedia in about a hundred languages, plus Wiktionary, Wikivoyage, Stack Exchange, Project Gutenberg. Download one once, and the model can search and cite it forever, with no network.

A pack is a source, not a bigger model: the app searches the archive, hands the model the passages it found, and the answer cites the articles it used — and Open article shows the article text, offline, in the app. Packs are per chat and off by default (up to 12 in one chat), and unticking Search my documents answers from the packs alone.

1. Get the tools once. kiwix-serve and kiwix-manage are not bundled (GPL-3.0-or-later).

1. Add packs. Copy .zim files into the drive's zim/ folder, or use *Documents →

1. Ask. Open a documents chat's sources picker ("Answering from…") and tick the packs.

Asking never leaves your machine: the pack server binds to loopback only. One limit belongs in plain sight: While the workspace is unlocked and a knowledge pack has been used in a chat, other programs running under your own user account on this computer can read the enabled packs through the pack server, which has no password of its own; locking or quitting stops it.

Full detail — choosing packs, the setup paths, the privacy posture and every measured limit — is in docs/knowledge-packs.md; the step-by-step walkthrough is user guide §7b.

Two distribution paths

• Open-source DIY toolkit. Clone this repo, prepare your own drive, and download supported

• HilbertRaum AI Kit (commercial). A preconfigured drive with tested hardware, a signed and

Documentation

| Doc | What's inside | |---|---| | docs/product-vision.md | Product intent: thesis, target user, commercial model, positioning guardrails, scope, roadmap | | docs/user-guide.md | End-user walkthrough of every screen and feature | | docs/knowledge-packs.md | Knowledge packs (ZIM / offline Wikipedia): choosing packs, setup, asking, privacy posture, the measured limits | | docs/architecture.md | System design, services, IPC, runtimes, design records | | docs/rag-design.md | Retrieval pipeline: ingestion, chunking, hybrid search, rerank | | docs/security-model.md | Threat model, encrypted vault, offline guard, audit log | | docs/local-api.md | The opt-in local API: tutorial, client examples, the full HTTP contract, security and privacy posture | | docs/design-guidelines.md | Design system: tokens, components, UI/UX design records | | docs/skills-overview.md | The bundled skills at a glance; reviewed on every skill change | | docs/model-policy.md | Manifest schema, roles, license policy, runtime pinning | | docs/model-benchmarks.md | Measured model speed / RAM / quality plus the offline harness (not the hardware probe) | | docs/benchmark.md | In-app hardware benchmark and model recommendation (the machine-capability probe) | | docs/drive-layout.md | On-drive directory layout and how the app finds its data | | docs/packaging.md | Preparing a drive, fetch scripts, portable builds | | docs/troubleshooting.md | Common problems and fixes | | docs/known-limitations.md | Consciously accepted gaps | | docs/data-contracts.md | Shared cross-module data contracts (IPC surface, DB schema, streaming, …) | | docs/build-log.md | Archive of retired BUILD_STATE.md entries (frozen; grep for old citations) | | BUILD_STATE.md | Live build state; read first when contributing | | CHANGELOG.md | What changed for users, per released version, and the source of each release page's notes |

For developers

A single Electron app in an npm-workspaces monorepo (apps/desktop), built with electron-vite (Electron + React + TypeScript). Storage is the built-in node:sqlite; model runtimes are external sidecars (llama.cpp, whisper.cpp) so they stay swappable behind clean service interfaces.

HilbertRaum/
├─ apps/desktop/        # the Electron app (main / preload / renderer + tests)
│  └─ src/main/services # chat, rag, embeddings, reranker, vision, ocr, skills, …
├─ docs/                # architecture, rag, security, packaging, … (see above)
├─ model-manifests/     # per-model YAML (chat, embeddings, reranker, transcriber, translation, vision)
├─ app-skills/          # bundled skills: bank-statement, invoice, document-edit, document-redaction, contract-brief, meeting-protocol, deadline-obligation-finder, what-changed, share-safe-review
├─ scripts/             # prepare-drive / fetch-models / fetch-runtime / verify-models / …
├─ launchers/           # double-click launcher templates for a prepared drive
└─ eval/                # retrieval/quality evaluation fixtures

npm ci             # install (dev-time only; needs internet once for the Electron binary)
  npm ci installs EXACTLY what package-lock.json pins and never rewrites it (issue #49) —
  use it after every pull; plain npm install is only for deliberate dependency changes
  (with the pinned npm — see packageManager in package.json).
npm run dev        # launch the app
npm run build      # production build
npm test           # unit + integration tests (whole suite)
npm run typecheck  # TypeScript checking
npm run package:win # portable Windows .exe (electron-builder)
Faster iteration (from apps/desktop/): npx vitest run <file> · npx vitest -t "<name>" · npm run test:watch

New here? Read BUILD_STATE.md and CONTRIBUTING.md first. They cover the hard rules and the mandatory per-phase ritual (tests green, docs updated, BUILD_STATE.md updated).

Privacy & security

Nothing you type or import is sent anywhere. The workspace is encrypted at rest (AES-256-GCM, Argon2id key derivation); an unencrypted workspace exists only in developer builds. An offline guard logs (never blocks) any attempt to reach a remote host while offline, with local 127.0.0.1/localhost connections exempt, and a local audit log records activity for you (ids and counts only, never content).

The one inbound door is the local API, and it is opt-in: off by default behind a consent dialog, loopback-only (127.0.0.1/::1, no LAN mode exists), alive only while your workspace is unlocked, protected by an access key by default, structurally closed to browser JavaScript, and limited to chat completions. There is no route to your documents or conversations, and a drive policy can forbid it outright. Details in docs/local-api.md.

See PRIVACY.md and docs/security-model.md; report vulnerabilities per SECURITY.md.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the ground rules (no cloud/telemetry, offline-first, never commit weights or user data) and the workflow, and CODE_OF_CONDUCT.md for community expectations. Work one vertical slice at a time, add tests, keep npm run typecheck clean, and update the docs plus BUILD_STATE.md.

License

GPL-3.0-or-later for the software core. Model weights are not included and carry their own licenses (see docs/model-policy.md). Third-party notices for the npm packages bundled into packaged builds: THIRD-PARTY-NOTICES.md.

Native sidecars — a separate license class. The llama.cpp/whisper.cpp runtimes and the OCR language data are permissively licensed (MIT and Apache-2.0, respectively). The optional kiwix-tools sidecar is different: it is copyleft (GPL-3.0-or-later), statically linked against GPL-2.0-or-later-with-GPL-3.0-or-later-files libzim and GPL-2.0-or-later Xapian, plus LGPL-2.1-or-later libmicrohttpd. It is not linked into HilbertRaum — the app spawns it as a separate program and talks to it over loopback HTTP — so HilbertRaum's own GPL-3.0-or-later licensing is unaffected either way (see docs/model-policy.md "Sidecar binaries — kiwix-tools"). A preloaded Kit that ships the kiwix-tools binaries carries their complete corresponding source in runtime/kiwix-tools/source/ — that is the rule a shipping Kit follows, not a claim that the bundle exists in this repository today. A commercial build that cannot carry these source archives must not ship kiwix-tools; the app then shows the panel's tools-missing hint and the user installs the family in-app (their download, their consent). Full notices and the per-component license table: DRIVE-NOTICES.md and docs/model-policy.md.

Our promise: the HilbertRaum core is free software and will stay under GPL-3.0-or-later, in every version we publish here, forever. To fund its open development, we additionally offer the same software under commercial licenses (dual licensing), for example for tailor-made solutions for small businesses, or for embedding in other products without GPL obligations. That is also why contributions require a lightweight Contributor License Agreement; the reasoning is spelled out in CONTRIBUTING.md. Interested in a commercial license? Open an issue or contact the maintainers.

"HilbertRaum" and the HilbertRaum logo are trademarks; the GPL covers the code, not the name. Forks and unofficial kits must use their own branding; see TRADEMARKS.md.