Luminary：本地优先的文档学习工作区，答案带原文引用

Read. Ask. Write. Master what matters.

A local-first study workspace built on your own documents, that measures what you actually know.

Point it at a book, paper, video or article. Ask questions and get answers that cite the passage, write down what you understand, turn what matters into flashcards, and let it schedule the review. Nothing leaves your machine unless you give it an API key.

Full-quality video · Two-minute tour

Install

Download the installer for your system and open it. Every file is also on the latest release.

System	Download	Then
macOS (Apple Silicon, macOS 14+)		Open it and drag Luminary to Applications
Windows 10 or 11		Run it; installs for your user only, no administrator prompt
Linux (Debian, Ubuntu)		Open it in your software installer, or sudo apt install ./Luminary_*_amd64.deb
Linux (any x86_64)		chmod +x it and run it

The Windows installer is not yet code-signed: at Windows protected your PC, choose More info → Run anyway.

Everything ships inside the app — Python, the local model server and every dependency — and first launch fetches the models.

Or install with one command

On Windows and Linux, one command picks the right installer, checks your machine before downloading anything, verifies the download against its checksum and opens the app. On Debian and Ubuntu it installs the .deb through apt (sudo once), elsewhere the AppImage in your home folder.

Windows — in PowerShell:

irm https://raw.githubusercontent.com/nupsea/luminary/master/scripts/get-luminary.ps1 | iex

Linux — in a terminal:

curl -fsSL https://raw.githubusercontent.com/nupsea/luminary/master/scripts/get-luminary.sh | bash

For a background service, source installs or Docker, see docs/install.md.

What your machine needs

Luminary answers with a model on your machine, so it checks the machine can run one:

On a machine that cannot, the app says so at setup instead of offering local models, and the one-command install says so before downloading and offers to install anyway. Reading, search, notes, highlights and reviews all work there, and adding an API key in Settings makes answers and flashcards work too. Summaries and tags written during ingest stay off unless you choose Cloud mode, which sends document sections to your provider.

Updating and uninstalling

Run the same command again, or install the new release's .dmg, .exe or .deb; an older version is never installed over a newer one. Updates never touch your library.

To uninstall, use Settings → Apps on Windows, sudo apt remove luminary for the .deb, or drag the app to the Trash on macOS. Or run the one-command install with LUMINARY_UNINSTALL=1 set ($env:LUMINARY_UNINSTALL = "1" in PowerShell): it lists what it will remove and asks first. Your library — documents, notes, flashcards, settings and models — is kept and its location printed.

A source checkout is removed with make uninstall, which lists what it will remove and keeps the checkout's library; see docs/install.md.

Why this and not a chatbot

Every answer shows its receipts. A citation names the section and page, and the quote is the passage itself rather than the model's retyping of it — a model asked to retype a quote will invent one.

A flashcard is checked against your document. A card's quote is verified against the text, and a card that could not be checked says so. You know which cards are grounded and which are the model's word.

It measures what you remember. Before you flip a card you say whether you know it, so you find where you are confidently wrong. FSRS schedules the next review.

Your first five minutes

1. Add something. Library → Add Content: a PDF, EPUB, docx or audio file, or a web article or YouTube link.
2. Wait for the card to show Ready. Usually under a minute.
3. Ask it something in the panel beside the document. Clicking a citation marks the passage it came from. ⌘K / Ctrl+K searches everything.
4. Make some cards. Study → generate from the document → Start Review. Predict before you flip.

It works with the wifi off

In the default Private mode everything — reading, asking, generating cards, reviewing, taking notes, ingesting files — runs with no connection and no account, and nothing is sent anywhere. Turn the wifi off mid-session and it keeps working.

Faster answers, if you want them

A local model is private and slower. With an API key from Anthropic, OpenAI or Google AI Studio, answers come from a hosted model: Settings → LLM Mode → Answer with your API key. Only the question and the passages retrieved for it leave the machine — never the document, the library or your learner record.

Search runs on your machine either way, so the key buys the finish, not the start. The installed apps keep the key in your OS keychain. Docker and headless Linux have no keychain, so there a key saved in Settings is written to the library database in plain text; the key panel says which applies before you paste. Settings → Where your work runs lists every task and whether it runs on this machine.

What else is in it

Your data and logs

The library is one folder: copy it to move machines. Upgrades migrate it in place. If the app will not start, its startup screen says why and can open a pre-filled bug report; nothing is sent until you submit it.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Fork, branch from master, set up with make install-dev, and run make ci before opening a PR.

Found a bug or have an idea? Open an issue.

License

Apache 2.0