Seamlessly sync your KOReader highlights and notes to Obsidian via Unearthed.app (Unearthed Online) or via Unearthed Local (local app). This plugin is a simple one, it's just here to get those highlights and notes off your device and sync them to places that you might want them. So that they aren't locked and lost on whatever device you're using. So that you can combine them with highlights and notes from other sources too. Unearthed can also sync Kindle highlights automatically and merge them with your KOReader highlights. This plugin enables you to maintain an organised collection of your reading insights in one place. This is accomplished by using Unearthed (online or local version) as a middle man. Most of the software is open source, so please inspect the code or even run it yourself if you like.
After the setup is complete, you will not need to physically plug in your KOReader device to perform a sync! ( ͡° ͜ʖ ͡°)
There are 2 ways to sync using Unearthed. Unearthed Local (one time payment), and Unearthed Online (ongoing subscription)
Note: Unearthed Online can also facilitate syncing to places beyond Obsidian. You can also just sync to Unearthed.app or the Local app and digest the knowledge there if you like.
So far, only tested with:
- KOReader version: 2025.04
- On a Boox Palma
- Sync highlights and notes from KOReader to Obsidian (and other places)
- Daily Reflections built from your highlights and notes, emailed to you.
- Merge highlights from both Kindle and KOReader for the same books
- Tag books, highlights and notes to connect ideas
- AI-powered tagging and idea extraction (if you choose to use it)
- Customisable obsidian templates for book and highlight formatting
- Smart sync that only adds new highlights
- Interactive graph view of books, highlights and tags
- Customise how books and highlights appear in Obsidian
- Receive daily reflections appended to your daily obsidian note
- See Unearthed Obsidian Github for more
- Unearthed Local (one time purchase) app installed, OR a paid Unearthed.app account
- KOReader installed on your device
- Obsidian connected to Unearthed. Follow the instructions here: Unearthed Obsidian Github
- Download Unearthed Local from unearthed.app and install it on your computer
- Go to Releases and download the zip file for latest release
- Connect your device via USB and navigate to
koreader/pluginsfolder - Unzip the file into
koreader/pluginsfolder, making sure that the parent folder still remains (e.g.,koreader/plugins/Unearthed.koplugin) - On your device, restart KOReader and then go to tools and see if 'Unearthed' is listed as a menu item. If it is not listed there, go to
Tools → MoreTools → Plugin Managementand make sure 'Unearthed' is enabled - Open
Tools → Unearthed → General Settingsand keep it open. SelectBook Locationand input the path to the folder that holds your books along with your books' metadata. This must be the absolute path. You can find it by navigating your device's file system from within the KOReader app. Then look at the top of the app under the word KOReader to see the actual path. Here's an example for an Android device/storage/emulated/0/Books - Ensure your E-reader and computer are on the same network.
- Open the Unearthed Local app on your computer and go to Settings. Create a secret under API Endpoint (type anything you like) - Don't forget to press save. Type the same secret into the KORreader plugin settings under
Tools → Unearthed → Local Settings → Secret - Open the Unearthed Local app on your computer and copy the API Endpoint into the KOReader plugin on your E-reader, under
Tools → Unearthed → Local Settings → Local URL - Exit settings, and go back into
Tools → Unearthed → Send Booksand then wait - Wait until a confirmation message appears. This may take a while if you have many books. Open the Unearthed Local app on your computer scroll down to the Database section to see if the books have arrived. You may need to refresh the data within the app.
- Create a paid account on unearthed.app
- Go to Releases and download the zip file for latest release
- Connect your device via USB and navigate to
koreader/pluginsfolder - Unzip the file into
koreader/pluginsfolder, making sure that the parent folder still remains (e.g.,koreader/plugins/Unearthed.koplugin) - On your device, restart KOReader and then go to tools and see if 'Unearthed' is listed as a menu item. If it is not listed there, go to
Tools → MoreTools → Plugin Managementand make sure 'Unearthed' is enabled - Open
Tools → Unearthed → General Settingsand keep it open. SelectBook Locationand input the path to the folder that holds your books along with your books' metadata. This must be the absolute path. You can find it by navigating your device's file system from within the KOReader app. Then look at the top of the app under the word KOReader to see the actual path. Here's an example for an Android device/storage/emulated/0/Books - Login to Unearthed.app, go to settings and create an API Key, name it whatever you like. Copy it immediately and paste it into API Key in the KOReader Unearthed plugin settings, under
Tools → Unearthed → Online Settings - Login to Unearthed.app, go to settings (general) and press the copy button next to 'User ID' and paste it into
User IDin the KOReader Unearthed plugin settings, underTools → Unearthed → Online Settings - Exit settings, and go back into
Tools → Unearthed → Send Booksand then wait - Wait until a confirmation message appears. This may take a while if you have many books. Go to Unearthed.app books page and confirm that Unearthed received your books and highlights
- After you have your KOReader syncing to Unearthed.app, Follow the instructions here to send that data to Obsidian: Unearthed Obsidian Github
- Book Location: The folder that holds your books along with your books' metadata. Only one location is supported at this time
- API Key: A unique Unearthed API key for authentication
- User ID: Your unique User ID
- Auto-sync: Enable/disable automatic syncing of highlights. When enabled, the plugin will send your highlights to Unearthed.app when you first open KOReader, once per day
- Book Location: The folder that holds your books and their metadata (.sdr directories). Only one location is supported.
- API Key: Your Unearthed Online API key for authenticating uploads.
- User ID: Your Unearthed Online user ID (used together with the API key).
- Auto sync on startup: Enable/disable a daily sync with Unearthed Online when KOReader is opened.
- Auto sync hourly: Enable/disable hourly sync with Unearthed Online while KOReader is running.
Local (Unearthed Local)
- Local URL: URL of your Unearthed Local instance (e.g.
http://192.168.x.x:port). Re-check if your computer IP changes. - Local Secret: Shared secret used to authenticate with Unearthed Local.
- Auto sync on startup (Local): Enable/disable a daily sync with Unearthed Local when KOReader is opened.
- Auto sync hourly (Local): Enable/disable hourly sync with Unearthed Local while KOReader is running.
- Highlights not syncing: This plugin currently only works for books in one location. Make sure your books live within a single folder on your device
- Latest Highlights are missing: KOReader doesn't update the metadata until you exit the book. Before forcing a sync, make sure that you have closed all books first
- Plugin not loading: Restart KOReader and check Tools → MoreTools → PluginManagement
- Settings not saving: Ensure you have write permissions in the plugin directory
- Sync errors: Check the debug log for detailed error messages
If you encounter any issues:
- Check the debug logs in KOReader's plugin directory
- Verify your API key and user ID are correct
- Ensure you have an active Unearthed Online account, OR have Unearthed Local installed
- Contact through unearthed.app
- Visit GitHub repository
I welcome contributions! The plugin is open source, and I encourage community participation. Feel free to:
- Submit pull requests
- Report issues
- Suggest new features
- Improve documentation
This project is open source