Paperless-AI: automatic tagging and RAG chat for Paperless-ngx, and the maintenance caveat

What Paperless-AI adds to a Paperless-ngx archive

Paperless-ngx stores documents and lets you tag them. It does not read a scanned invoice and decide that the correspondent is the utility company. Paperless-AI is the layer that does that. The README describes it as an AI-powered extension that brings automatic document classification, smart tagging and semantic search, using OpenAI-compatible APIs and Ollama.

The target user is someone who already runs Paperless-ngx and whose archive has grown past the point where manual tagging keeps up. The project detects new documents in Paperless-ngx, analyzes the content, and then assigns a title, tags, a document type and a correspondent. It also ships a manual processing view at /manual, which the README presents as useful when reviewing sensitive documents before letting the model touch them.

The second half of the feature set is retrieval. The README advertises a RAG-based chat that answers questions such as when a rental agreement was signed or what the last electricity bill came to. That is a different workload from tagging: tagging is one document in, structured metadata out, while chat is a query against the whole archive.

The two-service architecture: Node.js plus a Python RAG service

The repository is not a single process. The top level contains server.js and package.json for a Node.js application, and main.py plus requirements.txt for a Python service. The Dockerfile makes this explicit: it starts from node:22-slim, installs python3 and python3-venv, creates /app/venv, and installs the Python requirements into it. The container command is ./start-services.sh, so both runtimes start together.

The Python side is the retrieval stack. requirements.txt lists fastapi, uvicorn, sentence-transformers, chromadb, rank-bm25 and nltk. That combination points at a vector store with a BM25 keyword component alongside it, which is a common hybrid retrieval setup. The Node side carries express, better-sqlite3, sqlite3, node-cron, dockerode and the openai client, so scheduling, local state and model calls live there.

The two halves are wired through environment variables. The compose file sets RAG_SERVICE_URL=http://localhost:8000 and RAG_SERVICE_ENABLED=true. Note the address: localhost, not a service name. That works because both processes share a container, and it is also why you cannot simply point RAG_SERVICE_URL at a separate container without checking how start-services.sh is written. The README warns that a first-time install needs a container restart after setup so the RAG index gets built, and that updates do not need this.

Installing Paperless-AI with Docker Compose

The README points at the installation wiki rather than giving full steps inline, so treat the compose file in the repository as the reference for the container itself. The published image is clusterzx/paperless-ai. A minimal compose file based on the repository's own docker-compose.yml looks like this:

services:
  paperless-ai:
    image: clusterzx/paperless-ai
    container_name: paperless-ai
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - PAPERLESS_AI_PORT=3000
      - RAG_SERVICE_URL=http://localhost:8000
      - RAG_SERVICE_ENABLED=true
    ports:
      - "3000:3000"
    volumes:
      - paperless-ai_data:/app/data

After the container is up, open port 3000 in a browser. That is where the web interface lives, and it is where you enter your Paperless-ngx connection details and your model backend before anything is processed. The repository ships an .env.example at the top level; the compose file above is the environment-variable path, and the README does not describe which of the two takes precedence.

The README states that after completing setup (API keys and preferences) you should restart the container once so the RAG index is built. That restart is the step people skip, and skipping it is why chat can appear to work while returning nothing useful.

For local development rather than Docker, package.json defines a single script:

npm install
npm run test

That second command is not a test runner despite the name. The script is nodemon server.js, so it starts the server in watch mode. The Python RAG service is separate and is not started by that command.

Choosing a backend: Ollama, OpenAI, or anything OpenAI-compatible

The model backend is the decision that determines both your running cost and your privacy posture. The README lists Ollama with Mistral, Llama, Phi-3 and Gemma-2, plus OpenAI, DeepSeek.ai, OpenRouter.ai, Perplexity.ai, Together.ai, LiteLLM, VLLM, Fastchat and Gemini. Because the openai client is a dependency and the project describes itself as working with OpenAI-compatible services, the practical rule is that anything exposing that API shape should be configurable.

The trade-off is not subtle. Sending document text to a hosted API means your scanned contracts and invoices leave your network. Running Ollama locally keeps the text inside it, at the cost of a GPU or a slow CPU inference path and a model that is generally weaker at structured extraction than the hosted options. Paperless-AI does not resolve that for you; it just makes both paths available.

The project also depends on tiktoken, which is used for token counting. That matters if you plan to send long documents to a metered API, because the prompt size is bounded by the model's context window and the README does not document any chunking strategy for classification. The RAG service, by contrast, exists precisely to handle documents that do not fit.

Rules, restrictions and the manual review path

Unattended tagging on a whole archive is a good way to discover that your model has confidently mislabelled several hundred documents. Paperless-AI's answer is a rules layer: the README describes defining rules to limit which documents are processed, disabling prompts, applying tags automatically, and setting custom output tags for tracked classification. The repository also contains test-restriction-service.js and test-updated-service.js at the top level, which suggests the restriction logic is a distinct service rather than a few conditionals in a route.

The /manual route is the other control. It gives you a web interface for tagging by hand, which the README frames as the option for sensitive documents. In practice this is the mode to use during a trial: point the tool at a small set of documents, watch what it assigns, and only then widen the rules.

The limitation here is that the README does not document a dry-run mode, nor a rollback for tags already written back to Paperless-ngx. If the model assigns the wrong correspondent to 400 documents, the README is silent on how to undo that in bulk. Anyone planning to run this across an existing archive should assume the undo work is theirs, and should confirm the behaviour against the wiki and the open issues before enabling automatic processing.

The maintenance notice is the main risk, not a footnote

The README opens with a notice stating that the repository is currently not maintained. The author writes that he is rewriting the entire codebase with what he calls a more stable, up-to-date architecture, that he is limited to evenings, and that doing support here while also working on the rewrite is not feasible. He also notes the upcoming official AI integration in Paperless-ngx itself and says he is not sure whether he will complete the rewrite or continue maintaining this repository at all.

That is unusually direct, and it should be read as the project's own statement about its future rather than as speculation. The last push to the default branch was on 2026-09-03, and the most recent release listed is v3.0.9 from 2025-11-04, described as a fix for a tag caching issue introduced by a security fix. The release before it, v3.0.8, is labelled Security Fix, Updates, Merges. So there has been recent activity, but the author's own framing is that maintenance is not currently happening.

A second signal sits in the repository root: package-lock.json.bak. A backup lockfile committed alongside the live one usually means a dependency operation went sideways at some point. It is not proof of anything by itself, but it is the kind of detail worth noticing when you are deciding how much you want to depend on a project.

The practical consequence is that you should treat Paperless-AI as software you may have to patch yourself. The MIT licence permits that. It does not oblige anyone to help you do it.

How it compares with Paperless-gpt and with Paperless-ngx alone

Paperless-gpt appears repeatedly in the search terms around this project, and the comparison is fair because both sit in the same slot: an external service that reads your Paperless-ngx documents and writes metadata back. The difference visible in this repository is scope. Paperless-AI bundles a Python RAG service with ChromaDB and sentence-transformers, so semantic chat over the archive is part of the product rather than an add-on, and it exposes a manual tagging interface at /manual. A tool focused only on OCR correction or title generation would be lighter to run and would not need a second runtime in the container.

The other comparison is doing nothing. Paperless-ngx already does full-text search, and the README's own notice points at an official AI integration coming to Paperless-ngx itself. If your archive is small or your tagging discipline is good, the honest answer is that Paperless-AI adds a container, a Python dependency tree that includes torch, and a model backend to keep running, in exchange for metadata you might not need. The RAG chat is the feature that is hardest to replicate by hand, and it is also the one most affected by the first-install restart requirement.

If you do want an external layer, the deciding question between the options is not feature count but which model backend each supports and whether the project is being maintained. On the second point, this repository answers for itself in its README.

Editorial conclusion

Adopt Paperless-AI if you already run Paperless-ngx, want automatic title, tag, document type and correspondent assignment, and are willing to accept that the README declares the repository currently not maintained. Do not adopt it if you need vendor-backed support or a guaranteed upgrade path; the author states he is rewriting the codebase and is unsure whether he will continue maintaining this repository. Before installing, verify three things: that your Paperless-ngx API token works from the container, that you have chosen a backend (Ollama locally or an OpenAI-compatible API), and that you have read the installation wiki, because the README itself does not document rollback or migration between versions.

Frequently asked questions

Official sources

1. clusterzx/paperless-ai on GitHub
2. License: MIT
3. Project website
4. README
5. Releases