Skip to content
qcode-uni-aPublic

About

Papers, for us. A self-hosted research library for teams: shared collections and notes, search by meaning across full texts, and an MCP server so any AI assistant can search and cite your library

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

paperus

CI Coverage Release Licence: Apache-2.0 PyPI npm Docker image Firefox add-on Demo

Papers, for us. A research library for groups, on your own server, read with the AI assistant you already use. Made by scientists, for scientists.

Homepage and demo (a recorded library to look around in: uploads, changes and search by meaning don't work there).

paperus in the browser: a group's library with papers, tags and collections

Status: beta (0.1.5), in a pilot. It works, with private papers and nested groups, but the data format may still change. See the changelog for what is there and what is missing.

The idea

  • AI first, on your terms: no built-in chatbot and no AI vendor. Any assistant (Claude, ChatGPT, a self-hosted or local model) connects through an MCP server, sees only what the user may see, cites the exact passage and asks before it changes anything: retrieval-augmented generation (RAG) over your own papers. paperus finds, checks and keeps track; the assistant does the thinking.
  • One library for the group, on your own server with your organisation's login (OIDC), groups inside groups, plus private space for each member.
  • Semantic search: search by meaning across the full text of every paper, note and annotation, together with keyword search, computed on the server with small open models (and reranked, on a GPU).
  • Figure search: figures and tables are found by their captions and shown in the results, opening the paper at the figure. With a GPU, multimodal search finds them by what they show too (a heatmap with a ring, two crossing bands): one switch for the administrator.
  • PDFs that fit your phone: fluent mode turns two columns into one, figures whole, highlights and notes as on the page.
  • Preprints that get published: the published version is found by itself, and cited from then on.
  • Apps for Linux, Windows and macOS, also offline: your libraries in a window of their own. Offline, the app opens its copy: papers kept with their PDFs ("Keep offline on this device", for a paper or a whole collection), annotations and notes made on the train sent when you are back. Or a library on the computer itself, without a server. Notifications, PDFs added with "Open with"; installers on each release. Android and iOS are planned.
  • Sources first: papers, lecture notes, meeting notes and their versions, with notes and annotations attached to them. Not a general notes app.
  • No lock-in: full export of files, BibTeX/CSL-JSON, Markdown notes and annotations at any time.
  • And the rest: import, export, OCR, tags, collections, smart collections, annotations, notes, duplicates, open-access PDFs, authors with ORCID, references and cited-by, similar papers, browser extension, backups, monitoring.
  • Free and open source, forever: Apache-2.0, no paid tier, no account with us; your server, your data.

Installation

Needs a Linux machine (x86-64) with Docker Engine and its Compose plugin (docker compose), about 4 GB of RAM (the model for search by meaning takes 2–3 GB), and HTTPS out to the internet (the model, metadata services; behind a proxy, see operations).

  1. Download deploy/compose.yaml and deploy/example.env into a new folder; rename example.env to .env.
  2. In .env, set the folders for files, database, backups and models (CONTACT_EMAIL, which metadata services ask for, can also be given later under Administration → Settings → Server). Random secrets for DB_PASSWORD and ML_TOKEN in one go:
    sed -i "s/^DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -hex 16)/; s/^ML_TOKEN=.*/ML_TOKEN=$(openssl rand -hex 32)/" .env
  3. Put a reverse proxy with HTTPS in front of port 8000, on a (sub)domain of its own; examples for Caddy and nginx are in operations. The port is open to this machine only; with the proxy on another one, set PAPERUS_PORT=8000. Folders on a network share must belong to uid 1000 there (the containers' user).
  4. Start: docker compose up -d. The ML service downloads its models when it first needs them (the recommended search model about 300 MB).
  5. Open paperus at its address (the proxy's) in the browser: create the administrator account, or restore a backup found in the backup folder (for moving to a new server). Check the address under Administration → Settings → Server ("Public address"). The library page then lists the first steps: backups, adding people, the browser extension, connecting an AI assistant.
  6. Optional: people log in with your organisation's accounts (OIDC login), see operations.

Just trying it out, without HTTPS? Open http://localhost:8000 on the same machine; from another computer on the network, set COOKIE_SECURE=false in .env first (the login cookie is otherwise sent over HTTPS only).

Backups of the database run every night from the start; add the files (the PDFs), or change when, under Administration → Backups. They go into BACKUP_LOCATION on another disk; restoring is described in operations. To update (see operations): docker compose pull && docker compose up -d; the database is brought up to date as the server starts.

Browser extension (Chrome, Firefox): one click saves the paper you are reading, with its PDF, or the PDF you have open; right-click it to save to another owner; on arXiv, a button next to each paper. For Firefox on addons.mozilla.org; for Chrome and Edge, until it is in their store, load it from the release's zips: see extension/README.md.

Documents

Document Contents
Architecture Components, stack, data model, scaling
Ingestion Adding items, metadata, PDFs, browser extension, versions, other sources
Export Taking everything home: a SQLite database and the files, in zips; importing it back
Search Chunking, embeddings, hybrid search, deduplication across versions, pgvector
Permissions Who may do what with papers, tags, collections and groups
AI integration MCP tools, permissions, the AI inbox, skill draft
Apps One app for computers and phones (begun), a library on one's computer, offline sync
Operations Hosting at the university, data protection, lessons from similar projects
Decisions Decisions made so far and open questions
Pilot Pilot plan and questions for testers

Planned work, ideas and bugs are in the issues; labels show the area and whether a point still needs discussion.

Development

Needs Docker, uv and Node.js.

docker compose up -d                       # Postgres with pgvector on localhost
cd server
uv run alembic upgrade head
uv run paperus user create alice --admin   # asks for a password
uv run paperus serve --reload              # API on http://localhost:8000
uv run paperus worker                      # background jobs, in a second terminal

cd ml                                      # machine learning service (search by meaning)
PAPERUS_ML_CACHE_PATH=../data/model-cache uv run paperus-ml
# or in a container, with the same model folder:
# docker compose --profile ml up -d

cd web
npm install
npm run dev                                # website on http://localhost:5173
npm run api                                # after API changes: regenerate the client

To try it from a phone on the same network: start the API with PAPERUS_COOKIE_SECURE=false (plain HTTP outside localhost) and the website with npm run dev -- --host 0.0.0.0, then open http://<this PC's IP>:5173.

npm run build writes the website to web/build, which paperus serve serves on its own port as well. Checks: uv run pytest, uvx pre-commit run --all-files.

The app for computers (Tauri, Rust) is in app/ (app/README.md); its installers for Linux, Windows and macOS are on each release. The homepage is in site/, its demo in e2e/demo/ (README).

Licence

Apache-2.0, see LICENSE. Bundled fonts and libraries keep their own licences, see THIRD_PARTY.md.

About

Papers, for us. A self-hosted research library for teams: shared collections and notes, search by meaning across full texts, and an MCP server so any AI assistant can search and cite your library

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages