📚 Molio
Give AI your personal knowledge base. Local-first, and every byte stays yours.
English · 中文 · 🌐 Official Website
What you've accumulated isn't one kind of thing: experience and methods scattered across notes, documents, and chat logs — and also whole books, PDFs full of figures, piles of industry material. Most of it sits in a form AI can't read, so every conversation starts from zero.
Molio turns all of it into a personal knowledge base that AI can read and use: Claude Code, Codex, and other agents enter your knowledge space, work on top of everything you've accumulated — researching, writing, answering, analyzing — and write their results back as Markdown, so the base grows thicker with every task. Everything runs on your machine, never through a third-party server.
Starting from zero? The resource library ships ready-made knowledge bases that keep growing — import one and start asking.
▶ Click to watch the demo — one book, one knowledge universe: 1,362 years of history from the Zizhi Tongjian, processed by Molio into an AI-explorable knowledge base
🔁 How It Works
01 · Collect & Process — scattered fragments, or a whole book, all become a callable knowledge base
Input isn't limited by format: clip pages with one click via the Web Clipper, open your Obsidian vault directly, or batch-import local documents. Scanned PDFs and Word / PPT / Excel files go through the bundled docling for layout analysis, OCR, and table reconstruction; images are read by OCR; million-word books run through a chunked preprocessing and digest pipeline with resumable progress. What lands on disk is plain Markdown — zero migration, no lock-in.
The Wiki engine then extracts entities and concepts from that unified Markdown layer, weaving dense cross-links and layered indexes — data becomes a foundation only after it's processed.
02 · Work & Task — agents run on your data
Claude Code, Codex, Gemini CLI, Qwen Code — agents work inside your knowledge space, researching, writing, answering, and analyzing. What they see is no blank slate, but everything you've accumulated. Pick an agent in a unified GUI with streaming output; scan a QR code to chat with your base from your phone via WeChat.
03 · Reflow & Deposit — the base grows thicker with use
Every task's output is written back as Markdown — a reusable, long-term asset. The knowledge graph keeps growing, so the next task starts from higher ground. Ready to publish? Typeset with doocs/md and distribute to 30+ platforms in one click.
📥 Supported Inputs
PDF and Office conversion is handled by the bundled docling skill. The first conversion downloads the tool plus ~500MB of models; later runs reuse the cache.
📦 Ready-made Knowledge Bases
Beyond the tool itself, Molio offers ready-made structured knowledge graphs — entire books and professional domains pre-organized into AI-ready knowledge bases you can import in one click, no building from scratch.
Covering literature, history, philosophy, traditional Chinese medicine, medicine, and AI engineering, with new resources added regularly. Highlights include the ontology knowledge base, the Zizhi Tongjian knowledge system, and an obstetric-ultrasound knowledge base. See the resource library for the full, always-current catalog.
These are uniquely structured assets that AI cannot conjure on its own. Import one into Molio and instantly run AI Q&A, relationship lookup, and topical research.
- Dream of the Red Chamber: characters and imagery across all 120 chapters
- Jin Ping Mei: people, commerce and social structure
- Shiji (Records of the Grand Historian): people, institutions, thought
- Zizhi Tongjian: 1,362 years of rise and fall
- History of Ming: empire, institutions and court politics
- Zhouyi: all 64 hexagrams, with line-change and image-number analysis
- Laozi & Zhuangzi: core concept system
- Chinese and Western philosophy: a knowledge base for local AI
- Traditional Chinese medicine classics: six-meridian and triple-burner pattern differentiation
- Obstetric and gynecologic ultrasound: fetal anomalies, signs and differential diagnosis
- Knowledge engineering: ontology, RAG, GraphRAG and agent engineering
- Guangdong gaokao application planning: universities and majors
- Romance of the Three Kingdoms: character relationship map, all 120 chapters
- Drawing data extraction: from engineering drawings to computable data
- PCB flexible manufacturing: from online order to lights-out factory
- Bar exam criminal law: 131 exam points and subjective-question training
📡 Channels
A single Molio instance can serve multiple channels in parallel. Most channels can be onboarded right from the Web console.
✅ Supported · ⏳ Planned · — N/A
🖼️ Screenshots
🚀 Quick Start
Installation
Download the latest release from GitHub Releases:
- Windows:
Molio-Setup-x.x.x.exe - macOS:
Molio-x.x.x.dmg
Install and launch. On first run, you'll be guided to configure an AI runtime CLI (e.g., Claude Code, Codex, Gemini).
🐳 Docker / NAS Deployment (self-hosted)
Run Molio as a self-hosted web service on a NAS or server. A single container bundles the daemon, web UI, and Claude Code CLI, and works on both linux/amd64 and linux/arm64 — Synology, QNAP, TerraMaster, TrueNAS, Unraid, and most other NAS devices.
⚠️ How this differs from the desktop app (read before deploying)
- Browser access only — there is no desktop client for this mode. The Electron desktop app only ever talks to the daemon it launches locally (
localhost); it cannot connect to a container running on a remote NAS/server.- The daemon runs inside the container and can only read/write directories mounted into it. The desktop workflow of "pick any local folder as a knowledge base via a folder picker" does not apply here — the browser has no folder picker, so when you add a knowledge base you type a container-internal path (e.g.
/vaults/your-folder, not the NAS host path).- To expose folders as knowledge bases, mount them under
/vaultsindocker-compose.ymlvolumes. Your data still stays entirely yours (on your NAS) — only the access model changes, from "desktop app" to "browser + mounted volumes".
One-click install (requires Docker + Docker Compose v2):
# China (recommended)
curl -fsSL https://molio-releases.oss-cn-guangzhou.aliyuncs.com/script/install.sh | bash
# Overseas
curl -fsSL https://raw.githubusercontent.com/zhuzhaoyun/Molio/main/install.sh | bash
# Offline (clone the repo first, then run the bundled script)
bash install.sh
The script asks for your knowledge-base directory and port, then pulls the image and starts the service. When it finishes, open http://<your-server-ip>:3100, then go to Settings → Runtimes to configure your AI model and API key. On first boot Molio auto-creates a default knowledge base on the mounted directory, so you land straight inside — no manual setup.
Manual install (if you prefer plain docker compose):
git clone https://github.com/zhuzhaoyun/Molio.git && cd Molio
cp .env.example .env # AI model is configured later in the web UI
docker compose up -d # then open http://<your-server-ip>:3100
Everyday commands (run inside the install directory, default ~/molio):
docker compose logs -f # follow logs
docker compose restart # restart
docker compose pull && docker compose up -d # update to the latest image
docker compose down # stop
Set
MOLIO_VAULT_PATHin.envto mount your existing documents folder into the container (at/vaults). Seeinstall.shand.env.examplefor every option.
Development (from source)
If you want to build from source or contribute to development:
Prerequisites:
- Node.js >= 22
- pnpm >= 9
- At least one AI runtime CLI:
# Clone the repository
git clone https://github.com/zhuzhaoyun/Molio.git
cd Molio
# Install dependencies
pnpm install
# Start development environment (daemon + web)
pnpm dev
# Or start individually
pnpm dev:daemon # Backend only (port 3100)
pnpm dev:web # Frontend only (port 5173)
Desktop Build:
# One-click build + generate unpacked version
pnpm desktop:run
# Or full packaging as installer
pnpm package
# Generate unpacked directory only (no installer)
pnpm package:dir
Testing:
pnpm test # Run all tests (node:test)
pnpm typecheck # Type checking
pnpm build # Build all packages
pnpm test:e2e # E2E tests (requires pnpm dev running)
🔌 MCP server & Pi package
Molio's knowledge base is also available as a read-only MCP server, so Claude Code, Cursor, Pi, and any MCP-compatible agent can search and read your local vaults mid-conversation:
npx -y @molio/cli mcp # stdio MCP server, 7 read-only tools
claude mcp add molio -- npx -y @molio/cli mcp # register it in Claude Code
pi install npm:@molio/cli # Pi: auto-registers the server + a `molio-kb` skill
Any other MCP client:
{
"mcpServers": {
"molio": { "command": "npx", "args": ["-y", "@molio/cli", "mcp"] }
}
}
Tools: molio_status, kb_vaults, kb_tree, kb_read, kb_search, kb_ask_start, kb_ask_poll — strictly read-only, published to the official MCP Registry as io.github.zhuzhaoyun/molio. Requires a running Molio service (desktop app or Docker). Details: apps/cli/README.md · npm: @molio/cli
🧩 DeepSeek Harness (dsh) plugin
Molio's knowledge base is also available as a read-only plugin for DeepSeek Harness (dsh), so dsh agents can search and read your local Molio vaults during a conversation:
dsh plugin add dsh-plugin-molio
It exposes 5 read-only tools (molio_status, molio_kb_vaults, molio_kb_tree, molio_kb_search, molio_kb_read) backed by the local Molio daemon HTTP API. Requires a running Molio service (desktop app or Docker). Details: packages/dsh-plugin-molio/README.md · npm: dsh-plugin-molio
🏗️ Architecture
Molio/
├── packages/
│ └── contracts/ @molio/contracts — Shared type definitions
├── apps/
│ ├── daemon/ @molio/daemon — Hono HTTP server (API + SSE)
│ ├── web/ @molio/web — Vite + React frontend
│ └── desktop/ @molio/desktop — Electron desktop shell
└── package.json Monorepo root config
Tech Stack:
- Frontend: React 19 + Vite 6 + TypeScript
- Backend: Hono + Node.js + SQLite (better-sqlite3)
- Desktop: Electron 40 + electron-builder
- Build: pnpm workspace monorepo
❓ FAQ
macOS says the app is "damaged and can't be opened"
This is macOS Gatekeeper's security warning, because Molio is currently not notarized with Apple (requires an Apple Developer Program subscription at $99/year). It's not a problem with the app itself. Either:
Option 1 (recommended): Right-click the app → "Open" → click "Open" in the dialog (first launch only).
Option 2: Run in Terminal:
sudo xattr -d com.apple.quarantine /Applications/Molio.app
After that, it opens normally with a double-click.
🏢 Custom Services
Keep your core knowledge in your own yard — data processing, consulting, and private deployment on demand. One demo says it all.
🤝 Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Key principles:
- All changes must go through Pull Request (no direct pushes to
main) - Follow Conventional Commits:
feat(scope): description - Add tests for bug fixes (unit tests for daemon/desktop, E2E for web)
- Run smoke tests before submitting PRs
💬 Community & Support
File an issue on GitHub, or scan the QR code below to join our WeChat community:
❤️ Acknowledgments
Molio is inspired and supported by these excellent open-source projects:
- multica — Open-source Agent management platform, inspiring Molio's multi-runtime orchestration
- doocs/md — WeChat Markdown editor, powering Molio's typesetting engine
- doocs/cose — Multi-platform content distribution extension, powering Molio's publishing capabilities
- WeKnora — Tencent's open-source knowledge management platform, providing design philosophy reference
Thanks to the authors and communities of these projects!
📄 License
Modified Apache 2.0 — Based on Apache License 2.0 with additional commercial use restrictions. Free for internal and non-commercial use; commercial hosting/embedding requires a commercial license.
If you find Molio useful, consider giving it a ⭐️ star on GitHub!
