@geminilight/mindos

v0.5.8

Published

4 hours ago

MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.

0High
0Medium
0Low

geminilight

mindos mcp knowledge-base ai-agent local-first second-brain

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:

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.

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

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

| 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)
└── my-mind/          # Your private knowledge base (default path, customizable on onboard)

⌨️ CLI Commands

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