MindOS

<p align="center"> <img src="assets/logo-square.svg" alt="MindOS" width="100" /> </p> <h1 align="center">MindOS</h1> <p align="center"> <strong>Human Thinks Here, Agents Act There.</strong> </p> <p align="center"> <a href="README.md">English</a> | <a href="README_zh.md">中文</a> </p> <p align="center"> <a href="https://tianfuwang.tech/MindOS"><img src="https://img.shields.io/badge/Website-MindOS-0ea5e9.svg?style=for-the-badge" alt="Website"></a> <a href="https://www.npmjs.com/package/@geminilight/mindos"><img src="https://img.shields.io/npm/v/@geminilight/mindos.svg?style=for-the-badge&color=6366f1" alt="npm version"></a> <a href="#wechat"><img src="https://img.shields.io/badge/WeChat-Group-07C160.svg?style=for-the-badge&logo=wechat&logoColor=white" alt="WeChat"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-64748b.svg?style=for-the-badge" alt="MIT License"></a> </p> <p align="center"> <a href="https://github.com/GeminiLight/MindOS/releases?q=desktop"><img src="https://img.shields.io/badge/Desktop_App-Download-d97706.svg?style=for-the-badge" alt="Desktop App"></a> <a href="https://github.com/GeminiLight/MindOS/releases?q=clipper"><img src="https://img.shields.io/badge/Web_Clipper-Install-c8873a.svg?style=for-the-badge" alt="Web Clipper"></a> </p> MindOS is where you think, and where your AI agents act — a local-first knowledge base shared between you and every AI you use. **Share your brain with every AI — every thought grows.** --- <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/images/demo-flow-dark.webp" type="image/webp" /> <source media="(prefers-color-scheme: dark)" srcset="assets/images/demo-flow-dark.png" /> <source media="(prefers-color-scheme: light)" srcset="assets/images/demo-flow-light.webp" type="image/webp" /> <source media="(prefers-color-scheme: light)" srcset="assets/images/demo-flow-light.png" /> <img src="assets/images/demo-flow-light.png" alt="MindOS: From Idea to Execution to Review" width="960" /> </picture> </p> <table> <tr> <td width="50%"> <picture> <source srcset="assets/images/mindos-home.webp" type="image/webp" /> <img src="assets/images/mindos-home.png" alt="MindOS Home" /> </picture> </td> <td width="50%"> <picture> <source srcset="assets/images/mindos-chat.webp" type="image/webp" /> <img src="assets/images/mindos-chat.png" alt="MindOS AI Agent" /> </picture> </td> </tr> <tr> <td align="center"><em>Home — Knowledge base overview</em></td> <td align="center"><em>AI Agent — Proactively understand intent and execute tasks from your knowledge</em></td> </tr> <tr> <td width="50%"> <picture> <source srcset="assets/images/mindos-dashboard.webp" type="image/webp" /> <img src="assets/images/mindos-dashboard.png" alt="MindOS Agents Dashboard" /> </picture> </td> <td width="50%"> <picture> <source srcset="assets/images/mindos-echo.webp" type="image/webp" /> <img src="assets/images/mindos-echo.png" alt="MindOS Echo" /> </picture> </td> </tr> <tr> <td align="center"><em>Agents — Manage all connected AI agents</em></td> <td align="center"><em>Echo — Reflect and distill cognitive growth</em></td> </tr> </table> > [!IMPORTANT] > **⭐ One-click install:** Send this to your Agent (Claude Code, Cursor, etc.) to set up everything automatically: > ``` > Help me install MindOS from https://github.com/GeminiLight/MindOS with MCP and Skills. Use English template. > ``` > > **✨ Try it now:** After installation, give these a try: > ``` > Here's my resume, read it and organize my info into MindOS. > ``` > ``` > Help me distill the experience from this conversation into MindOS as a reusable SOP. > ``` > ``` > Help me execute the XXX SOP from MindOS. > ``` ## 📢 What's New | Date | Update | |------|--------| | 2026-04 | **Protocol runtimes internalized** — ACP and MCP source now live under `packages/mindos/src/protocols/*`; the published package ships self-contained `dist/protocols/*` bundles instead of nested protocol packages. | | 2026-04 | **Product main package** — MindOS now follows an OpenCode-style core package: `packages/mindos` (`@geminilight/mindos`) is the product runtime facade and CLI kernel boundary; Web/CLI adapt around it. | | 2026-04 | **OpenCode-style workspace flattening** — all source workspaces now live under `packages/`: `packages/web`, `packages/desktop`, `packages/mobile`, `packages/mindos`, and optional `packages/retrieval/*` adapters. npm tarball, CLI, MCP, Web standalone, Desktop, and Mobile checks have passed. | | 2026-04 | **Clean publish package** — legacy top-level `app/`, `mcp/`, `desktop/`, and `mobile/` source roots are removed; publish entries exclude tests, caches, and nested `node_modules`. | | 2026-04 | **Web Clipper** — Browser extension to clip any web page to your MindOS Inbox with one click. [Get it →](packages/browser-extension/) | | 2026-04 | **PDF & Image Import** — Drag PDFs and images into MindOS, auto-converted to searchable Markdown. | ## 🧠 Human-AI Shared Mind > You shape AI through thinking, AI empowers you through execution. Human and AI, growing together in one shared brain. **1. Global Sync — Breaking Memory Silos** Switch tools or start a new chat and you're re-transporting context, scattering knowledge. **With a built-in MCP server, MindOS connects all Agents to your core knowledge base with zero config. Record profile and project memory once to empower all AI tools.** **2. Transparent & Controllable — No Black Boxes** Agent memory locked in black boxes makes reasoning unauditable, erasing trust as hallucinations compound. **MindOS saves every retrieval, reflection & action as local plain text. You hold absolute mind-correction rights with a full GUI to recalibrate Agents anytime.** **3. Symbiotic Evolution — Experience Flows Back As Instructions** You express preferences but the next chat starts from zero, leaving your thinking useless for AI. **MindOS auto-distills every thought into your knowledge base. Clarify your standards through interaction and sharpen your cognition with each iteration — AI will never repeat the same mistake.** > **Foundation:** Local-first by default — all data stays in local plain text for privacy, ownership, and speed. --- ## 🚀 Getting Started > [!IMPORTANT] > **Quick Start with Agent:** Paste this prompt into any MCP-capable Agent (Claude Code, Cursor, etc.) to install automatically, then skip to [Step 3](#3-inject-your-personal-mind-with-mindos-agent): > ``` > Help me install MindOS from https://github.com/GeminiLight/MindOS with MCP and Skills. Use English template. > ``` > Already have a knowledge base? Skip to [Step 4](#4-make-any-agent-ready-mcp--skills) to configure MCP + Skills. ### 1. Install **Option A: Desktop App (macOS / Windows / Linux)** Download from the [official website](https://tianfuwang.tech/MindOS/#quickstart) or [GitHub Releases](https://github.com/GeminiLight/MindOS/releases/latest) — double-click to install, no terminal needed. **Option B: npm** ```bash npm install -g @geminilight/mindos@latest ``` **Option C: Clone from source** ```bash git clone https://github.com/GeminiLight/MindOS cd MindOS pnpm install pnpm link --global # registers the `mindos` command globally ``` The npm package intentionally installs both the CLI and the prebuilt local Web runtime. `mindos` is the command entrypoint, while `_standalone/` provides the browser UI used by `mindos start` / `mindos open`; Web source (`packages/web`), tests, wiki, legacy source roots, and dev caches are excluded from the tarball. ### 2. Interactive Setup ```bash mindos onboard ``` The setup wizard guides you through knowledge base path, template, ports, auth, AI provider, and start mode — all with sensible defaults. Config is saved to `~/.mindos/config.json`. See **[docs/en/configuration.md](docs/en/configuration.md)** for all fields. > [!TIP] > Choose "Background service" during onboard for auto-start on boot. Run `mindos update` anytime to upgrade. Open the Web UI in your browser: ```bash mindos open ``` ### 3. Inject Your Personal Mind with MindOS Agent 1. Open the built-in MindOS Agent chat panel in the GUI. 2. Upload your resume or any personal/project material. 3. Send this prompt: `Help me sync this information into my MindOS knowledge base.` ### 4. Make Any Agent Ready (MCP + Skills) **MCP** (connection) — one command to auto-install: ```bash mindos mcp install # interactive mindos mcp install -g -y # one-shot, global scope ``` **Skills** (workflow) — install one based on your language: ```bash npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y # English npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y # Chinese ``` > For remote access, manual JSON config, and common pitfalls, see **[docs/en/supported-agents.md](docs/en/supported-agents.md)**. ### 5. Capture from Anywhere MindOS knowledge doesn't have to start from scratch — bring in what you already have: - **Drag & Drop**: drop files (PDF, images, Markdown, CSV) into the MindOS GUI — AI auto-organizes them into the right folders. - **Web Clipper**: install the [browser extension](packages/browser-extension/) to save any web page to your Inbox with one click. Ctrl+Shift+M or right-click → "Save to MindOS". - **Agent Import**: tell any connected Agent to read a document and sync it into your knowledge base. ## ✨ Features **For Humans** - **GUI Workbench**: browse, edit, search notes with unified search + AI entry (`⌘K` / `⌘/`), designed for human-AI co-creation. - **Built-in Agent Assistant**: converse with the knowledge base in context; edits seamlessly capture human-curated knowledge. - **One-Click Import**: drag-and-drop files with Inline AI Organize — auto-analyzes, categorizes, and writes into the knowledge base with progress tracking and undo support. - **Guided Onboarding**: step-by-step first-run experience that helps new users set up their knowledge base and connect their first Agent. - **Plugin Extensions**: multiple built-in renderer plugins — TODO Board, CSV Views, Wiki Graph, Timeline, Workflow Editor, Agent Inspector, and more. - **Web Clipper**: browser extension to clip any web page as clean Markdown — one click, saves to Inbox for later AI-powered organizing. [Install →](packages/browser-extension/) **For Agents** - **MCP Server + Skills**: stdio + HTTP dual transport, full-lineup Agent compatible (Claude Code, Cursor, Gemini CLI, etc.). Zero-config access. - **ACP / A2A Protocols**: Agent communication protocols for discovery, delegation, and orchestration. Phase 1 is live with Agent Card discovery + JSON-RPC messaging. - **Workflow Orchestration**: YAML-based workflow editor with step execution engine — define, edit, and run multi-step agent workflows visually. - **Structured Templates**: pre-set directory structures for Profiles, Workflows, Configurations, etc., to jumpstart personal context. - **Agent-Ready Docs**: everyday notes naturally double as high-quality executable Agent commands — no format conversion needed, write and dispatch. **Infrastructure** - **Security**: Bearer Token auth, path sandboxing, INSTRUCTION.md write-protection, atomic writes. - **Knowledge Graph**: dynamically parses and visualizes inter-file references and dependencies. - **Backlinks View**: displays all files that reference the current file, helping you understand how a note fits into the knowledge network. - **Agent Inspector**: renders Agent operation logs as a filterable timeline to audit every tool call in detail. - **Git Time Machine**: Git auto-sync (commit/push/pull), records every edit by both humans and Agents. One-click rollback, cross-device sync. - **Desktop App**: native macOS/Windows/Linux app with system tray, auto-start, and local process management. <details> <summary><strong>Coming Soon</strong></summary> - [ ] Deep RAG integration: retrieval-augmented generation grounded in your knowledge base for more accurate, context-aware AI responses - [ ] ACP / A2A Phase 2: deep multi-agent collaboration with task delegation, shared context, and workflow chaining - [ ] Experience Compiler: auto-extract corrections and preferences from agent interactions into reusable Skills/SOPs - [ ] Knowledge Health Dashboard: visualize cognitive compound metrics — rules accumulated, agent reuse count, knowledge freshness </details> ## ⚙️ How It Works ```mermaid graph LR H["👤 Human<br/><sub>thinks · reviews · evolves</sub>"] M[("📚 MindOS")] A["🤖 Agent<br/><sub>executes · retrospects · extracts SOPs</sub>"] EXT["🌐 All Agents"] H -- "ideas & feedback" --> M M -- "context & insights" --> H M -- "instructions & context" --> A A -- "results & SOPs" --> M M -. "via MCP" .-> EXT style H fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px style M fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px style A fill:#6366f1,stroke:#4f46e5,color:#fff,stroke-width:2px style EXT fill:#64748b,stroke:#475569,color:#fff,stroke-dasharray:5 5 ``` > **Both sides evolve.** Humans gain new insights from accumulated knowledge; Agents extract SOPs and get smarter. MindOS sits at the center — the shared second brain that grows with every interaction. --- ## 🤝 Supported Agents > The current registry supports 26 Agents. Full list with MCP config paths and manual setup: **[docs/en/supported-agents.md](docs/en/supported-agents.md)** | Agent | MCP | Skills | |:------|:---:|:------:| | OpenClaw | ✅ | ✅ | | Claude Code | ✅ | ✅ | | Cursor | ✅ | ✅ | | Codex | ✅ | ✅ | | Gemini CLI | ✅ | ✅ | | GitHub Copilot | ✅ | ✅ | | Trae | ✅ | ✅ | | CodeBuddy | ✅ | ✅ | | Qoder | ✅ | ✅ | | Cline | ✅ | ✅ | | Windsurf | ✅ | ✅ | | Hermes | ✅ | - | --- ## 📁 Project Structure ```bash MindOS/ ├── packages/web/ # Next.js 16 frontend — browse, edit, and interact with AI ├── packages/desktop/ # Electron desktop client ├── packages/mobile/ # Expo mobile app ├── packages/browser-extension/ # Web Clipper browser extension ├── packages/desktop-tauri/ # Tauri desktop spike ├── packages/mindos/ # Published product package: runtime facade, protocols, foundation/knowledge internals, CLI kernel ├── packages/retrieval/ # Optional retrieval stack: search, vector, indexer, API ├── skills/ # MindOS Skills (`mindos`, `mindos-zh`) — workflow guides for Agents ├── templates/ # Preset templates (`en/`, `zh/`, `empty/`) — copied to knowledge base on onboard ├── scripts/ # Setup wizard and helper scripts └── README.md ~/.mindos/ # User data directory (outside project, never committed) ├── config.json # All configuration (AI keys, port, auth token, sync settings) ├── sync-state.json # Sync state (last sync time, conflicts) └── mind/ # Your private knowledge base (default path, customizable on onboard) ``` > In v1, top-level `app/`, `apps/`, `mcp/`, `desktop/`, `mobile/`, `browser-extension/`, `desktop-tauri/`, and root `bin/` are no longer source roots. The repo root is a private monorepo orchestrator. `packages/mindos` is the OpenCode-style published product package (`@geminilight/mindos`): its repo CLI entry is `packages/mindos/bin/cli.js`, installed npm users still receive the package-relative `bin/cli.js`, and the prebuilt local Web runtime is published as `_standalone/`. `packages/web` remains the only Web source tree and is not copied into the npm tarball. During `npm pack` / publish, `packages/mindos/_standalone`, `packages/mindos/packages`, `packages/mindos/scripts`, `packages/mindos/assets`, `packages/mindos/skills`, and `packages/mindos/templates` may be generated as staging output; they are ignored, excluded from pnpm workspace discovery, and cleaned by `pnpm run clean:product-stage` or product `postpack`. ## ⌨️ CLI Commands > Full command reference: **[docs/en/cli-commands.md](docs/en/cli-commands.md)** | Command | Description | | :--- | :--- | | **Core** | | | `mindos onboard` | Interactive setup (config, template, start mode) | | `mindos start` | Start Web + MCP services | | `mindos start --daemon` | Start as background OS service | | `mindos stop` / `restart` | Stop or restart running processes | | `mindos dev` | Start in dev mode | | `mindos build` | Build for production | | `mindos status` | Show service status overview | | `mindos open` | Open Web UI in browser | | **Knowledge** | | | `mindos file <sub>` | File operations (list, read, create, delete, search) | | `mindos space <sub>` | Space management (list, create, info) | | `mindos search "<query>"` | Search knowledge base | | `mindos ask "<question>"` | Ask AI using your knowledge base | | `mindos agent <sub>` | AI Agent management (list, info) | | `mindos channel` / `mindos feishu-ws` | IM channel config and Feishu long connection | | `mindos api <METHOD> <path>` | Raw API passthrough for developers/agents | | **MCP & Config** | | | `mindos mcp install` | Auto-install MCP config into your Agent | | `mindos token` | Show auth token and MCP config | | `mindos config <sub>` | View/update config (show, set, validate) | | `mindos sync` | Show sync status (init, now, conflicts, on/off) | | `mindos gateway <sub>` | Manage background service (install, start, stop) | | `mindos doctor` | Health check | | `mindos update` | Update to latest version | **Main keyboard shortcuts:** `⌘K` Search · `⌘/` AI Assistant · `E` Edit · `⌘S` Save · `Esc` Close. --- ## 💬 Community <a name="wechat"></a> Join our WeChat group for early access, feedback, and AI workflow discussions: <p align="center"> <img src="assets/images/wechat-qr.png" alt="WeChat Group QR Code" width="200" /> </p> > Scan the QR code or add WeChat **wtfly2018** to be invited. --- ## 👥 Contributors <a href="https://github.com/GeminiLight"><img src="https://github.com/GeminiLight.png" width="60" style="border-radius:50%" alt="GeminiLight" /></a> <a href="https://github.com/yeahjack"><img src="https://github.com/yeahjack.png" width="60" style="border-radius:50%" alt="yeahjack" /></a> <a href="https://github.com/USTChandsomeboy"><img src="https://github.com/USTChandsomeboy.png" width="60" style="border-radius:50%" alt="USTChandsomeboy" /></a> <a href="https://github.com/ppsmk388"><img src="https://github.com/ppsmk388.png" width="60" style="border-radius:50%" alt="ppsmk388" /></a> <a href="https://github.com/U-rara"><img src="https://github.com/U-rara.png" width="60" style="border-radius:50%" alt="U-rara" /></a> <a href="https://github.com/one2piece2hello"><img src="https://github.com/one2piece2hello.png" width="60" style="border-radius:50%" alt="one2piece2hello" /></a> <a href="https://github.com/zz-haooo"><img src="https://github.com/zz-haooo.png" width="60" style="border-radius:50%" alt="zz-haooo" /></a> <a href="https://github.com/zjpyb"><img src="https://github.com/zjpyb.png" width="60" style="border-radius:50%" alt="zjpyb" /></a> ### 🙏 Acknowledgements This project has been published on the [LINUX DO community](https://linux.do), and we deeply appreciate the community's support and feedback. --- ## 📄 License MIT © GeminiLight