Turn your Kobo & Kindle highlights and reading data into structured, readable insight.
Live Demo · Features · Getting Started · CLI · Web UI · Roadmap
No cloud required. No account. No tracking.
Your reading data stays on your machine.
⭐ If KoNotes helps you get more out of your reading, consider starring the repo.
Kobo and Kindle e-readers create rich annotation data -- highlights, notes, bookmarks, dictionary lookups, reading sessions -- but getting that data out and doing something useful with it is harder than it should be.
|
What your e-reader gives you
|
What KoNotes gives you
|
Parse, browse, and export your Kobo library from the command line
Chat with your reading data using your own OpenAI API key
| Overview | Library |
|---|---|
 |
 |
| Library-wide metrics, top authors, reading time | Browse books with progress bars and shelf badges |
| AI Insights | Activity |
|---|---|
 |
 |
| Evidence-backed reading intelligence feed | Sessions, progress curves, annotation timelines |
| Book Detail | Vocabulary |
|---|---|
 |
 |
| Per-book annotations grouped by chapter | Every word you looked up, searchable by book |
| Chat | Chat Conversation |
|---|---|
 |
 |
| Connect with your own OpenAI key | Ask questions about your reading habits and get recommendations |
Explore KoNotes instantly in your browser -- no install, no setup. The hosted demo runs on Streamlit Community Cloud with a preloaded synthetic library so you can browse every view, chart, and insight category.
| Hosted Demo | Local Install | |
|---|---|---|
| Setup | None -- runs in your browser | Clone, install, launch |
| Data | Preloaded synthetic library (Kobo & Kindle) | Your real Kobo/Kindle data |
| Kobo USB detection | Not available | Full support |
| Insights | Rule-based Insight Feed | Full Insight Feed + AI themes, clustering, summaries with pip install '.[ai]' |
| Chat | Bring your own OpenAI key | Bring your own OpenAI key with pip install '.[chat]' |
| Privacy | Runs on Streamlit Cloud; Chat sends data to OpenAI if used | Fully local unless Chat is used |
| Export | HTML site and CSV download | HTML site, CSV, Markdown, JSON, text via CLI |
| Best for | Quick preview | Daily use with your own reading data |
The demo uses entirely synthetic data. For the full experience -- especially Kobo device detection, AI insights, and export -- install locally.
KoNotes isn't just a parser -- it turns raw reading data into personal intelligence about how you read.
- Reading patterns -- when you read, how long your sessions last, and how your pace changes over time
- Highlight behavior -- which books made you stop and mark something, and what themes keep resurfacing
- Vocabulary growth -- every word you looked up, how often, and in which books
- Cross-book connections -- ideas that echo across different authors, surfaced automatically
- Engagement signals -- which books held your attention, which ones stalled, and where your deepest reading happens
- Progress momentum -- streaks, slowdowns, and completion curves across your entire library
Most of this data already exists on your Kobo or Kindle. KoNotes makes it visible.
|
|
|
Here's a sample of what KoNotes surfaces from a real reading library. All data below is synthetic.
|
Insight: Deep Reading Detected
Insight: Recurring Theme -- Power & Control
Insight: Vocabulary Spike
Insight: Reading Momentum
|
These insights are generated automatically from your Kobo data. With AI features enabled, KoNotes also detects themes, clusters ideas across books, and generates per-book summaries.
- Python 3.12 or higher
- pip
git clone https://github.com/texasbe2trill/KoNotes.git
cd KoNotes
python3 -m venv .venv
source .venv/bin/activate # macOS / Linux
# .venv\Scripts\activate # Windows
pip install -r requirements.txtOptional: Install AI features
For theme detection, clustering, similarity search, and smart summaries:
pip install '.[ai]'This installs sentence-transformers, scikit-learn, and numpy. All AI processing runs locally on your machine -- no API keys needed. The embedding model (~80 MB) is downloaded once on first use and cached.
Optional: Install Chat features
To chat with your reading data using an OpenAI API key:
pip install '.[chat]'This installs the openai Python package. You provide your own API key in the browser -- it is never stored or transmitted by KoNotes.
# Web UI
streamlit run app/app.py
# CLI
konotes --helpWith a Kobo connected via USB:
konotes detect-device # find your Kobo
konotes parse <path> # parse the database
streamlit run app/app.py # launch the dashboardNo Kobo on hand? A synthetic test database is included:
konotes parse docs/KoNotes_synthetic.sqlite
streamlit run app/app.py
# then upload docs/KoNotes_synthetic.sqlite in the browserHave a Kindle? Use your My Clippings.txt file:
konotes parse My\ Clippings.txt
streamlit run app/app.py
# then upload My Clippings.txt in the browserKoNotes also works with .html, .txt, or .md annotation exports. See Supported Inputs.
| Format | Extensions | Interface | Source | Priority |
|---|---|---|---|---|
| KoboReader SQLite | .sqlite, .sqlite3, .db |
Web UI + CLI | Kobo device .kobo/ folder |
Primary |
| Kindle My Clippings | .txt (auto-detected) |
Web UI + CLI | Kindle device root | Primary |
| Kobo HTML export | .html, .htm |
CLI only | Kobo app / device | Secondary |
| Kobo plain-text export | .txt |
CLI only | Kobo app / device | Secondary |
| Kobo Markdown export | .md, .markdown |
CLI only | Kobo app / device | Secondary |
How to get your data
From a Kobo e-reader (recommended):
Connect via USB. KoNotes detects it automatically. Or navigate to the .kobo/ hidden folder and copy KoboReader.sqlite.
From the Kobo app: Open a book, tap the highlights icon, Share annotations, and choose your format.
From a Kindle e-reader:
Connect via USB. Copy My Clippings.txt from the device root. The file contains all highlights, notes, and bookmarks across every book. KoNotes auto-detects the Kindle format and deduplicates entries.
KoNotes uses adaptive, schema-aware SQLite parsing -- it reads only the columns and tables that exist in your specific database and gracefully handles missing metadata. Works across firmware versions and device models.
KoNotes ships with seven CLI subcommands. Every command works with any supported file format.
konotes detect-deviceKobo Libra 2
Mount: /Volumes/KOBOeReader
Database: /Volumes/KOBOeReader/.kobo/KoboReader.sqlite
konotes parse /Volumes/KOBOeReader/.kobo/KoboReader.sqliteParsed: KoboReader.sqlite
Books 24
Annotations 387
Highlights 312
Notes 75
In Progress 8
Completed 16
Avg HL/Book 13.0
Books
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
┃ Title ┃ Author ┃ Highlights ┃ Notes ┃ Progress ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
│ Dune │ Frank Herbert │ 42 │ 12 │ 100% │
├─────────────────────────────┼───────────────────┼────────────┼───────┼──────────┤
│ Neuromancer │ William Gibson │ 28 │ 6 │ 73% │
├─────────────────────────────┼───────────────────┼────────────┼───────┼──────────┤
│ The Left Hand of Darkness │ Ursula K. Le Guin │ 19 │ 3 │ 45% │
└─────────────────────────────┴───────────────────┴────────────┴───────┴──────────┘
konotes export KoboReader.sqlite -f markdown -o ./output
konotes export KoboReader.sqlite -f json -o ./output
konotes export KoboReader.sqlite -f text -o ./output
konotes export KoboReader.sqlite -f csv -o ./outputTip: The Markdown export renders beautifully in Markdown editors like Bear, Obsidian, and Typora. KoNotes is not affiliated with or endorsed by any of these apps.
konotes summary KoboReader.sqlite Books 24
Annotations 387
Highlights 312
Notes 75
Avg HL/Book 13.0
Top Authors:
Frank Herbert -- 3 book(s)
William Gibson -- 2 book(s)
Most Highlighted:
Dune -- 42 highlight(s)
Neuromancer -- 28 highlight(s)
Shelves:
sci-fi (12 book(s))
currently-reading (3 book(s))
konotes book KoboReader.sqlite "Dune"Dune
Author: Frank Herbert
Series: Dune Chronicles #1
Progress: 100%
Highlights: 42 Notes: 12
HL Fear is the mind-killer. Fear is the little-death that brings total
obliteration.
HL He who controls the spice controls the universe.
NT The litany against fear is a central theme -- connects to the Bene
Gesserit training...
... and 49 more
konotes export-html KoboReader.sqlite -o ./my-siteStatic site exported to: ./my-site/
Open ./my-site/index.html in a browser to view.
Generates a single self-contained index.html with your full library, annotations, charts, and reading intelligence. Dark-themed. No dependencies. Works offline.
konotes chat KoboReader.sqliteOpenAI API key: sk-...
Fetching available models...
Available models:
1. gpt-4o
2. gpt-4o-mini
3. gpt-4.1-mini
4. gpt-4.1-nano
Select a model [1-4] (default: 1): 2
Model: gpt-4o-mini
Library: 24 books
Type 'exit' or 'quit' to end the conversation.
You: Which book did I highlight the most?
KoNotes: Dune has the most highlights with 42 passages marked...
You: exit
Goodbye.
Start an interactive conversation about your reading data. Requires pip install 'konotes[chat]' and an OpenAI API key. You can also pass --model gpt-4o-mini to skip model selection, or set the OPENAI_API_KEY environment variable to skip the key prompt.
Launch with streamlit run app/app.py and open localhost:8501.
| View | What it does |
|---|---|
| Overview | Library-wide metrics, top authors, annotation trends, reading time, shelf distribution. Includes ranked recommendation cards with book covers. Kindle: annotation density, pace, engagement ratio |
| Library | Browse all books with progress bars, shelf badges, author/status filters, and book cover thumbnails |
| Book Detail | Per-book annotations grouped by chapter, with search, filtering, export, full metadata, and a medium-sized cover image beside the title |
| Annotations | Cross-book annotation search -- find any highlight by keyword |
| Activity | Reading sessions, progress curves, annotation timelines, day-of-week and time-of-day charts. Kindle: stacked bars, heatmaps, cumulative timelines |
| Vocabulary | Every dictionary lookup from your Kobo, searchable and filterable by book, with frequency data |
| AI Insights | Insight Feed with 15+ categories, theme detection, clustering, similarity search, summaries, Bluesky sharing |
| Chat | Ask questions about your reading data, generate Bluesky posts, powered by your own OpenAI API key |
Plug in your Kobo via USB and the app detects it. Or drag-and-drop any supported file, including Kindle My Clippings.txt.
pip install pytest
pytest tests/ -v489 passed
Tests cover every parser, normalizer, model, CLI subcommand, export format, SQLite telemetry extractor, AI insight pipeline, insight feed, recommender engine, book cover resolver, chat context builder, share formatters, and static HTML exporter.
KoNotes/
├── app/
│ ├── app.py # Streamlit entry point
│ ├── charts.py # Shared Plotly chart helpers
│ ├── assets/ # Logo, CSS
│ ├── components/ # Reusable UI components (book covers, recommendation cards)
│ └── views/ # Overview, Library, Activity, Vocabulary, Insights, Chat
├── models/ # Pydantic models (Book, Annotation, Session, Insight, Recommendation, ...)
├── parser/ # SQLite, HTML, TXT, Markdown, Kindle parsers + device detection
├── services/ # Stats, exports, AI, embeddings, insight feed, recommender, book covers, chat
├── utils/ # Text utilities, schema helpers
├── tests/ # 571 tests across 20+ modules
├── main.py # CLI entry point
├── pyproject.toml # Project metadata & build config
└── requirements.txt # Runtime dependencies
Architecture Decisions
| Decision | Rationale |
|---|---|
| Local-first AI | Embeddings via sentence-transformers run entirely on your machine |
| Pydantic models | Typed, validated data structures with JSON serialization |
| Abstract parser interface | New input formats slot in without touching existing code |
| Read-only SQLite | Opens the database with ?mode=ro -- zero risk to user data |
| Schema-aware queries | Handles firmware variations gracefully |
| Streamlit | Fast to iterate, zero frontend build step |
| No database / no server | All processing happens in-memory per session |
| Single-page HTML export | One file, no dependencies, works offline |
Phases 1 through 6 are complete. Phase 7 is next.
Phase 1 -- MVP ✅
- Parse Kobo HTML, TXT, and Markdown annotation exports
- Parse KoboReader.sqlite (read-only)
- Normalize into typed
Book/Annotationmodels - Library and book detail views
- Cross-book annotation search
- Markdown export and CLI summary
Phase 1.5 -- Polish ✅
- Rich CLI with subcommands (parse, export, summary, detect-device, book, export-html)
- Chapter title normalization
- JSON and plain-text export
- Enhanced SQLite extraction (shelves, progress, publisher, ISBN, language)
- Schema-aware SQLite helpers for firmware compatibility
- Device detection
- 92 tests
Phase 2 -- Reading Intelligence Dashboard ✅
- Reading session detection
- Progress snapshot extraction
- Library statistics (15+ metrics)
- Overview, Activity, and enhanced Library views
- CLI book lookup with partial matching
- JSON export with telemetry metadata
- 135 tests
Phase 3 -- AI/ML Features ✅
- Theme detection -- cluster highlights by semantic topic
- Highlight clustering -- recurring ideas across books
- Smart summaries -- "what I learned" per book
- Similarity search -- find echoing highlights
Phase 4 -- Integrations & Sharing ✅
- Vocabulary view -- browse dictionary lookups
- Static HTML export with charts and reading intelligence
- Structured Insight Feed with evidence-backed cards
- Insight export (Markdown and plain text)
- Activity charts (timeline, snapshots, sessions)
- 461 tests
Phase 5 -- Social & Sharing ✅
- CSV export format
- Reading goals and streaks
- Chat with your reading data (OpenAI)
- Bluesky sharing from annotations, insights, themes, and summaries
- First-person post composition for social sharing
- Chat-generated #booksky posts with reading context
- New insight generators (active vs passive reading, export-worthy, vocabulary friction)
- Conversational insight summaries (less stat-heavy)
- Author attribution on shared posts
- 461 tests
Phase 6 -- Kindle Support ✅
- Kindle My Clippings.txt parser with auto-detection
- Kindle upload in Web UI (tabbed: Kobo | Kindle)
- Dynamic dashboard adaptation (Overview, Activity, Library views adjust for Kindle data)
- Kindle-specific charts: annotation density, pace, engagement ratio, heatmaps, cumulative timelines
- Kindle demo dataset with switch toggle
- CLI support for all subcommands with Kindle files
- 489 tests
Phase 7 -- Recommendations & Book Covers ✅
- Rule-based recommendation engine with 6 categories (revisit, finish, export, forgotten gem, deepest thinking, compare)
- Ranked recommendation cards on Overview with evidence bullets and call-to-action
- Share/copy buttons on recommendation cards (Bluesky + clipboard)
- Book cover art throughout the app (Library thumbnails, Book Detail header, Recommendation cards)
- Cover resolution priority: local file path → metadata URL → Open Library by ISBN (same source as Calibre)
- ISBN-only Open Library lookup -- no title/author guessing to avoid wrong covers
- Persistent cover cache at
~/.konotes/cover_cache.jsonwith version key to auto-invalidate on strategy change - Initials placeholder gradient for books without covers
- Book cover support in static HTML export
- 571 tests
Phase 8 -- Future
- Annotation tagging and categorization
- Spaced repetition integration
- Reading statistics export (PDF report)
Contributions are welcome. KoNotes is designed to be easy to extend.
git clone https://github.com/texasbe2trill/KoNotes.git
cd KoNotes
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install '.[ai]'
pytest tests/ -v- Open an issue first to discuss your change
- Fork and create a feature branch
- Write tests for your changes
- Make sure all tests pass
- Open a pull request
Good first contributions: new export formats (EPUB, PDF), UI improvements, annotation tagging, enhanced classification heuristics.
|
KoNotes is a local-first tool. Your reading data never leaves your machine.
AI features and network access:
Book cover fetching: When the app resolves book covers for books with an ISBN, it makes a single HEAD request to the Open Library covers API ( Chat feature: The optional Chat view lets you ask questions about your reading data using your own OpenAI API key. When you use Chat, your reading context (library stats, highlights, notes) is sent to the OpenAI API to generate responses. Your API key is only held in your browser session and is never saved. Chat is entirely opt-in -- it requires installing the Hosted demo: The live demo runs on Streamlit Community Cloud with synthetic data only. No real user data is uploaded or stored. |
If KoNotes is useful to you, consider giving it a star or sponsoring the project.
KoNotes exists because of the tools, communities, and people who make building in public possible.
- Streamlit — powering the KoNotes dashboard
- sentence-transformers — local embeddings for AI features
- Plotly — interactive charts and visualizations
- Rich — beautiful terminal output
- Pydantic — data validation and modeling
- Kobo — for building e-readers that make this data possible
- The #booksky community on Bluesky — for reminding me that reading is better when it’s shared
- The open-source community — for making it normal to build, ship, and learn in public
- Everyone exploring local-first tools — this project exists because privacy and ownership matter
- Friends and family who listened to me talk about “Kobo SQLite databases” more than they probably wanted to
- Anyone who tested, gave feedback, or starred the repo — early support means everything
- Every reader who highlights, takes notes, and looks up words
Your curiosity is what makes this project meaningful.
KoNotes is an independent, open-source project. It is not affiliated with, endorsed by, or sponsored by Rakuten Kobo Inc. "Kobo" is a trademark of Rakuten Kobo Inc.
- KoNotes does not access Kobo accounts, servers, or APIs
- KoNotes does not bypass, circumvent, or interact with DRM
- KoNotes only processes files explicitly provided by the user
- All database access is read-only (
?mode=ro)
All example data shown in this README, in tests, and in demo fixtures is entirely synthetic. The included docs/KoNotes_synthetic.sqlite database contains generated data for testing -- no real user data or copyrighted book content is included. Book titles and author names used in examples are references for illustration only; no copyrighted text from those works is reproduced.
MIT -- Chris Campbell
KoNotes -- Made with love for the Kobo community.