MindOS

MindOS

Human Thinks Here, Agent Acts There.

English | 中文

MindOS is a Human-AI Collaborative Mind System—a local-first knowledge base that ensures your notes, workflows, and personal context are both human-readable and directly executable by Agents. One shared memory layer for all Agents — auditable, correctable, and smarter with every use.

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

Read my MindOS knowledge base, see what's inside, then help me write my self-introduction into Profile.

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

No more fragmented memory, no more black-box behavior, no more lost experience.

1. Global Sync — Breaking Memory Silos

Each Agent keeps its own memory — switching tools means manually hauling context. MindOS lets all Agents share one knowledge base via MCP and Skills — record once, reuse everywhere.

2. Transparent & Controllable — No More Black Boxes

What did your Agent remember? Is it even correct? You have no way to know. MindOS saves every read/write as local plain text — humans can audit, correct, and delete in the GUI.

3. Symbiotic Evolution — Experience Flows Back as Instructions

All that experience from your conversations — gone the moment you close the window. MindOS auto-distills conversation experience into Skills/SOPs. Notes are instructions. The knowledge base gets better with use.

Foundation: Local-first by default — all data stays in local plain text for privacy, ownership, and speed.

✨ Features

For Humans

• GUI Collaboration Workbench: use one command entry to browse, edit, and search efficiently (⌘K / ⌘/).
• Built-in Agent Assistant: converse in context while edits are captured into managed knowledge.
• Plugin Views: use scenario-focused views like TODO, Kanban, and Timeline.

For Agents

• MCP Server + Skills: connect any compatible agent to read, write, search, and run workflows.
• Structured Templates: start quickly with Profile, Workflows, and Configurations scaffolds.
• Experience Auto-Distillation: automatically distill daily work into reusable, executable SOP experience.

Infrastructure

• Security: Bearer Token auth, path sandboxing, INSTRUCTION.md write-protection, atomic writes.
• Knowledge Graph: visualize relationships and dependencies across notes.
• Git Time Machine: track every edit, audit history, and roll back safely.
• Cross-Device Sync: auto-commit, push, and pull via Git — edits on one device appear on all others within minutes.

• ACP (Agent Communication Protocol): connect external Agents (e.g., Claude Code, Cursor) and turn the knowledge base into a multi-Agent collaboration hub
• Deep RAG integration: retrieval-augmented generation grounded in your knowledge base for more accurate, context-aware AI responses
• Backlinks View: display all files that reference the current file, helping you understand how a note fits into the knowledge network
• Agent Inspector: render Agent operation logs as a filterable timeline to audit every tool call in detail

🚀 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 will guide you through:

1. Knowledge base path → default ~/MindOS
2. Choose template (en / zh / empty / custom)
3. Ports (Web UI + MCP)
4. Auth token (auto-generated or passphrase-seeded)
5. Web UI password (optional)
6. AI Provider (Anthropic / OpenAI) + API Key — or skip to configure later via mindos config set
7. Start mode — Background service (recommended, auto-starts on boot) or Foreground

Config is saved to ~/.mindos/config.json automatically.

{
  "mindRoot": "~/MindOS",
  "port": 3000,
  "mcpPort": 8787,
  "authToken": "",
  "webPassword": "",
  "startMode": "daemon",
  "ai": {
    "provider": "anthropic",
    "providers": {
      "anthropic": { "apiKey": "sk-ant-...", "model": "claude-sonnet-4-6" },
      "openai":    { "apiKey": "sk-...",     "model": "gpt-5.4", "baseUrl": "" }
    }
  },
  "sync": {
    "enabled": true,
    "provider": "git",
    "remote": "origin",
    "branch": "main",
    "autoCommitInterval": 30,
    "autoPullInterval": 300
  }
}

Multiple providers can be configured simultaneously — switch between them by changing ai.provider. Shell env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) take precedence over config file values.

[!NOTE]If you want the MindOS GUI to be reachable from other devices, make sure the port is open in firewall/security-group settings and bound to an accessible host/network interface.

[!TIP]If you chose "Background service" during onboard, MindOS is installed as a background OS service and starts automatically — no need to run mindos start manually. Run mindos update to upgrade to the latest version.

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)

4.1 Configure MindOS MCP

Run one command to auto-install MCP config into your Agent:

mindos mcp install

Supports Claude Code, Cursor, Windsurf, Cline, Trae, Gemini CLI, and more — interactively guides you through agent, scope, transport, and token.

Local (Agent and MindOS on the same machine)

Use stdio transport — no server process needed, most reliable:

# Interactive
mindos mcp install

# One-shot, global scope (shared across all projects)
mindos mcp install -g -y

Remote (Agent on a different machine)

Use http transport — MindOS must be running (mindos start) on the remote machine:

mindos mcp install--transport http --url http://<server-ip>:8787/mcp --token your-token -g

[!NOTE]For remote access, ensure port 8787 is open in your firewall/security-group.

Add -g to install globally — MCP config is shared across all projects instead of the current directory only.

The MCP port defaults to 8787. To use a different port, run mindos onboard and set mcpPort.

Local via stdio (no server process needed):

{
  "mcpServers": {
    "mindos": {
      "type": "stdio",
      "command": "mindos",
      "args": ["mcp"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

Local via URL:

{
  "mcpServers": {
    "mindos": {
      "url": "http://localhost:8787/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Remote:

{
  "mcpServers": {
    "mindos": {
      "url": "http://<server-ip>:8787/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Each Agent stores config in a different file — see the MCP Config Path column in the Supported Agents table for exact paths.

4.2 Install MindOS Skills

Install one skill only (choose based on your preferred language):

# English
npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y

# Chinese (optional)
npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y

MCP = connection capability, Skills = workflow capability. Enabling both gives the complete MindOS agent experience.

4.3 Common Pitfalls

• Only MCP, no Skills: tools are callable, but best-practice workflows are missing.
• Only Skills, no MCP: workflow guidance exists, but the Agent cannot operate your local knowledge base.
• MIND_ROOT is not an absolute path: MCP tool calls will fail.
• No authToken set: your API and MCP server are exposed on the network without protection.
• No webPassword set: anyone who can reach your server can access the web UI.

⚙️ How It Works

A fleeting idea becomes shared intelligence through three interlocking loops:

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.

Collaboration Loop (Human + Multi-Agent)

1. Human reviews and updates notes/SOPs in the MindOS GUI (single source of truth).
2. Other Agent clients (OpenClaw, Claude Code, Cursor, etc.) connect through MCP and read the same memory/context.
3. With Skills enabled, those Agents execute workflows and SOP tasks in a guided way.
4. Execution results are written back to MindOS so humans can audit and refine continuously.

Who is this for?

• Independent Developer — Store personal SOPs, tech stack preferences, and project context in MindOS. Any Agent instantly inherits your work habits.
• Knowledge Worker — Manage research materials with bi-directional links. Your AI assistant answers questions grounded in your full context, not generic knowledge.
• Team Collaboration — Share a MindOS knowledge base across team members as a single source of truth. Humans and Agents read from the same playbook, keeping everyone aligned.
• Automated Agent Operations — Write standard workflows as Agent-Ready documents. Agents execute directly, humans audit the results.

🤝 Supported Agents

📁 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 entry point (`mindos onboard`, `mindos start`, `mindos open`, `mindos sync`, `mindos token`)
├── 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)
└── my-mind/          # Your private knowledge base (default path, customizable on onboard)

⌨️ CLI Commands

⌨️ Keyboard Shortcuts

💬 Community

Join our WeChat group for early access, feedback, and AI workflow discussions:

Scan the QR code or ask an existing member to invite you.

📄 License

MIT © GeminiLight