# πŸ“š Molio **Give AI your personal knowledge base. Local-first, and every byte stays yours.** [English](README.md) Β· [δΈ­ζ–‡](README_zh.md) Β· [🌐 Official Website](https://molio.cn/) [![GitHub Release](https://img.shields.io/github/v/release/zhuzhaoyun/Molio?style=flat-square)](https://github.com/zhuzhaoyun/Molio/releases) [![License](https://img.shields.io/github/license/zhuzhaoyun/Molio?style=flat-square)](LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/zhuzhaoyun/Molio?style=flat-square)](https://github.com/zhuzhaoyun/Molio/stargazers) [![Last Commit](https://img.shields.io/github/last-commit/zhuzhaoyun/Molio?style=flat-square)](https://github.com/zhuzhaoyun/Molio/commits) [![npm: @molio/cli β€” MCP server & CLI](https://img.shields.io/npm/v/%40molio/cli?style=flat-square&label=MCP%20%40molio%2Fcli&color=blue)](https://www.npmjs.com/package/@molio/cli) [![npm: dsh-plugin-molio β€” DeepSeek Harness plugin](https://img.shields.io/npm/v/dsh-plugin-molio?style=flat-square&label=dsh%20plugin&color=blue)](https://www.npmjs.com/package/dsh-plugin-molio)
--- 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](https://molio.cn/resources.html) ships ready-made knowledge bases that keep growing β€” import one and start asking.
[Zizhi Tongjian knowledge base demo](https://molio.cn/videos/zizhitongjian-overview-v2.mp4) **β–Ά 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](https://chromewebstore.google.com/detail/pjdacbbkjpegfkogoieejajljplngbik), 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](https://molio.cn/resource/01M110NNMKNWXKBXT01HVJ06ZW.html) - [*Jin Ping Mei*: people, commerce and social structure](https://molio.cn/resource/01M2GAA83Q83CMQZPN40T9GQZ8.html) - [*Shiji* (Records of the Grand Historian): people, institutions, thought](https://molio.cn/resource/01M10WWK7WNMM61QNJJJXHNWS2.html) - [*Zizhi Tongjian*: 1,362 years of rise and fall](https://molio.cn/resource/01M10RZP9118BA6YRBZ1D4FKM2.html) - [*History of Ming*: empire, institutions and court politics](https://molio.cn/resource/01M111M5CSYX96FTKGC3V1QC2T.html) - [*Zhouyi*: all 64 hexagrams, with line-change and image-number analysis](https://molio.cn/resource/01M12YMV1144F4RZMX1HBK8GQ0.html) - [Laozi & Zhuangzi: core concept system](https://molio.cn/resource/01M114523M19P4J7GZMZ7E6188.html) - [Chinese and Western philosophy: a knowledge base for local AI](https://molio.cn/resource/01M10MC4S9ZH54WVFCXJWZ2JWS.html) - [Traditional Chinese medicine classics: six-meridian and triple-burner pattern differentiation](https://molio.cn/resource/01M112AA9MV91T3FJD5Z2GSPY8.html) - [Obstetric and gynecologic ultrasound: fetal anomalies, signs and differential diagnosis](https://molio.cn/resource/01M1152PE8YE365S9ZXDMNYCW6.html) - [Knowledge engineering: ontology, RAG, GraphRAG and agent engineering](https://molio.cn/resource/01M13QT669Q6E94PWACEH00YJF.html) - [Guangdong gaokao application planning: universities and majors](https://molio.cn/resource/01M2DFJ9E66FARK5SEBMPT92K0.html) - [*Romance of the Three Kingdoms*: character relationship map, all 120 chapters](https://molio.cn/resource/01M35RVX9S3TQK6ZE0QT9J6NG4.html) - [Drawing data extraction: from engineering drawings to computable data](https://molio.cn/resource/01M35QEB3RMK46SGCQ6WSZ3GZR.html) - [PCB flexible manufacturing: from online order to lights-out factory](https://molio.cn/resource/01M3VX66XMG5NHQ5HP9TK0Q2DC.html) - [Bar exam criminal law: 131 exam points and subjective-question training](https://molio.cn/resource/01M2QAYVBMH2YCF68BEA393BY4.html) - [Chinese classical poetry and prose: a panoramic knowledge base](https://molio.cn/resource/01M3VY2DZXW6KN1X5AFP7PXJ05.html) **[Browse all resources β†’](https://molio.cn/resources.html)** ### πŸ“‘ 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
AI Chat
Agent Workbench: multi-agent support with streaming responses 		Knowledge Space
Knowledge Space: vault file tree with Markdown rendering
Knowledge Graph
Knowledge Graph: visual map of your knowledge connections 		Publishing
Publishing: one-click sync to 30+ platforms
## πŸš€ Quick Start ### Installation Download the latest release from [GitHub Releases](https://github.com/zhuzhaoyun/Molio/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): ```bash # 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://: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`): ```bash 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://:3100 ``` **Everyday commands** (run inside the install directory, default `~/molio`): ```bash 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`](install.sh) and [`.env.example`](.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](https://claude.ai/claude-code) - [OpenAI Codex CLI](https://github.com/openai/codex) - [Gemini CLI](https://github.com/google-gemini/gemini-cli) - [Qwen Code](https://github.com/QwenLM/qwen-code) ```bash # 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:** ```bash # 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:** ```bash 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: ```bash 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: ```json { "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`](apps/cli/README.md) Β· [npm: @molio/cli](https://www.npmjs.com/package/@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: ```bash 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`](packages/dsh-plugin-molio/README.md) Β· [npm: dsh-plugin-molio](https://www.npmjs.com/package/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: ```bash 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 β†’](https://molio.cn/enterprise.html)** ## 🀝 Contributing Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. **Key principles:** - All changes must go through Pull Request (no direct pushes to `main`) - Follow [Conventional Commits](https://www.conventionalcommits.org/): `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](https://github.com/zhuzhaoyun/Molio/issues), or scan the QR code below to join our WeChat community: WeChat Community QR Code ## ❀️ Acknowledgments Molio is inspired and supported by these excellent open-source projects: - **[multica](https://github.com/multica-ai/multica)** β€” Open-source Agent management platform, inspiring Molio's multi-runtime orchestration - **[doocs/md](https://github.com/doocs/md)** β€” WeChat Markdown editor, powering Molio's typesetting engine - **[doocs/cose](https://github.com/doocs/cose)** β€” Multi-platform content distribution extension, powering Molio's publishing capabilities - **[WeKnora](https://github.com/Tencent/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](LICENSE) β€” 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](https://github.com/zhuzhaoyun/Molio)!** [⭐ Star](https://github.com/zhuzhaoyun/Molio) Β· [πŸ› Report Bug](https://github.com/zhuzhaoyun/Molio/issues) Β· [πŸ’‘ Request Feature](https://github.com/zhuzhaoyun/Molio/issues)