📚 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

Input	What happens
Markdown / TXT / HTML / CSV and other text	Read as-is — the default shape of a knowledge base
PDF	Layout analysis + OCR + table reconstruction → Markdown
Word / PPT / Excel	Same pipeline, heading hierarchy and tables preserved
Images (PNG / JPG / TIFF)	OCR text extraction
Web pages	One-click clip, or article extraction for WeChat posts
Obsidian vault	Opened in place — original files are read-only
Million-word books	Chunked preprocessing + digest pipeline, resumable

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
• Chinese classical poetry and prose: a panoramic knowledge base

Browse all resources →

📡 Channels

A single Molio instance can serve multiple channels in parallel. Most channels can be onboarded right from the Web console.

Channel	Text	Image	File	Voice	Group
Web Console (default)	✅	✅	✅	✅	—
WeChat	✅	✅	✅	⏳	⏳
Feishu	✅	✅	✅	⏳	✅
Telegram	⏳	⏳	⏳	⏳	⏳
Slack	⏳	⏳	⏳	—	⏳
Discord	⏳	⏳	⏳	—	⏳

✅ 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 /vaults in docker-compose.yml volumes. 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_PATH in .env to mount your existing documents folder into the container (at /vaults). See install.sh and .env.example for 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:
  • Claude Code
  • OpenAI Codex CLI
  • Gemini CLI
  • Qwen Code

# 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.

Learn more →

🤝 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!

⭐ Star · 🐛 Report Bug · 💡 Request Feature