Molio: a local-first knowledge layer that lets agents read your notes, PDFs and books

What Molio is for

Molio is a local-first knowledge layer for AI agents. The problem it names is specific: what you have accumulated is not one kind of thing, but experience and methods scattered across notes, documents and chat logs, plus whole books, PDFs full of figures and piles of industry material, and most of it sits in a form AI cannot read, so every conversation starts from zero. Molio's answer is to turn all of it into a personal knowledge base that agents can enter and work on top of, researching, writing, answering and analysing, and then write their results back as Markdown so the base grows with every task. The README states that everything runs on your machine and never through a third-party server.

Collect, work, reflow: the three stages

The workflow is described in three stages. Collect and process turns input into a callable knowledge base, with text formats read as-is, PDF and Office files going through the bundled docling for layout analysis, OCR and table reconstruction, images read by OCR, and million-word books run through a chunked preprocessing and digest pipeline with resumable progress. A wiki engine then extracts entities and concepts from that unified Markdown layer and weaves cross-links and layered indexes, on the argument that data becomes a foundation only after it is processed. Work and task is where agents such as Claude Code, Codex, Gemini CLI and Qwen Code run inside your knowledge space, picked from a unified GUI with streaming output. Reflow and deposit is the part that closes the loop: every task's output is written back as Markdown, and the knowledge graph keeps growing.

What each input format goes through

The input table is the most concrete part of the documentation. Markdown, TXT, HTML and CSV are read as-is. PDFs get layout analysis, OCR and table reconstruction into Markdown. Word, PPT and Excel go through the same pipeline with heading hierarchy and tables preserved. PNG, JPG and TIFF images go through OCR. Web pages come in through a Chrome Web Clipper or article extraction for WeChat posts. An Obsidian vault can be opened in place, with the original files treated as read-only. Million-word books get chunked preprocessing and a digest pipeline that can resume. The README adds one cost up front: PDF and Office conversion is handled by the bundled docling skill, and the first conversion downloads the tool plus roughly 500 MB of models, with later runs reusing the cache.

Deploying it with Docker

The documented deployment path is Docker, and the compose file is annotated with the exact sequence. Copy the example env file, start the stack, then open the web console and configure the model there, which the docs recommend over editing the file by hand.

cp .env.example .env
docker compose up -d

The service listens on port 3100 by default, overridden with MOLIO_PORT, and the compose file maps ${MOLIO_PORT:-3100}:3100. Three volumes matter: molio-data holds the SQLite database and configuration at /home/molio/.molio, molio-claude persists Claude Code authentication and configuration, and your documents are bind-mounted from the host, controlled by MOLIO_VAULT_PATH and mounted at /vaults. On a first start with no knowledge base, Molio creates a default one pointing at /vaults so the web console opens straight into it. Additional knowledge bases use the container path, so /vaults/your-folder rather than the host path. The compose file targets linux/amd64 and linux/arm64 and explicitly calls out NAS boxes: Synology, QNAP, Terramaster, TrueNAS and Unraid.

Pointing it at a model, and file permissions

Model configuration is where the environment file earns its keep, and it is optional. The .env.example lists three routes: ANTHROPIC_API_KEY for the Anthropic API, or ANTHROPIC_AUTH_TOKEN together with ANTHROPIC_BASE_URL for an Anthropic-compatible endpoint, with a Chinese token plan and DeepSeek both given as worked examples. The example file gives the Anthropic-compatible route as commented lines you can uncomment, with the DeepSeek base URL and model names given in full, and the key itself is left for you to paste.

ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_MODEL=deepseek-v4-pro

There are also ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL keys for mapping the model tiers. On the file permission side, the container runs as a non-root user because Claude Code requires it, and it reads the host ownership of your vault directory at startup and aligns the container user to it, printing the uid it settled on in the startup log. PUID and PGID override that detection for the cases where you mount several directories with different owners. The desktop build has its own friction: the release notes explain that macOS Gatekeeper blocks the app because it is not notarized, and give a right-click Open workaround plus an xattr command that removes the quarantine attribute from Molio.app.

Channels, and which ones are finished

A single Molio instance serves several channels in parallel, and the README's channel table is honest about which are finished. The web console is the default and handles text, images, files and voice. WeChat handles text, images and files, with voice and group support marked pending. Feishu handles text, images, files and groups, with voice pending. Telegram is entirely pending. Most channels can be onboarded from the web console, and there is a QR-code path that lets you chat with your knowledge base from your phone through WeChat. This is the part of the product that is clearly still being filled in, so check the table against the version you install.

Pointing your agent at the folder is the alternative

The simplest alternative is to point your agent at the folder directly. Claude Code reads files off disk, so a vault of Markdown needs no ingestion layer at all: no conversion pipeline, no wiki pass, no Docker container, and nothing to keep running. What you give up is everything Molio does to inputs that are not Markdown, since scanned PDFs, Word files and images are unreadable to an agent without the docling conversion, and you also give up the entity and concept extraction that produces cross-links, plus the multi-channel access and the write-back discipline that makes each task leave something behind. If your material is already Markdown, the folder is enough. If it is mostly PDFs and books, the conversion layer is the reason Molio exists.

Licence, release cadence and build requirements

On licensing, the repository metadata declares no standard open source licence, so read the LICENSE file in the repository before you build anything on top of it, rather than assuming the usual permissions. On upkeep, the last push was on 2026-09-17 and releases are frequent, with 0.3.56 on 2026-09-15, 0.3.55 on 2026-09-08 and 0.3.54-beta.1 on 2026-09-08, so this is being worked on weekly. The release notes in that window are dominated by one thing, the macOS Gatekeeper instructions, which tells you where the current user friction is. Building from source needs Node 24 or newer, pnpm 11.5.0 as declared by the packageManager field, and a native module build for better-sqlite3, which the Dockerfile handles by installing python3, make and g++.

Editorial conclusion

Adopt Molio if your material is mostly PDFs, Office files, images or books that your agent currently cannot read, because the docling conversion and the wiki pass are what turn that into something an agent can work on. Skip the Docker route if your notes are already Markdown, since pointing Claude Code at the folder costs nothing and needs no container. If you do deploy it, set MOLIO_VAULT_PATH in .env before the first start, so the default knowledge base Molio creates points at your documents instead of an empty ./vaults.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. zhuzhaoyun/Molio on GitHub