Turn your Kobo highlights and reading data into structured, readable insight.
Live Demo · Try It · Features · Example Insights · CLI · Web UI · Roadmap
No cloud required. No account. No tracking.
Your reading data stays on your machine.
Kobo 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 Kobo gives you
|
What KoNotes gives you
|
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. KoNotes makes it visible.
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 | Your real Kobo database |
| Kobo USB detection | Not available | Full support |
| AI features | Not available | Full support with pip install '.[ai]' |
| Privacy | Runs on Streamlit Cloud | Fully offline, nothing leaves your machine |
| Export | View only | Markdown, JSON, HTML, text, static site |
| 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.
Want to explore first? Try the hosted demo -- no install needed.
With a Kobo connected via USB:
git clone https://github.com/texasbe2trill/KoNotes.git && cd KoNotes
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
konotes detect-device # find your Kobo
konotes parse <path> # parse the database
streamlit run app/app.py # launch the dashboardWith an exported annotation file:
konotes parse my-annotations.html
konotes export my-annotations.html -f markdown -o ./outputNo Kobo on hand? A synthetic test database is included so you can try KoNotes immediately:
konotes parse docs/KoNotes_synthetic.sqlite
streamlit run app/app.py
# then upload docs/KoNotes_synthetic.sqlite in the browserKoNotes also works with any .html, .txt, or .md annotation export. See Supported Inputs.
| 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 |
|
|
|
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.
# Web UI
streamlit run app/app.py
# CLI
konotes --help| Format | Extensions | Source | Priority |
|---|---|---|---|
| KoboReader SQLite | .sqlite, .db |
Kobo device .kobo/ folder |
Primary |
| Kobo HTML export | .html, .htm |
Kobo app / device | Secondary |
| Kobo plain-text export | .txt |
Kobo app / device | Secondary |
| Kobo Markdown export | .md |
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.
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 six 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 ./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.
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 |
| Library | Browse all books with progress bars, shelf badges, and author/status filters |
| Book Detail | Per-book annotations grouped by chapter, with search, filtering, export, and full metadata |
| Annotations | Cross-book annotation search -- find any highlight by keyword |
| Activity | Reading sessions, progress distribution, annotation timeline, progress snapshots over time |
| Vocabulary | Every dictionary lookup from your Kobo, searchable and filterable by book, with frequency data |
| AI Insights | Insight Feed with 10+ categories, theme detection, clustering, similarity search, summaries |
Plug in your Kobo via USB and the app detects it. Or drag-and-drop any supported file.
pip install pytest
pytest tests/ -v358 passed
Tests cover every parser, normalizer, model, CLI subcommand, export format, SQLite telemetry extractor, AI insight pipeline, insight feed, and static HTML exporter.
KoNotes/
├── app/
│ ├── app.py # Streamlit entry point
│ ├── charts.py # Shared Plotly chart helpers
│ ├── assets/ # Logo, CSS
│ └── views/ # Overview, Library, Activity, Vocabulary, Insights, ...
├── models/ # Pydantic models (Book, Annotation, Session, Insight, ...)
├── parser/ # SQLite, HTML, TXT, Markdown parsers + device detection
├── services/ # Stats, exports, AI, embeddings, insight feed
├── utils/ # Text utilities, schema helpers
├── tests/ # 358 tests across 13 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 4 are complete. Phase 5 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)
- 358 tests
Phase 5 -- Future
- CSV export format
- Reading goals and streaks
- 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 (CSV, EPUB), UI improvements, reading goals, enhanced classification heuristics.
|
KoNotes is a local-first tool. Your reading data never leaves your machine.
AI features and network access:
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.
- Streamlit -- the framework 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 respect open data
- Every reader who highlights, 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.
