PaperlessBrain

The brain for your Paperless-ngx archive.
Chat with your documents, let a vision LLM read every page, never miss a deadline.
Keep your Markdown notes beside them — editable in the app, Obsidian optional.
Installable PWA — built for mobile and desktop.

---

Status. A personal homelab project, shared as-is. Rough edges, no full-time maintainer — issues and PRs get answered when I have time, and good work gets merged. It's MIT: fork it if you like, but I'd rather build it with you.

What it does

Paperless-ngx stores and organizes your documents. PaperlessBrain reads them — every page, through a vision LLM — and turns the archive into something you can talk to.

• Chat with your archive — an agentic tool loop that searches, reads, cross-references and cites your documents.
• Every claim shows its source — answers carry reference numbers; one tap opens the page with the passage highlighted, from the PDF's own text layer. When nothing matches, nothing is marked — no confident wrong highlight. Web pages are numbered sources too, linked to the page the tool actually read.
• Vision-LLM ingestion — every page rendered and read by a vision model: summary, tables, actions and deadlines, per document type. Fully local on Ollama, or any cloud vision model.
• Pictures in chat — "show me the lasagna recipe" answers with the photo, cropped from the page; any page can be shown inline. Ingestion finds every photo, chart, map or X-ray on a page, describes it and records where it is — exactly from the PDF where it can, from the vision model on scans.
• Deadlines & actions — extracted obligations ("cancel by …", "pay until …") on the dashboard.
• Brain memory — the assistant remembers facts about you as plain Markdown, embedded for recall in every conversation.
• Note vault — your Markdown notes in a plain folder, searchable in chat. Editable in the app (tree, editor, properties panel) so a phone is enough; Obsidian on the same folder stays the richer way to work. → docs/vault.md
• Voice memos — speak, and the transcript is tidied into structured Markdown and filed into your vault after you approve it. Conversation mode turns a recorded dialog into speaker turns. → docs/voice-memos.md
• Experts — chat personas for one slice of the archive (say, "Car" or "Health"): narrowed or excluded by correspondent, type and tag, with their own instructions, reusable skills and a briefing that maps their documents. The scope is enforced in code, not asked of the model.
• Deep research — autonomous multi-step research across your own documents alongside the web. Deterministic code checks every quote against what the tools actually returned, so what survives is citable. Each report becomes a note in your vault, readable as PDF.
• Document generation — DIN-5008 letters, email drafts, chat-to-PDF saved back into Paperless. Plus notes filed on a document under your own account.
• OCR write-back (opt-in) — vision-read text pushed back into Paperless, which fixes its full-text search too. → docs/operations.md
• AI document names (opt-in) — scan_0042.pdf becomes 2026_10_17_Invoice_Computer_parts_Amazon.pdf, from a template you write ({year}_{month}_{day}_{doc_type}_{description}_{correspondent}). The model only names what the document is about, in at most three words; date and sender come from Paperless. New documents are named as they arrive, and existing ones after a dry run that shows every rename first. → docs/operations.md
• Proactive reminders & insights (opt-in) — a background worker reads new documents while you are away: deadline reminders at 30/7/1 days (never for dates that have passed), and notes on contracts, insurance or savings worth a look, with a deep dive on request. Notifications on your phone and desktop (Web Push, end-to-end encrypted) or by email, each just a link to the finding; quiet hours you set; it learns which topics you care about. Every recommendation needs a quote from your document and a web page actually read; web queries never carry your names, numbers or amounts. Findings and long-running topics (dossiers with a timeline, open questions and your saved insights) live in one workspace, with the chat docked beside them. → docs/proactive.md
• Email, calendar & web — per-user IMAP and CalDAV (encrypted), web search through your own SearXNG with full-page reading.
• Wake-on-LAN GPU host — a local model whose machine is asleep wakes it, and it sleeps again when idle — never while someone is using it. The dashboard shows what the GPU is doing.
• PWA — installable on phone and desktop, English/German, dark/light.

Screenshots

Dashboard — deadlines & actions extracted from every document	Document detail — vision-read pages, tables, actions, cross-references
Sources — every claim carries a number; tap it and the page opens with the passage marked	Note vault — tree, markdown editor and properties, without leaving the app
On the phone — installable PWA: chat, document details, dashboard

Quick start (Docker)

mkdir paperless-brain && cd paperless-brain
BASE=https://raw.githubusercontent.com/Vailsen/paperless-brain/main
curl -O  $BASE/docker-compose.yml
curl -o .env $BASE/.env.example   # fill in: PAPERLESS_URL, PAPERLESS_SUPERUSER_TOKEN, STORAGE_SECRET
docker compose up -d              # pulls the prebuilt image from GHCR

Two files, ~6 KB — nothing to clone. Prefer a fixed tag (v0.20.0) over main.

Before the first start, point the vault mount in docker-compose.yml at the directory holding your notes — one subfolder per Paperless user (/srv/obsidian/alice for user alice → mount - /srv/obsidian:/mnt/vaults). Left unchanged, the app creates an empty vault and your real notes are never indexed.

Then open http://localhost:8080 and log in with your Paperless-ngx username and password — users, permissions and sessions come from Paperless itself.

First boot downloads the embedding model (~2.2 GB) into a Docker volume, so the container needs internet access once. The default image includes headless Chromium for JS-heavy pages; :lean is ~1 GB smaller and falls back to trafilatura. To build from source, clone and swap image: for build: ..

Installing without Docker → docs/operations.md.

Prerequisites

You need	Notes
Paperless-ngx	any recent version + a superuser API token
A vision-capable model	for ingestion — local via Ollama (Qwen-VL class, can live on another machine) or any cloud vision model
An LLM endpoint for chat	Anthropic- or OpenAI-compatible; added per user in Settings
SearXNG · IMAP · CalDAV · speech-to-text · WoL GPU host	all optional, each enabling one feature

AI models & providers

Models are added per user in Settings > AI Models — base URL, API key, model id. Two backend types (anthropic, openai_compatible), both with a custom base URL, so local runtimes (Ollama, vLLM, llama.cpp, LM Studio), direct cloud providers and AI gateways (OpenRouter, Requesty, LiteLLM, Portkey) all work with no code. No provider is hardcoded and no API key belongs in .env. The same registry serves chat, deep research and vision ingestion.

Details, thinking mode and every .env key → docs/configuration.md.

Architecture

flowchart LR
    P[Paperless-ngx] <-->|REST API| B(PaperlessBrain)
    B <--> C[(ChromaDB<br/>+ JSON sidecars)]
    B <-->|chat + vision ingest<br/>local| O[Ollama]
    B <-->|chat + vision ingest<br/>optional| A["Anthropic-compatible<br/>(Claude, MiniMax …)"]
    B <-->|chat + vision ingest<br/>optional| X["OpenAI-compatible<br/>(OpenAI, OpenRouter, vLLM …)"]
    B <--> V[/"Vault (Markdown + git)"/]
    B -->|web search| S[SearXNG]
    B <-->|mail| M[IMAP]
    B <-->|calendar| D[CalDAV / iCal]

Sync compares Paperless against the index; new documents are rendered page by page and read by the vision model, landing as JSON sidecars plus ChromaDB embeddings (multilingual-e5). Each run ends with removal of deleted documents, an LLM review of extracted deadlines and — if enabled — the text write-back. Both LLM backends share one tool set and one streaming event protocol.

Documentation

Configuration	every .env key, model registry, extraction rules, adding a language
Vault & notes	how memory and your notes are stored, the built-in editor, Obsidian alongside it
Voice memos	transcription services, conversation mode, what to expect
Proactive reminders & insights	the background worker, push/email, what it does and never does
Operations	OCR write-back, Wake-on-LAN + idle shutdown, security notes, bare-metal install

Why I built this

I tried several existing tools in early 2026 and none fit: I wanted high-end consumer hardware used properly, a more detailed LLM ingestion, an information-rich vector database and genuinely useful document views. It grew feature by feature until it felt worth sharing.

My best results so far come from Qwen3.6-35B-A3B (MTP, Q4) as the chat model — Multi-Token Prediction makes it faster than any cloud model I've tried while staying strong at tool use. Nothing here is tied to a specific model.

Contributing

Issues and PRs welcome — early alpha from a personal homelab, so expect rough edges. Please open an issue before large changes. CI runs the test suite on every PR.

Acknowledgements

NiceGUI is the entire frontend: every page, dialog and the streaming chat view is plain Python — no JS build step, no separate frontend service, no API layer to keep in sync. A one-person project keeps a UI this large maintainable only because that whole category of work is gone. Thank you, Zauberzeug.

Paperless-ngx is the archive this is built on — it stores the documents, owns users and permissions, and is why this project can concentrate on reading and reasoning. PaperlessBrain adds to it; it does not replace it.

Also standing on: FastAPI, ChromaDB, sentence-transformers with intfloat/multilingual-e5-large-instruct, Ollama, pypdfium2, WeasyPrint and SearXNG.

License

MIT — use it, fork it, ship it, sell it. Attribution is the only condition. All runtime dependencies are permissively licensed (MIT / BSD / Apache-2.0).