MyLibrary

MyLibrary is a small, self-contained research-paper library with a local web interface, CLI, and optional private Telegram bot.

It can add papers by URL or identifier, discover metadata, download available PDFs, track HTML articles by their original URL, cache lightweight visual previews, track notes and tags, save PDF highlights, record reading status, refresh citation counts, and arrange publications in an added-time timeline.

All persistent state stays in this clone under data/. Telegram credentials, when used, stay under api_keys/. MyLibrary does not write application data to ~/.local.

Requirements

• Python 3.10 or newer
• Linux, macOS, or another environment capable of running Python
• systemd only if you want the optional background service
• Internet access for metadata, PDFs, citations, and Telegram

Quick start

git clone https://github.com/liusida/MyLibrary.git
cd MyLibrary
python3 -m venv .venv
.venv/bin/pip install -e .
./mylibrary init
./mylibrary run

Open http://127.0.0.1:8765. run starts the web interface and daily citation updater. If Telegram credentials are present it also starts the bot; otherwise Telegram is quietly disabled.

To run only the web interface:

./mylibrary serve

CLI

# Add by title, arXiv URL, PDF URL, DOI, arXiv ID, PMID, or another paper URL
./mylibrary add "Attention Is All You Need"
./mylibrary add https://arxiv.org/abs/1706.03762
./mylibrary add https://arxiv.org/pdf/1910.05653
./mylibrary add https://alignment.anthropic.com/2025/automated-auditing/

./mylibrary list
./mylibrary remove PAPER_ID
./mylibrary search "attention"
./mylibrary show PAPER_ID
./mylibrary notes PAPER_ID "My note"
./mylibrary tag add PAPER_ID Classic
./mylibrary done PAPER_ID
./mylibrary citations update
./mylibrary thumbnails --force

Use a full paper ID or an unambiguous ID prefix. Run ./mylibrary --help or ./mylibrary COMMAND --help for all commands and options.

Exact arXiv IDs and URLs are resolved from the paper's arXiv abstract page; MyLibrary does not call the legacy arXiv API. Title-only discovery uses alphaXiv's public search index, then resolves the selected result through its arXiv abstract page. alphaXiv is optional: exact URLs and identifiers continue to work if it is unavailable.

Web interface

The default page is an added-time timeline. Paper cards can display Page 1 or Figures 1–3 alongside tags, citation counts, notes, and a selectable reading marker. The metadata page lets you choose a PDF timeline preview. The built-in PDF reader supports persistent highlights, zoom, and highlight removal. HTML publications remain metadata-only records, cache only a thumbnail image, and open on their original website.

The web interface has no authentication. It binds to 127.0.0.1 by default. Do not expose it directly to the internet; use only a trusted network or an authenticated reverse proxy.

Telegram bot

Telegram is optional. Create the private configuration directory and put the BotFather token on the only line of api_keys/.telegram_bot:

mkdir -p api_keys
chmod 700 api_keys
editor api_keys/.telegram_bot
chmod 600 api_keys/.telegram_bot

Send a message to the bot, then discover your numeric Telegram user ID:

./mylibrary telegram --discover-users

Put each allowed numeric ID on its own line in api_keys/.telegram_users:

123456789
987654321

chmod 600 api_keys/.telegram_users
./mylibrary telegram

Both files are ignored by Git. Bot activity is recorded in data/logs/telegram.log.

Background service

On Linux with systemd, MyLibrary can generate a service using the current clone path and a selected non-root account. Preview it before installing:

./mylibrary service print --user "$USER"
sudo ./mylibrary service install --user "$USER"
./mylibrary service status
./mylibrary service logs --follow

The safe default is 127.0.0.1:8765. To make the UI reachable on a trusted local network:

sudo ./mylibrary service install --user "$USER" --host 0.0.0.0 --port 9999

Uninstalling the service does not delete papers, metadata, or API keys:

sudo ./mylibrary service uninstall

Storage and backup

data/
├── library.sqlite3   # metadata, tags, notes, highlights, and status
├── files/            # content-addressed PDFs
├── thumbnails/       # Page 1 and Figure 1–3 previews
├── cache/
├── logs/
└── tmp/

Back up the entire data/ directory to preserve the library. Use --data-dir PATH on CLI commands to select another storage directory.

Development

.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -q
./mylibrary doctor

MyLibrary is released under the MIT License.