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.

🧠 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: npm (recommended)

npm install -g @geminilight/mindos@latest

Option B: Clone from source

git clone https://github.com/GeminiLight/MindOS
cd MindOS
npm install
npm link   # registers the `mindos` command globally

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.

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

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 Protocol for inter-agent discovery, delegation, and orchestration. Phase 1 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

Full list with MCP config paths and manual setup: docs/en/supported-agents.md

📁 Project Structure

MindOS/
├── app/              # Next.js 16 Frontend — Browse, edit, and interact with AI
├── mcp/              # MCP Server — HTTP adapter that maps tools to App API
├── skills/           # MindOS Skills (`mindos`, `mindos-zh`) — Workflow guides for Agents
├── templates/        # Preset templates (`en/`, `zh/`, `empty/`) — copied to knowledge base on onboard
├── bin/              # CLI (`mindos start`, `mindos file`, `mindos ask`, `mindos agent`, ... 22 commands)
├── 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: ~/MindOS/mind, customizable on onboard)

⌨️ CLI Commands

Full command reference: docs/en/cli-commands.md

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/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/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/one2piece2hello"><img src="https://github.com/one2piece2hello.png" width="60" style="border-radius:50%" alt="one2piece2hello" /></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