kwiry

Knowledge Workspace Information Retrieval Yoke — pronounced “query”
one retrieval core yoking your knowledge into a truthful search experience

Local-first search for the knowledge you already own.
In the desktop sidecar profile, kwiry combines Tantivy BM25, fully offline ONNX embeddings, and RRF hybrid ranking in one Rust binary — nothing leaves your machine, and no cloud API is required. Point it at any Markdown or text tree, not just an Obsidian vault, then search through its watching daemon, authenticated HTTP API, or BRAT-installable Obsidian client. A contractual in-plugin lexical profile for desktops that cannot run a daemon remains urgent but is not delivered: after Tantivy's normal WASM writer hit its hard stop, the official SQLite FTS5-WASM runtime gate passed and the owner accepted the isolated one-file installed Obsidian/frozen-BRAT compatibility gate. Portable Rust extraction and production integration remain. Enterprise deployments use the separate OpenClast profile and its governed server-to-server boundary.

---

A single Rust binary provides:

• Lexical search (Tantivy BM25) over heading-split section chunks
• Semantic search (local ONNX embeddings, bge-small-en-v1.5, fully offline) — opt-in via serve --semantic
• Hybrid ranking (reciprocal rank fusion over both legs)
• A watching daemon with authenticated HTTP API, incremental hash-based updates, rename/delete correctness, and boot reconciliation for offline changes
• A disposable index: files are the sole source of truth; all derived state rebuilds from nothing, deterministically
• A no-daemon Obsidian lexical contract/design with verified FTS5 runtime and owner-accepted one-file installed Electron/frozen-BRAT compatibility—not a delivered plugin mode

Quick start

Native installers are not published yet. Build the binary from source, then use the guided setup on native Windows or Linux:

cd daemon
cargo build --release -p kwiry
./target/release/kwiry setup

On Windows, run target\release\kwiry.exe setup. The wizard asks for a tree, a stable ID, whether to enable semantic search, and final confirmation. It prepares the index, installs a least-privilege per-user background service, starts it, and verifies authenticated readiness. WSL lifecycle setup is intentionally rejected; manual development commands remain available there.

Preview an automation-safe plan without changing anything:

./target/release/kwiry setup /absolute/path/to/notes --id notes --no-semantic --dry-run --json

See the setup guide for Windows Task Scheduler behavior, Linux systemd --user, semantic first-run costs, JSON automation, service lifecycle commands, readiness checks, and recovery.

For development or unsupported lifecycle environments, the original explicit flow remains available:

cargo run -p kwiry -- vault add --id notes --path /absolute/path/to/notes
cargo run -p kwiry -- index
cargo run -p kwiry -- search "your query"
cargo run -p kwiry -- serve --semantic

Documentation

Start with the orientation layer, then follow links to the canonical contract and delivered behavior:

• docs/product-map.md — product vision, component relationships, trust profiles, search modes, and intended end state
• ROADMAP.md — desktop and identity-governed delivery tracks, current review boundary, and planned sequencing
• CONTRACT.md — binding product invariants, interfaces, and authorization commitments
• docs/setup.md — guided setup, automation, per-user service lifecycle, and recovery
• docs/vertical-1.md — deterministic lexical index and query core
• docs/vertical-2.md — daemon, watcher, authentication, and incremental correctness
• docs/vertical-3.md — local semantic and hybrid search
• docs/openclast-ig1.md — identity-governed OpenClast lexical gateway and operator configuration
• clients/obsidian/README.md — current daemon-backed Obsidian client behavior, installation, and privacy boundary
• docs/design/obsidian-lite.md — no-daemon design, measured Tantivy-WASM NO-GO, and staged FTS5-WASM feasibility gates
• bench/fts5-wasm/README.md — verified standalone official SQLite FTS5-WASM Gate 1 evidence and limitations
• bench/fts5-wasm-obsidian-probe/README.md — one-file Gate 2 automation, public frozen releases, field evidence, and accepted verdict
• docs/roadmap/desktop-obsidian.md — detailed desktop and Obsidian sequencing, including future recency/properties/folder relevance

Serve the repository documentation and logo previews without GitHub:

./scripts/serve-docs.sh local      # localhost only
./scripts/serve-docs.sh tailnet    # direct tailnet HTTP on port 32190
./scripts/serve-docs.sh tailscale  # tailnet HTTPS mounted at /kwiry
./scripts/serve-docs.sh unmount    # remove only the /kwiry HTTPS mount

The HTTPS mode preserves any existing Tailscale Serve root proxy and removes its /kwiry mount when the session exits.

Repository layout

Path	Contents	License
daemon/	Rust workspace: kwiry-core library + kwiry binary	MIT OR Apache-2.0
clients/obsidian/	Obsidian presentation client; currently daemon-backed, while D5B proceeds from accepted one-file compatibility into portable-core and production integration gates	GPL-3.0-only
fixtures/vault/	CI fixture vault for determinism tests	MIT OR Apache-2.0
bench/	Standalone runtime, storage, WASM feasibility, and compatibility probes	Per-package license; see each benchmark or probe

Unless a path contains its own license notice, repository content outside clients/obsidian/ is dual-licensed under MIT or Apache-2.0 at your option (the Rust convention; Apache-2.0 adds an express patent grant). Compatibility probes that bundle GPL-covered plugin code carry their own license. Unless you state otherwise, any contribution you submit follows the license of its target path, per Apache-2.0 §5 where applicable.

The accepted responsive logo system and preserved design archive live in docs/logo/: the untouched mark is used at 64px and below, while the graphite-K mark is used at 96px and above.

The Obsidian plugin is GPL-3.0-only and may port code from Omnisearch by Simon Cambier. The delivered profile currently talks to the daemon only over localhost HTTP. The selected D5B design may package portable dual-licensed Rust preparation code plus official SQLite FTS5-WASM behind the GPL plugin; no GPL code moves into the daemon or core.

Design invariants

1. Authorization precedes retrieval — candidate generation, scoring statistics, hydration, and future fusion/traversal are constrained before results exist.
2. Files are the sole source of truth — every byte of index state is derivable from the vault.
3. Explicit host profiles never fall back into one another: the desktop sidecar uses its loopback token, in-plugin lite uses a direct project-owned worker interface, and OpenClast uses short-lived signed search capabilities.
4. Presentation clients are dumb — project-owned hosts own retrieval. Native hosts use Rust adapters; constrained in-plugin mode uses portable Rust preparation/query planning plus an application-owned Worker binding fixed operations to official SQLite FTS5-WASM.
5. The engine is an implementation detail — Tantivy, official SQLite FTS5-WASM, sqlite-vec, and fastembed live behind project-owned adapters and models.
6. No algorithm authorship — scoring, ANN, tokenization, and embeddings are imported; RRF fusion is the one permitted formula.