What's Your Idea?
Store highlights and notes as KOReader-compatible sidecar files (.sdr/metadata.*.lua) alongside each book in the library, in addition to the database. The database becomes a queryable cache that can be rebuilt from the sidecar files, rather than the sole copy of annotation data.
Why Would This Be Helpful?
Right now, highlights and notes only exist in the database. If the database is lost or corrupted, all annotations are permanently gone with no way to recover them from the book files themselves.
This also makes cross-device reading painful. A user reading across the web reader, a Kobo running KOReader or just a user using KOReader, and a mobile browser has no way to get highlights from one surface to another — reading progress syncs via the existing KOReader endpoint, but highlights and notes do not travel at all.
There are two complementary improvements that together solve this:
1. Sidecar files alongside books
Write annotations to KOReader's .sdr/metadata.*.lua format alongside each EPUB in the library. This gives:
- Resilience — annotations survive a database loss and can be rebuilt by scanning the library folder, the same way book metadata already can be
- Grimmory → KOReader via OPDS — when a user downloads a book through OPDS, the sidecar travels with it and KOReader picks up the highlights on the device automatically, with no plugin or configuration change needed
- Portability — copy a book and its
.sdr folder anywhere and highlights come with it
2. Extend KOReader Sync endpoints to include annotations
This path applies to Kobo users who have KOReader installed on their device. The existing /api/koreader endpoints handle reading progress. Adding GET and PUT endpoints for annotations at the same base path would give users who already have KOReader Sync pointed at Grimmory full bidirectional highlight sync with no new configuration on their end — the same credentials and server URL they already use.
This is the only path for KOReader → Grimmory sync in the typical setup where the Kobo connects to a remote Grimmory server. OPDS is download-only and cannot push highlights back.
Users running the native Kobo firmware (without KOReader) would only benefit from the sidecar path above — highlights made in the native Kobo reader would not sync back to Grimmory.
Anything Else? (Optional)
The main design decision would be conflict resolution when annotations diverge between the sidecar and the database (e.g. a highlight made on the Kobo while offline, and a different highlight made in the web reader on the same passage). Last-write-wins is probably the pragmatic starting point.
Want to Help Out?
Yes! I'd love to help implement this
Have You Considered Any Alternatives? (Optional)
Calibre-web was the obvious comparison point but it stores annotations in its own SQLite database with the same fragility. KOReader's sidecar approach is the only self-hosted solution that actually keeps annotations with the book file.
Before Submitting
What's Your Idea?
Store highlights and notes as KOReader-compatible sidecar files (
.sdr/metadata.*.lua) alongside each book in the library, in addition to the database. The database becomes a queryable cache that can be rebuilt from the sidecar files, rather than the sole copy of annotation data.Why Would This Be Helpful?
Right now, highlights and notes only exist in the database. If the database is lost or corrupted, all annotations are permanently gone with no way to recover them from the book files themselves.
This also makes cross-device reading painful. A user reading across the web reader, a Kobo running KOReader or just a user using KOReader, and a mobile browser has no way to get highlights from one surface to another — reading progress syncs via the existing KOReader endpoint, but highlights and notes do not travel at all.
There are two complementary improvements that together solve this:
1. Sidecar files alongside books
Write annotations to KOReader's
.sdr/metadata.*.luaformat alongside each EPUB in the library. This gives:.sdrfolder anywhere and highlights come with it2. Extend KOReader Sync endpoints to include annotations
This path applies to Kobo users who have KOReader installed on their device. The existing
/api/koreaderendpoints handle reading progress. AddingGETandPUTendpoints for annotations at the same base path would give users who already have KOReader Sync pointed at Grimmory full bidirectional highlight sync with no new configuration on their end — the same credentials and server URL they already use.This is the only path for KOReader → Grimmory sync in the typical setup where the Kobo connects to a remote Grimmory server. OPDS is download-only and cannot push highlights back.
Users running the native Kobo firmware (without KOReader) would only benefit from the sidecar path above — highlights made in the native Kobo reader would not sync back to Grimmory.
Anything Else? (Optional)
The main design decision would be conflict resolution when annotations diverge between the sidecar and the database (e.g. a highlight made on the Kobo while offline, and a different highlight made in the web reader on the same passage). Last-write-wins is probably the pragmatic starting point.
Want to Help Out?
Yes! I'd love to help implement this
Have You Considered Any Alternatives? (Optional)
Calibre-web was the obvious comparison point but it stores annotations in its own SQLite database with the same fragility. KOReader's sidecar approach is the only self-hosted solution that actually keeps annotations with the book file.
Before Submitting