PaperLab

PaperLab

[](https://github.com/khannoussi-malek/PaperLab/stargazers) [](https://github.com/khannoussi-malek/PaperLab/releases/latest) [](LICENSE) [](https://www.linkedin.com/company/os-paperlab)

Website · Download · ⭐ Star it to get new releases in your GitHub feed · Follow on LinkedIn for a weekly breakdown of how one feature works

PaperLab is a research reading tool that runs on your own machine. You drop in PDFs, read them, highlight passages, and write notes that stay attached to the exact spot they came from. You can ask a paper questions and get answers that cite the passages they used, then keep the useful parts as notes.

The note is the main thing in PaperLab, not the chat. Anything an AI wrote is stored apart from what you wrote and is always marked as AI in the interface.

What you can do

Build a library

• Upload PDFs. A background worker extracts the text, splits it into sections and chunks, and indexes it for search.
• Find papers by title, DOI or arXiv ID with Find papers. It asks every paper source you turn on in

Settings → Paper sources at once (arXiv, Crossref, CORE, Unpaywall and Semantic Scholar are free; OpenAlex can cost money and stays off until you tick it), shows one list with the sources that found each paper, and adds one in a click when a free PDF exists (arXiv, a repository or an open-access publisher). A paper with no free copy links to its page, so you can download it yourself. Nothing gets past a paywall.

• Hover a paper in the list to preview its first page and details.
• With OpenAlex ticked in Settings, fill in each paper's title, authors, year, venue and topics from

OpenAlex, and correct any of them by hand with Edit details. Your corrections are kept when a paper is processed again.

• A retracted paper shows a banner at the top of the reader that can't be dismissed.
• Manage models in Settings: add connections and keys, test them, choose which models chat lists and the

default, pull and delete Ollama models with live progress. Keys stay in your local database and are never sent back to the browser.

Group papers into workspaces

• Group papers into workspaces (a paper can be in several), see all their notes in one place, and chat with a whole

workspace: answers cite passages from its papers and your notes.

Read and highlight

• Read in a PDF.js reader with zoom, in a light, dark or system theme. The page itself stays white.
• Select text to highlight it in one of five colours, or a custom one, and add a note if you want.
• Hover a highlight to see, edit, recolour or delete its note in place. Right-click it for the same actions and "Copy quote".
• Resize the side panel by dragging its edge. It remembers the width.

Follow a citation

• Hover a numbered citation the PDF links, like [51], to see which paper it is: its details once the paper's

references are looked up, with Open in PaperLab when it's in your library or Add to library when a free PDF exists, and otherwise the entry exactly as the reference list prints it. Click it to jump to that entry, and Back to page N takes you back to where you were. Tab reaches every citation too.

See how your papers connect

• Open the Graph page to see how your papers connect: what cites what, papers in the same workspace, a note

anchored on two of them, a shared author or topic, and papers that simply read alike — each a layer you can switch on or off. Similar content comes from the same embeddings search uses. Click a paper to focus it and list its connections, and draw your own link between two papers with a label like "builds on". Look at it five ways: the 2D map, a 3D one you can turn around when clusters overlap, a Matrix of exactly which papers connect and how (a table a screen reader can read cell by cell), a Timeline of what builds on older work, by year published or date added, and Rings showing how many links away everything is from one paper.

Follow the references

• Open a paper's References tab to see what it cites and what has cited it since, ranked for your library:

references several of your papers cite come first, then ones close to what you write notes about, then ones with a free PDF. Import a reference in a click when a free PDF exists.

• Open a paper's Similar tab for papers like it, suggested by Semantic Scholar,

and add them the same way.

Capture data and chart it

• Capture a table by drawing a box over it, or select a number like 88.5 ± 0.3 to keep it, add your own data from a

CSV, and chart them side by side. Click any point on a chart to open its page in the paper.

Keep notes that stay findable

• Every note keeps the page and position of its passage. Click a note to jump back to it in the paper.
• Each note shows who wrote it: You, AI, or AI · edited.
• Filter the notes list to show only your notes, only AI notes, or both.

Ask a paper questions

• Chat with one paper at a time. Answers stream in as they are written.
• Pick the model for each question from the chat panel: a local Ollama model, Anthropic with your own key, or any

OpenAI-compatible server (OpenAI, OpenRouter, Groq, Mistral, DeepSeek, Gemini, LM Studio, vLLM, llama.cpp). Cloud models are tagged "Cloud". Each answer keeps the model and connection that wrote it.

• Answers cite the passages they use, like [C1]. Hover a citation to see its page and section, and click it to

scroll the paper to that passage and flash it.

• A short paper is sent to the model whole. A long one is searched first, and only the most relevant passages are sent.
• Your notes on the paper go to the model with its passages, marked You or AI, and answers can cite them like [N1].

Click one to jump to that note.

• Press Follow up under an answer to ask about it. The model gets your earlier questions and the passages they

used, never its own earlier answers. Follow-ups stay under the first question, and your next questions keep following the newest answer until you press ×.

• Select part of an answer and click Save as note. The note is anchored on the passage it cites and marked AI.

Use your library from Claude Desktop

• Connect Claude Desktop, Claude Code or another MCP client to PaperLab

([how](#use-paperlab-from-claude-desktop)). It can search your papers, read a paper's details, outline and notes, find the papers in your library connected to one (a shared workspace, note, author or topic, or a citation), and save a note on a passage it quotes.

• A note it saves is marked AI, like a note saved from chat, and is highlighted on the lines it quoted.

Install it as an app

• Download PaperLab for macOS, Windows or Linux and open it ([Quick start](#quick-start)). It starts everything

it needs, so there is no repo to clone and no server to run. Docker is the one thing to install first.

• A short first run offers a chat model and a search model. Both are optional and both can be skipped: reading,

highlighting and notes work without either, and you can set them up later in Settings.

• Closing the window stops PaperLab. Turn on Keep running and it stays in the menu bar instead, so Claude

Desktop can reach your library and uploads keep processing while the window is closed.

Principles

• Local first. One user, one machine, no accounts. Your PDFs, notes and search index live in a local Postgres

database. With a local model (Ollama, LM Studio and other servers on your machine), the text of your papers and notes never leaves your computer; a model tagged "Cloud" receives the passages and notes sent with each question. A search source tagged Cloud (OpenAI, Gemini, or an Ollama or OpenAI-compatible server outside your network) receives the text of every chunk of every paper and of every note when you switch to it, each paper and note you add, and every search question. PaperLab asks before the first send, with an estimate of the cost. Metadata lookups on OpenAlex are off unless you tick OpenAlex, and they send a paper's DOI or title, never its text. Find papers sends what you type to every paper source that is on and can answer it, then the results' DOIs to Semantic Scholar and, for results without a free PDF, to Unpaywall. The Similar and References tabs send Semantic Scholar the paper's DOI (its arXiv ID when the DOI is an arXiv one), or its title when it has none. With OpenAlex ticked, the References tab also sends OpenAlex the paper's OpenAlex ID and the OpenAlex IDs of the works it cites. Your contact email goes to Crossref, Unpaywall and OpenAlex (when on), never to the others or to PDF hosts. API keys stay in your local database and are never sent back to the browser. Adding a paper downloads its PDF from the free link found. None of them send a paper's text. An MCP client you connect, such as Claude Desktop, receives what its tools return: passages from your papers, paper details and workspace names, and every note on a paper marked as yours or AI. Claude Desktop and Claude Code send what the tools return to Anthropic.

• Updates are announced, never installed. Each time it opens, the desktop app asks GitHub whether a newer version

is out and offers a download link when there is one. It is the only request the app makes on its own; turn it off in Settings → Desktop app.

• An upgrade keeps a way back. Before a new version first starts, the desktop app saves a copy of your library's

database in its data folder, keeping only the latest.

• AI is always labelled. AI text is stored separately from yours, keeps the model and prompt version that

produced it, and shows an AI badge. Editing an AI note marks it "AI · edited", never "You".

• Answers show their sources. Chat answers cite passages you can click, so you can check every claim against the paper.

Quick start

The desktop app

PaperLab runs on Docker: install Docker Desktop and open it once. Then download PaperLab for your system from the latest release and open it.

| System | File | |---|---| | macOS with Apple silicon | PaperLab--arm64.dmg | | macOS with an Intel processor | PaperLab--x64.dmg | | Windows | PaperLab--x64.exe | | Linux | PaperLab--x86_64.AppImage, or PaperLab--amd64.deb |

The first launch downloads PaperLab itself (about 335 MB; an update downloads only what changed) and opens it in its own window. A short setup then offers a chat model and a search model. Each downloads only if you pick it, and Skip leaves both for later in Settings: reading, highlighting and notes need neither.

PaperLab isn't signed yet, so your system asks before the first launch, and again after each update:

• macOS: open PaperLab and close the warning. Then open System Settings → Privacy & Security, find the line

about PaperLab near the bottom, and click Open Anyway.

• Windows: on "Windows protected your PC", click More info, then Run anyway.
• Linux: make the AppImage executable (chmod +x PaperLab-*.AppImage) and run it. If it doesn't start (Ubuntu

24.04 blocks some AppImages, and Ubuntu 22.04 and later lack libfuse2), install the .deb instead.

Closing the window stops PaperLab and frees its memory. To keep it running for Claude Desktop, turn on Keep PaperLab running when the window is closed in Settings → Desktop app: its menu-bar icon then opens or quits PaperLab.

Any Docker that provides the docker command works: Docker Desktop, OrbStack, Colima or Rancher Desktop. Docker Desktop is free for personal use, education and small companies; larger companies need a paid Docker subscription.

On Linux:

• install Docker from docker.com, not the Snap package: the Snap's Docker

can't read ~/.config, where PaperLab keeps its files;

• let Ollama listen beyond 127.0.0.1, so PaperLab's containers can reach it: run sudo systemctl edit ollama, add

Environment="OLLAMA_HOST=0.0.0.0" under [Service], then sudo systemctl restart ollama. Other machines on your network can then reach Ollama too, unless a firewall stops them.

Without the app

With Docker Compose 2.24 or later, two commands install the same release, with no clone and no build:

VERSION=0.1.1   # the latest release's number
curl -L "https://github.com/khannoussi-malek/PaperLab/releases/download/v$VERSION/paperlab-$VERSION.tar.gz" | tar xz
cd paperlab && docker compose up -d   # then open http://127.0.0.1:5190

The paperlab folder holds docker-compose.yml and scripts/paperlab-mcp. To update, unpack a newer release over it and run docker compose up -d again. Nothing starts with the computer: docker compose stop stops PaperLab and docker compose up -d starts it.

Your library

The desktop app and the commands above share one library, in the paperlab-app project's Docker volumes, so use one or the other. Updating or uninstalling keeps it.

Before a new version of the app first starts, the app saves a copy of the database as backups/latest.sql.gz in its data folder, replacing the previous copy. The data folder is:

• macOS: ~/Library/Application Support/PaperLab;
• Windows: %APPDATA%\PaperLab;
• Linux: ~/.config/PaperLab.

Without the app, back up by hand in the PaperLab folder: docker compose exec -T db pg_dump -U paperlab paperlab | gzip > paperlab-backup.sql.gz.

Going back to an older version on a library a newer one has used isn't supported: it doesn't start, and says why.

docker compose -p paperlab-app down -v deletes everything: the library, its PDFs and the search model. The app's backup stays in its data folder.

Build from source

For contributors, with Docker and Ollama installed:

ollama pull qwen3:8b                  # the default chat model
docker compose up -d --build          # db (:5433), redis, api (:8000), worker, frontend (:5180)
open http://localhost:5180

First start

PaperLab works without a search model: upload papers, read them, highlight and take notes, and chat with short ones. Chatting with a long paper or a workspace needs the built-in search model, and so does Claude's search_library: it is nomic-embed-text-v1.5 running on ONNX Runtime (548 MB). Download it in Settings → Search, or from the library or chat when a long paper needs it. It goes into the models volume, and the papers you added before are made searchable in the background. If Settings → Search then says some chunks were indexed with another model, re-index the library there once. The graph's Similar content layer and the References tab's note ranking also stay off until the model is downloaded.

Search can also run on Ollama's nomic-embed-text, OpenAI (text-embedding-3-small or -large), Gemini (gemini-embedding-2) or an OpenAI-compatible server instead of the built-in model: pick one in Settings → Search. It uses a connection from Settings → Model connections, so a key is entered once, and every source gives the 768 numbers the search index holds. A switch embeds every paper again in the background, and your notes the next time a References tab fetches. Search pauses with its progress until the papers are done, while reading, notes and chat on short papers keep working. A source tagged Cloud asks first, with an estimate of what it sends and what it costs. If some papers can't be embedded (a rejected key, a server that went away), Settings → Search says why, and Try again embeds just those. With another source in use, the built-in model i

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: khannoussi-malek
• Source: khannoussi-malek/PaperLab
• License: Apache-2.0
• Homepage: http://paperlab.tn/

Install and usage instructions live in the source repository linked above.