Insurgently

Technical details

Library Hub keeps your book collection as notes, in step with the servers your books live on. This is how it's built.

It runs its model work through Model Hub and asks Topic Map which books share topics. It holds no keys, names no models and keeps no vectors of its own. Everything below is in the code, and anything still to come is marked Soon or Later.

All the pagesDeveloper docs →Agent docs →

The shape of it

Your books stay where they are, in Calibre or a book server. Library Hub reads them into notes, one per book, and every change to your notes or to Calibre is previewed first, logged and undoable. Model work goes through Model Hub and topics come from Topic Map, so neither lives in this plugin.

  1. Sources

    Calibre's Content Server or its metadata.db; OPDS servers such as Komga, Kavita and Calibre-Web; Audiobookshelf; Hardcover; Readwise for highlights

  2. read

    Sync

    Works out what changed, shows it to you, then writes it. Each run can be undone.

  3. write

    Your vault

    A note per book, a note per shelf, covers, authors, series and highlights, all under Books/

  4. work on

    Summaries · Shelves · Reader and review

    A one-page summary and chapter notes, through Model Hub. Suggestions, health and living shelves, through Topic Map. Read the book file; check its record against the book.

Written down, in your vault

  • notes/runs/: every sync and summary run, for Undo
  • queue/: changes waiting to go to Calibre, and what each one did
  • timelines/: how long each step of a run took

All three sit in the plugin's folder in your vault's config folder. Passwords, tokens and keys are in Obsidian's secret storage.

Where books come from

Each source is read through Obsidian's own request function. Calibre is the one Library Hub writes back to.

Calibre
The Content Server over HTTP, read and write: metadata, covers, adding and removing books. Without a server, Library Hub reads your library's metadata.db directly, read-only, through sql.js.
OPDS
Any OPDS catalog, read-only. That's how Komga, Kavita and Calibre-Web come in.
Audiobookshelf
Its REST API, read-only: your library and your listening.
Hardcover
Its GraphQL API, read-only.
Readwise
Highlights only, read-only.
Look-ups
Open Library and Google Books, with your own key, for checking a book's record.

A summary, step by step

What happens between asking for a book's summary and the summary landing in its note.

  1. Price it. The cost is estimated through Model Hub before anything is sent, and the run waits for your OK.
  2. Read the book. The text comes from the EPUB, AZW3 or MOBI file through foliate-js, or from a PDF through Obsidian's own PDF.js.
  3. Write the page. The library-hub.summarize role reads the whole book in one call when it fits the model's context. When it doesn't, it writes a digest per chapter, then one page from the digests. Chapter notes are one call per chapter on library-hub.chapters.
  4. Check the quotes. A quote stays only if the text library finds it word for word in the book. Any other is dropped.
  5. Write it down. The summary goes in the book note's own ## Summary section, marked with a hash so Library Hub knows it's still its own. If you've edited that section, your text moves to ## Orphaned sections rather than being overwritten. Chapter notes go in a folder beside the book note.

Spending stops early. A call billed well above its listed price stops the run. Every call is credited to Library Hub in Model Hub's ledger.

Shelves and Topic Map

A shelf is a note in Books/Shelves, and a book lists its shelves in its shelves property. A Base shows each shelf's members, so a shelf works in Obsidian with Library Hub off.

Library Hub keeps no vectors of its own. Topic Map learns the topics each book covers, and Library Hub asks it for similar books, the shelves that suit a book, new shelves to suggest, a shelf's health and where it could split, and shelves that overlap. When new books arrive, Topic Map says where each belongs and Library Hub offers the move for you to review. That's a living shelf.

Each call to Topic Map is checked on its own, so an older Topic Map turns off only the features it can't serve, with a line saying which. Indexing your library is priced first and waits for your OK. Without Topic Map, shelves match by words, with BM25 search.

The reader and review

The reader

Opens EPUB, KEPUB, AZW3, MOBI and PDF files from any source. A content security policy blocks scripts, and images and fonts load only from the book, so opening a book never reaches the web. Highlights keep the words around them, so they find their place again.

Metadata review

A record counts as checked only when its ISBN is printed in the book, or its title matches the title page with an author in common. Anything else becomes a proposal for you to look at. What you confirm goes to Calibre one change at a time, each checked against what was there first, and each undoable.

Tools and the API

Library Hub registers its model jobs and its tools with Model Hub. You choose the models for each job there, and coding agents reach the tools through Model Hub's MCP server.

Roles
13, from reading a title page (quick) to researching a book on the web (research). Each names a tier you can change.
Tools
21: 12 that read (find books, list shelves, a shelf's members, a PDF's text, estimates) and 9 that write (add to a shelf, create, rename, merge and delete shelves, summarize a book, undo). Reads can be sent again safely; each write returns a handle that undoes it.
Estimates
A write that costs money has an estimate tool, and its estimate is what the approval dialog shows.
The API
Other plugins find Library Hub with getLibraryHub and onLibraryHubReady, and hear about changes through library-hub:books-changed. The calls cover books, book text and chapters, shelves, summaries, jobs and undo.
// wanted: the API version your plugin was built for
const found = getLibraryHub(this.app, wanted);
if (!found.libraryHub) return new Notice(found.message);
const ids = await found.libraryHub.shelfMembers('coyote-tales');
Developer docs →

Shared libraries

The same packages the rest of the family uses, published under MIT.

obsidian-ui
The family design system: every panel, dialog and setting is built from its named controls.
text
Finds a quote in a book word for word, and finds a highlight's place again after the text moves.
retrieval
BM25 search, for matching books to shelves by words.
Library releases ↓

How it's tested

Four suites, and a set of cards that say what a person is trying to do, each one linked to the test that proves it.

Unit
About 1,500 Vitest tests across 138 files.
Integration
Run by hand against real servers and accounts: Calibre, Audiobookshelf, Hardcover, OPDS and Readwise.
End to end
53 WebdriverIO specs against a real, sandboxed Obsidian, with real builds of Model Hub and Topic Map beside it. They run in Docker under Xvfb, so no window opens on anyone's screen, and one variant runs a real Calibre server.
Journeys
10 jobs, 30 journeys and 201 scenario cards. 198 scenarios link to a test, and a check fails on a gap or a broken link.
API
The public API's docs are generated, and CI fails when they're out of date.

The pages

Each part above has its own section with the detail. Developer docs are for people building on Library Hub; Agent docs are the same knowledge for coding agents.

Technical roadmap

Library Hub came out with the other two plugins, since the three call each other. Soon is the next release; Later is after it. Nothing has a date.

Soon

  • Map layers. Library Hub's shelves, reading status and covers as layers on Topic Map's library map, and a lasso that makes a shelf.
  • Ask a book. Answers about a passage, with word-for-word quotes checked against the text, saved under the highlight.
  • Kobo highlights. A Kobo source that writes into each book's highlights note.
  • Shelves in Calibre. In Calibre, a custom column and virtual libraries, written through the write queue with a dry run and undo.
  • A stable API. API 1.0, with an event when shelves change.

Later

  • A tidier library. Series gaps, and a metadata sweep against the web that you review.
  • Writing back. Status, rating and dates to Hardcover, and listening progress to Audiobookshelf.
  • Audiobook sources. Several audiobook providers as sources, matched to the same books and notes.
  • Listen and export. Summaries read aloud, voice notes on highlights, and EPUB export for Calibre.
  • A full reader. A reader built on the reading view, with notes, shelves and Topic Map's topics beside the text, and routes through the library.
  • Mobile. The notes, shelves and reading list on a phone or tablet.

Library releases

The shared packages Library Hub is built on, newest first. Each release has its own page, and the same notes go on GitHub.

  • @insurgently/obsidian-ui 0.4.0The design system: tokens, layout classes and the named controls.
  • @insurgently/text 0.6.2anchorsIn: find many spans of one text in a single pass.
  • @insurgently/retrieval 0.1.0The first version: tokenizing and BM25 search.

Getting involved

The source is public, under MIT. CONTRIBUTING.md lists the checks a pull request passes: lint, typecheck, unit tests, the API docs check, and end to end for anything that touches Obsidian.

It stands on other people's open-source work: foliate-js for reading books, sql.js for Calibre's database, fast-xml-parser for OPDS, and Open Library's records. What I've built for the family goes back out as the shared libraries above.

Get involved, for the whole family →

Join

One list for everything here: an email when a plugin ships, plus the posts I write about these projects on brianspringer.com.

Want to help build this, or join the co‑op? Email me about joining →

Insurgent Methods is where we build at a different scale, to take on the biggest problems.

API package
@insurgently/library-hub-api, on npm
Needs
Obsidian 1.13.1, desktop
License
MIT