What is Nostos?
Nostos is an open-source, self-hosted home for people who read and write. It brings physical books, EPUBs, PDFs and audiobooks into one quiet library, keeps saved passages and notes attached to the exact page they came from, and lets you bring quotations into your drafts with verified citations.
It connects the whole journey in one place: Read → Notice → Capture → Return → Write.
- Read & listen: Read EPUBs and PDFs with adjustable typography, or listen to audiobooks (multi-track files play as one book).
- Capture & return: Highlights and notes stay attached to their source. Topics connect ideas across books in the Brain.
- Write: Type
@ in the Writing Studio to pull a kept passage into your draft with attribution attached. Export with real footnotes to Word, PDF, Markdown or rich text for Substack.
- Own your data: Runs locally as a single Docker container with SQLite. Export notes and highlights as plain Markdown or full
.nostos backups anytime.
It is deliberately quiet. There are no social feeds, streaks or engagement mechanics. The optional assistant stays out of the way until you ask for it.
You can use the hosted service, Nostos Cloud, or run it yourself. This repository is the complete, open-source SelfHosted app.
Features
Library
- Every kind of book in one place: physical books, EPUB, PDF and audiobooks (MP3, M4A, M4B) to read or play. TXT and MOBI files can be stored and downloaded, but Nostos cannot read them yet. Audiobooks split into many files play as one book.
- Free books, built in: search Project Gutenberg, Standard Ebooks, Wikisource and LibriVox from Add a book.
- Collections and editions: nested collections, drag and drop, and editions of the same work grouped together.
- A To read list: keep the books you want but don't own yet, with a short Next up shelf.
- Search everything: press Ctrl/⌘+K to find books, topics, notes and documents. Search forgives typos.
Reading & listening
- Readers for every format: an EPUB reader with adjustable typography, a PDF reader, and an audiobook player with chapters, speed control and a sleep timer.
- Highlights and notes on the page: select text to highlight it, and click a highlight to open its note.
- Passages: save a long stretch of a book, a range of PDF pages or a clip of an audiobook, and read or play it again on its own.
- Switch between ebook and audiobook: if you have both editions, continue in the other one near where you are (needs a speech-to-text provider; otherwise each edition opens where you left it).
- Read aloud: listen to any EPUB or PDF with your device's voice or a natural voice from a speech server.
- Bring your highlights: import highlights and notes from Kobo, KOReader, a Kindle's
My Clippings.txt or Readwise — through its export API with an access token, or a CSV export — review them, then add them to the right books.
Brain
The Brain is where notes from different books meet.
- Topics: link ideas with
[[Topic]] in any note or with a tap on its card, and sort new notes one by one.
- Places, like the Library: all notes, passages, unsorted notes, the topic map, and every topic, in one sidebar.
- Back to the source: every topic leads back to the notes, passages and books behind it, and can carry your own words.
Writing Studio
- Opens on the page: a blank sheet with the caret in it; your files and references slide in when you want them, and the chrome fades while you type.
- Type
@ to quote: find a note, quote or passage by its words, book or author (@schopenhauer will) and put it on the page with its attribution. A long passage opens so you can pick the sentences you want.
/ for blocks: headings, lists, a divider, an image, a table or code from an empty line.- Make the page yours: Studio themes, typefaces, size, spacing and width, a typewriter mode that keeps the current line centred, and optional typewriter sounds.
- Saves as you type, as plain Markdown.
Ask Nostos (optional)
Ask Nostos is an AI assistant for your own library. It can find what you have read, save a thought or a quote, add books, link notes to topics, open and draft Studio documents, put a book on To read, or reorganise your collections and book details. When it changes your library, it shows one set of changes you can undo, or review before anything happens. Nostos works fully without it.
On SelfHosted, you connect your own AI provider in Settings → AI connections. Nostos Cloud includes a managed allowance.
Connect your own AI (SelfHosted)
Use the AI app you already pay for with your library. Make an access token in Settings → Connected apps, paste the setup it gives you, and Claude Code, Cursor, VS Code or Claude Desktop can search your books and notes, quote them with citations, and save notes and drafts. Each token is read only or read and write, and you can revoke it at any time. Apps that run on the web, like claude.ai and ChatGPT, connect through a public address for just the MCP and sign-in paths (Tailscale Funnel, Cloudflare Tunnel or a reverse proxy), and you approve each one in Settings: see Connect claude.ai and ChatGPT.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
