ALMa — Another Library Manager

A personal academic literature monitor that runs on your own machine. ALMa watches OpenAlex and Semantic Scholar for new work from the authors and topics you follow, builds a local SQLite library of the papers you save, and uses SPECTER2 embeddings to surface related work you haven't seen yet. Nothing about your reading list leaves the box you put it on.

Early preview. Every surface works end-to-end, and first launch walks you through setup with a guided tour. Expect rough edges at the margins; public testing welcome. See the latest release for the current version.

Full documentation: https://costantinoai.github.io/alma-library-manager/

The surfaces

ALMa is organised the way the work is: Explore what is new, Manage what you keep, Control how it runs.

Explore

• Home — the daily brief. What arrived since midnight, what is waiting in your Inbox and reading list, and a few Signal Lab rounds to tune the ranker while you drink your coffee.
• Feed — a chronological inbox of new publications from the authors, topics, venues and queries you monitor.
• Discovery — papers related to your library that the Feed never saw, ranked by one auditable scorer. Every suggestion can show you exactly what made its score.
• Map — the whole corpus laid out by meaning. Lasso a region to see what lives there and adopt it as a direction.

Manage

• Authors — the researchers you track, their identities merged and deduplicated, plus suggested authors whose work overlaps with yours.
• Library — every paper you've saved, with notes, ratings, tags, collections and a reading list; Analytics inside it charts how the library is spread across years, topics and journals.
• Alerts — scheduled digests of what matched while you were away.

Control

• Health — what the background jobs are doing, what is missing, and one-click repairs for the gaps.
• Settings — connections, ranking weights, AI provider, scheduling.

How ranking works

One ranker scores every paper, on every page, so a score means the same thing wherever you see it. It weighs ten independent families — semantic similarity, topic overlap, retrieval agreement, authors, terminology, recency, citation structure, your explicit feedback, your learned preferences, and venue — and a family with nothing to measure is dropped rather than counted as zero, so a paper with thin metadata is judged on what is actually known about it.

Every suggestion carries a full breakdown: click Why on any paper and the rows you see add up, exactly, to the score beside them — each one expandable to the raw measurements underneath. You can retune the weights in Settings → Discovery. See scoring formulas for the arithmetic.

Why ALMa

Staying current with the literature is really three jobs: keeping the papers that matter, watching for new work from the people and topics you care about, and finding adjacent papers you don't yet know exist. Those jobs usually live in separate tools — Zotero for the first, Connected Papers or Semantic Scholar for the third, scattered journal alerts for the second — and that separation is where most of the friction comes from.

The jobs also need each other. A recommender ranks better when it knows which papers you kept and which you dismissed. A watcher is more useful when it can up-weight authors that keep showing up in your saved work. ALMa puts all three on one local database so they inform each other — the library trains discovery, the monitors fill the feed, and discovery suggests what to monitor next.

Read the full vision & philosophy for the design principles and the lifecycle model the whole UI is built around.

Browser connector (Firefox)

Save the paper open in your browser straight into ALMa — like the Zotero connector. Grab the signed .xpi from the latest release and install it via about:addons → Install Add-on From File…. Full guide: browser connector.

Quick start

One line, any OS. The installer checks Docker, auto-detects your hardware (NVIDIA GPU / Raspberry Pi / generic CPU) to pick the right image, and starts ALMa with named Docker volumes so your library survives upgrades. Prerequisite: Docker installed and running.

Linux / macOS

curl -sSL https://raw.githubusercontent.com/costantinoai/alma-library-manager/main/setup.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/costantinoai/alma-library-manager/main/setup.ps1 | iex

Then open http://localhost:8000. To update later, re-run the same command — the installer detects an existing install and pulls the latest image; your data lives in named volumes, so nothing is lost.

Other ways to install: manual docker run, the three image flavors (:latest / :latest-gpu / :latest-lite), Docker Compose, auto-updates with Watchtower, and exposing ALMa on your LAN are all covered in the Docker guide. For a bare-metal Python install (development only — not recommended for everyday use), see the installation docs.

First use

ALMa is empty on first launch and opens a guided tour that walks you through the same three steps:

1. Add your OpenAlex API key. OpenAlex requires a free key (no signup beyond an email; ~30s at openalex.org/settings/api). Paste it into Settings → Connections and save. A Semantic Scholar key is recommended too — it keeps Discovery off the shared rate-limit pool.
2. Follow a few authors. Open Authors and add three to five researchers by name (an ORCID or OpenAlex ID also works). Each follow kicks off a background backfill of their recent papers — watch it run under Activity.
3. Wait one refresh. Once the backfills finish, the Feed surfaces new papers and Discovery recommends related work. Save, like, or dismiss as you go — every action teaches the ranker what you care about, and Home shows you what arrived while you were away.

Optional: import a BibTeX file or Zotero library from Library → Imports for much better Discovery seed material from day one.

Full walkthrough: first-run checklist.

Configuration

Most settings — Discovery weights, AI provider, clustering — live in the database and are tuned from the Settings page. The .env file holds secrets (API keys, Slack tokens) and a few deployment knobs. The full reference is in docs/reference/configuration.md, and backups covers keeping your library safe.

License

Licensed under PolyForm Noncommercial 1.0.0 — a source-available license. Personal use, academic research, hobby projects, and use by nonprofits or educational institutions are all permitted; commercial use is not. Attribution (the LICENSE file and copyright notice) must be preserved in copies and derivative works. See LICENSE for the full text.

Author

Andrea Ivan Costantino · github.com/costantinoai