GeminiLight/MindOS

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.

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

🧠 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:

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 to configure MCP + Skills.

1. Install

Option A: Desktop App (macOS / Windows / Linux)

Download from the official website or GitHub Releases — double-click to install, no terminal needed.

Option B: npm

npm install -g @geminilight/mindos@latest

Option C: Clone from source

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

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 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:

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:

mindos mcp install        # interactive
mindos mcp install -g -y  # one-shot, global scope

Skills (workflow) — install one based on your language:

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.

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 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 →

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.

• 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

⚙️ How It Works

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

📁 Project Structure

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

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:

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, and we deeply appreciate the community's support and feedback.

📄 License

MIT © GeminiLight