Paper Mate

A local PDF reader for research and study.
Read, mark up, and reopen papers with your notes still where you left them.

Overview

Paper Mate is a local web app for keeping research PDFs, metadata, folders, and annotations in one place. The browser handles the library, reader, and annotation UI. A small FastAPI server saves files and annotations to disk.

The current version focuses on library management and PDF reading: table view, folders, recent and starred papers, page navigation, annotation tools, and an annotation bank. Local AI-assisted reading is planned later. For now, Paper Mate keeps private PDFs local and makes it easy to return to a paper with your notes still in place.

Library	Reader

Features

🗂️ Library

• Table view with title, authors, venue, year, folder, date added, and DOI
• Folder-based organization with uncategorized and trash views
• Recent and starred documents
• Resizable metadata columns
• Local library stored under ~/.paper-mate

📄 Paper reading

• Local PDF opening
• Page controls and table of contents
• Smooth scroll, zoom, and pan
• Stable pages while annotations are shown or hidden

✍️ Annotation

• Highlight, underline, pen, memo, comment, and box tools
• Quick box for choosing tools after text selection
• Recolor, move, resize, delete, undo, and redo
• Hide or show all annotations

💾 Review and storage

• Annotation Bank with click-to-jump
• Local autosave and restore for PDFs and annotations
• Original PDF left untouched

🔭 Planned

• Footnote and reference previews
• Author and venue grouping
• Export with annotations
• Local AI chat through CLI agents
• Click or drag a paper region into chat context

Quick Start

Run with Docker

git clone https://github.com/Cotidie/paper-mate.git
cd paper-mate
docker compose up --build

Open http://localhost:8000 after the container starts. Your library is stored in ./.paper-mate (see .env.example to point it elsewhere).

That command runs the app alone, which is the whole product: reader, library, annotations, and fast local structure extraction.

Service	What it is	Started by	Size
paper-mate	The app: API, reader UI, library storage, fast local structure extraction.	docker compose up	small
structure-hybrid	Optional higher-fidelity structure backend (Docling models). Recovers section headings the local extractor misses.	docker compose --profile hybrid up	multi-GB

The hybrid backend sits behind the hybrid Compose profile, so a plain up never builds or downloads its multi-GB image. To run it:

docker compose --profile hybrid up --build   # `--profile` belongs to `docker compose`, not to `up`

Then switch the toggle at the bottom of the Library panel to Hybrid. The app probes the server first and only adopts hybrid if it answers, so with the profile off (or the server still loading its models) everything keeps working in local mode, and the toggle says why. Papers already imported keep the structure they were imported with.

Pass the profile to down and build as well: docker compose down alone leaves a running structure-hybrid container up, because a profile-gated service is invisible to commands that do not enable its profile.

GPU. structure-hybrid is built with GPU-capable PyTorch by default; on a host with no NVIDIA GPU, set PAPER_MATE_TORCH_VARIANT=cpu in .env and rebuild it (docker compose --profile hybrid build structure-hybrid) for a much smaller image. To actually use a GPU, install the NVIDIA Container Toolkit (the GPU driver alone is not enough: the driver makes the GPU work on the host, the toolkit is what lets a container see it) and layer the GPU overlay on:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml --profile hybrid up

Or set COMPOSE_FILE=docker-compose.yml:docker-compose.gpu.yml in .env once, and every docker compose command in the repo picks it up. The structure-hybrid log then reports Accelerator: CUDA instead of Accelerator: CPU (no GPU detected). Without a GPU it runs on CPU: correct, just slower.

Develop locally

Run the backend and frontend in separate shells:

cd server && uv run uvicorn app.main:app --reload --port 8000

cd client && npm install && npm run dev

Open the Vite URL shown in the terminal, usually http://localhost:5173.

Hybrid structure extraction needs its server running too. On a host it is a third shell (uv run --project hybrid opendataloader-pdf-hybrid --port 5002 --no-ocr); the backend finds it at http://localhost:5002 by default.

Perfect For

• Researchers who read papers every day.
• Graduate students marking lecture notes, papers, and drafts.
• Anyone who wants PDF annotation without uploading papers to a cloud service.
• Readers who prefer local files, local annotations, and a quiet interface.

License

Paper Mate is released under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE. It bundles PyMuPDF for metadata extraction, which is AGPL-3.0; the combined distributed work is therefore AGPL-3.0. Running Paper Mate locally for personal use never triggers the license's distribution obligations.

Acknowledgement

Paper Mate uses PDF.js for PDF rendering, React and Vite for the client app, FastAPI for the local backend, Zustand for client state, and perfect-freehand for pen strokes.

The product shape comes from the BMad planning artifacts in this repository, especially the v1 viewer and annotator spec.