lode

lode is an AI-first, TUI-first personal knowledge base for the things you learn during your day at work. Fast to capture, intelligent to retrieve. See docs/brand.md for the full brand brief (positioning, name story, palette, type, voice, usage rules).

The mother lode: a rich vein you accumulate and mine. An append-only log of notes + a derived knowledge graph — the ore and the assay.

Meeting notes, technical instructions, decisions — captured fast, retrieved with citations.

$ lode add
$ lode ask "what did we decide about auth?"

Install

lode does not publish to PyPI, so pip install lode installs a different, unrelated project — see docs/release.md. Two install paths actually work:

From a release (no clone needed). Download the wheel from the GitHub releases page and install it directly:

pip install lode_kb-*.whl   # the wheel attached to the release you downloaded

From source (for contributing or tracking trunk). See docs/onboarding.md for the full walkthrough (venv, beads issue database, quality gates); the short version:

git clone https://github.com/bildzeitung/lode.git
cd lode
./scripts/python-init.sh
. ./venv/bin/activate

The idea in one breath

Capture is cheap and frequent; retrieval is rare and valuable. The whole point of the AI is to make capture worth it because you trust you can always ask later and get a cited answer grounded in your own notes. The TUI keeps capture instant; intelligence runs async or on demand — never in the capture path.

Core principles

• You own the notes; the AI never touches them. Everything the AI produces — annotations, links, tags, embeddings — lives in a parallel derived layer that can be regenerated or thrown away without risking a single character of your content.
• Append-only, immutable history. Every save (create/update/delete) writes a new immutable, content-addressed node. Single-user, single-instance, no sync → simple linear history per note.
• Answers, with citations. Retrieval always points back to the source note, "as of" a known version. Fidelity over fluency.
• Externals are snapshotted, never bookmarked. Tickets, repos, wikis, email, and linked web pages get mirrored as immutable snapshots, so the knowledge graph is immune to link rot.

Stack

A split store that follows the ownership boundary. The irreplaceable set — your notes and your own corrections — lives in one SQLite file (backup = copy the file). The regenerable cache — embeddings, AI annotations, the knowledge graph — is rebuildable from the notes, so it optimizes for retrieval quality: LanceDB for vectors, SQLite FTS5 for lexical, fused app-side (RRF) with a local cross-encoder reranker, and networkx for in-memory graph traversal. Accessed from Python behind a thin repository interface, with a Textual TUI. Indexing is fully on-box — embeddings, reranking, and citation-checking all run locally (fastembed/ONNX), so content never leaves the box for indexing or retrieval. Claude does background enrichment (Haiku 4.5) and cited Q&A (Sonnet 4.6 / Opus 5) — these are explicit, logged egress, and notes/sources marked no_egress are kept local and never sent to the cloud. See docs/stack.md for the full rationale (including why a split store over a unified Oracle/Postgres engine) and docs/externals.md for the privacy model.

First run needs the network once. "Locally" describes inference, not the weights: the local models (embedder + reranker/NLI, ~500MB of ONNX files) download from HuggingFace on first use. Run lode models pull right after install to fetch them deliberately — see docs/configuration.md — rather than hitting that cost mid-capture. After that, retrieval is fully offline; indexing still makes one small metadata call per process to record which model revision produced the vectors (HF_HUB_OFFLINE=1 skips it too).

Status

Built end-to-end. The core loop ships: notes, version chains, cited Q&A, a minimal eval harness, and a web connector, behind a Textual TUI and a full CLI (lode add, lode ask, lode notes, lode work, lode models pull, …). See docs/design.md for the overview and a map of the design docs, with the reasoning behind every decision. Additional connectors (e.g. Atlassian) are being added one at a time — see docs/decisions.md for what's still open.

Working on the docs

The design docs contain Mermaid diagrams. They're validated against the same parser GitHub renders with, via the minlag/mermaid-cli Docker image — no Node/Chromium toolchain needed on the host:

scripts/update-images.sh      # pull the mermaid-cli image (one-time / on update)
scripts/validate-mermaid.sh   # parse every ```mermaid block in docs/, fail on syntax errors

docker is the only host requirement.

Brand assets

The hand-authored mark, wordmark, and lockup live under docs/assets/; the brief they conform to is docs/brand.md. The docs site's favicon (assets/favicon-16.png, assets/favicon.ico) is derived from a theme-neutral, fixed-tile variant of the mark (assets/favicon-mark.svg, lode-fhql.22 — a raster favicon can't track the browser chrome's own theme the way the header logo's currentColor SVG can, so it carries its own paper background tile instead), and its social/OG preview card (assets/og-card.png, 1200x630) is derived mechanically from the same mark — never redrawn — via scripts/rasterize-mark.sh, scripts/rasterize-favicon-mark.sh, scripts/rasterize-favicon-ico.sh, and scripts/rasterize-og-card.sh, each documented in its own header.

License

Apache-2.0.