MindOS

Human Thinks Here, Agent Acts There.

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.

MindOS: From Idea to Execution to Review

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 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.
Plugin Extensions: multiple built-in renderer plugins — TODO Board, CSV Views, Wiki Graph, Timeline, Agent Inspector, and more.

For Agents

MCP Server + Skills: stdio + HTTP dual transport, full-lineup Agent compatible (OpenClaw, Claude Code, Cursor, etc.). Zero-config access.
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.
Git Time Machine: Git auto-sync (commit/push/pull), records every edit by both humans and Agents. One-click rollback, cross-device sync.

Coming Soon

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:

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

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

Config Reference (~/.mindos/config.json)

{
  "mindRoot": "~/MindOS",
  "port": 3456,
  "mcpPort": 8781,
  "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`	`3456`	Optional. Web app port.
`mcpPort`	`8781`	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.

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

Open the built-in MindOS Agent chat panel in the GUI.
Upload your resume or any personal/project material.
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>:8781/mcp --token your-token -g

Note

For remote access, ensure port 8781 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 8781. To use a different port, run mindos onboard and set mcpPort.

Manual config (JSON snippets)

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:8781/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Remote:

{
  "mcpServers": {
    "mindos": {
      "url": "http://<server-ip>:8781/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

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)

Human reviews and updates notes/SOPs in the MindOS GUI (single source of truth).
Other Agent clients (OpenClaw, Claude Code, Cursor, etc.) connect through MCP and read the same memory/context.
With Skills enabled, those Agents execute workflows and SOP tasks in a guided way.
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)
└── mind/             # Your private knowledge base (default: ~/MindOS/mind, 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 uninstall`	Fully uninstall MindOS (stop, remove daemon, npm uninstall)
`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

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

Scan the QR code or add WeChat wtfly2018 to be invited.

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
app		app
assets		assets
bin		bin
mcp		mcp
scripts		scripts
skills		skills
templates		templates
tests		tests
wiki		wiki
.env.local.example		.env.local.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MindOS

🧠 Human-AI Shared Mind

✨ Features

🚀 Getting Started

1. Install

2. Interactive Setup

3. Inject Your Personal Mind with MindOS Agent

4. Make Any Agent Ready (MCP + Skills)

4.1 Configure MindOS MCP

4.2 Install MindOS Skills

4.3 Common Pitfalls

⚙️ How It Works

🤝 Supported Agents

📁 Project Structure

⌨️ CLI Commands

⌨️ Keyboard Shortcuts

💬 Community

👥 Contributors

📄 License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

MindOS

🧠 Human-AI Shared Mind

✨ Features

🚀 Getting Started

1. Install

2. Interactive Setup

3. Inject Your Personal Mind with MindOS Agent

4. Make Any Agent Ready (MCP + Skills)

4.1 Configure MindOS MCP

4.2 Install MindOS Skills

4.3 Common Pitfalls

⚙️ How It Works

🤝 Supported Agents

📁 Project Structure

⌨️ CLI Commands

⌨️ Keyboard Shortcuts

💬 Community

👥 Contributors

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages