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, Agent Acts 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=f59e0b" 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-6366f1.svg?style=for-the-badge" alt="MIT License"></a> </p>

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.

---

<p align="center"> <picture> <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.png" /> <img src="assets/images/demo-flow-light.png" alt="MindOS: From Idea to Execution to Review" width="960" /> </picture> </p>

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

<details> <summary><strong>Coming Soon</strong></summary>

• [ ] 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

</details>

---

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

<!-- For Agents: Before running setup, if the user has not provided LLM configuration, ask them:

1. AI Provider — anthropic or openai (compatible)?
2. API Key — the key for the chosen provider
3. Custom Base URL? — only needed for proxies or OpenAI-compatible endpoints; skip if using official API
4. Model ID — or use the default Or skip the wizard and edit ~/.mindos/config.json manually (see Config Reference below). -->

<details> <summary>Config Reference (~/.mindos/config.json)</summary>

{
  "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
  }
}

Field	Default	Description
mindRoot	~/MindOS	Required. Absolute path to the knowledge base root.
port	3000	Optional. Web app port.
mcpPort	8787	Optional. MCP server port.
authToken	—	Optional. Protects App /api/* and MCP /mcp with bearer token auth. For Agent / MCP clients. Recommended when exposed to a network.
webPassword	—	Optional. Protects the web UI with a login page. For browser access. Independent from authToken.
startMode	start	Start mode: daemon (background service, auto-starts on boot), start (foreground), or dev.
ai.provider	anthropic	Active provider: anthropic or openai.
ai.providers.anthropic.apiKey	—	Anthropic API key.
ai.providers.anthropic.model	claude-sonnet-4-6	Anthropic model ID.
ai.providers.openai.apiKey	—	OpenAI API key.
ai.providers.openai.model	gpt-5.4	OpenAI model ID.
ai.providers.openai.baseUrl	—	Optional. Custom endpoint for proxy or OpenAI-compatible APIs.
sync.enabled	false	Enable/disable automatic Git sync.
sync.provider	git	Sync provider (currently only git).
sync.remote	origin	Git remote name.
sync.branch	main	Git branch to sync.
sync.autoCommitInterval	30	Seconds after file change to auto-commit+push.
sync.autoPullInterval	300	Seconds between auto-pull from remote.

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.

</details>

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

<p align="center"> <img src="assets/images/gui-sync-cv.png" alt="Sync CV Example" width="800" /> </p>

4. Make Any Agent Ready (MCP + Skills)

4.1 Configure MindOS MCP

<!-- For Agents: Register MindOS MCP as global (user-level) config by default, so all projects share the same knowledge base. -->

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.

<details> <summary>Manual config (JSON snippets)</summary>

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.

</details>

4.2 Install MindOS Skills

Skill	Description
mindos	Knowledge base operation guide (English) — read/write notes, search, manage SOPs, maintain Profiles
mindos-zh	Knowledge base operation guide (Chinese) — same capabilities, Chinese interface

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

Agent	MCP	Skills	MCP Config Path
MindOS Agent	✅	✅	Built-in (no config needed)
OpenClaw	✅	✅	~/.openclaw/openclaw.json or ~/.openclaw/mcp.json
Claude Desktop	✅	✅	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	✅	✅	~/.claude.json (global) or .mcp.json (project)
CodeBuddy	✅	✅	~/.claude-internal/.claude.json (global)
Cursor	✅	✅	~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
Windsurf	✅	✅	~/.codeium/windsurf/mcp_config.json
Cline	✅	✅	macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json; Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Trae	✅	✅	~/.trae/mcp.json (global) or .trae/mcp.json (project)
Gemini CLI	✅	✅	~/.gemini/settings.json (global) or .gemini/settings.json (project)
GitHub Copilot	✅	✅	.vscode/mcp.json (project) or VS Code User settings.json (global)
iFlow	✅	✅	iFlow platform MCP configuration panel

---

📁 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

Command	Description
mindos onboard	Interactive setup (config, template, start mode)
mindos start	Start app + MCP server (foreground, production mode)
mindos start --daemon	Install + start as a background OS service (survives terminal close, auto-restarts on crash)
mindos dev	Start app + MCP server (dev mode, hot reload)
mindos dev --turbopack	Dev mode with Turbopack (faster HMR)
mindos open	Open the Web UI in the default browser
mindos stop	Stop running MindOS processes
mindos restart	Stop then start again
mindos build	Manually build for production
mindos mcp	Start MCP server only
mindos token	Show auth token and per-agent MCP config snippets
mindos sync	Show sync status (alias for sync status)
mindos sync init	Interactive setup for Git remote sync
mindos sync status	Show sync status: last sync, unpushed commits, conflicts
mindos sync now	Manually trigger a full sync (commit + push + pull)
mindos sync on	Enable automatic sync
mindos sync off	Disable automatic sync
mindos sync conflicts	List unresolved conflict files
mindos gateway install	Install background service (systemd on Linux, LaunchAgent on macOS)
mindos gateway uninstall	Remove background service
mindos gateway start	Start the background service
mindos gateway stop	Stop the background service
mindos gateway status	Show background service status
mindos gateway logs	Tail background service logs
mindos doctor	Health check (config, ports, build, daemon status)
mindos update	Update MindOS to the latest version
mindos logs	Tail service logs (~/.mindos/mindos.log)
mindos config show	Print current config (API keys masked)
mindos config validate	Validate config file
mindos config set <key> <val>	Update a single config field
mindos	Start using the mode saved in ~/.mindos/config.json

---

⌨️ Keyboard Shortcuts

Shortcut	Function
⌘ + K	Global Search
⌘ + /	Call AI Assistant / Sidebar
E	Press E in View mode to quickly enter Edit mode
⌘ + S	Save current edit
Esc	Cancel edit / Close dialog

---

💬 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 ask an existing member to invite you.

---

📄 License

MIT © GeminiLight