MindOS: a local Markdown base that agents read through MCP
MindOS is a Human-AI Collaborative Mind System, where human thinks and agents act. Globally sync your mind for all agents: transparent, controllable, and evolving symbiotically.
At a glance
- What is it?
- MindOS is a local-first knowledge base plus an MCP and Skills bridge, built so several AI agents can read and write the same plain-text context. The idea is sound and the delivery is wide; the documentation is thinner than the module table suggests.
- Who is it for?
- Adopt MindOS if you already keep notes in Markdown, you use an MCP-capable agent such as Claude Code or Cursor, and you want one local directory that several tools read instead of pasting context into each new chat. Do not adopt it if you need a hosted service with a server-side API and no desktop component, or if your team cannot maintain a Markdown tree by hand.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem MindOS targets: context that dies with each chat
The README frames the problem in terms of memory silos. You switch tools or open a new chat and re-transport the same context, and the knowledge scatters. MindOS answers that with a single local knowledge base that supported agents reach through a built-in MCP server and packaged Skills. Record profile and project memory once, the README says, then reuse it across your AI tools. The audience is narrow and specific: people who already run MCP-capable agents such as Claude Code or Cursor, and who want those agents to work from a directory of their own notes rather than from whatever was pasted into the current session. It is not a chat product, and it is not a hosted memory API. The unit of value is the local plain-text base, which the README states is kept local for privacy, ownership, and speed.
How the pieces fit: workbench, MCP bridge, agent runtime
The repository describes itself as organized around stable modules rather than one-off setup scripts. The first is a local knowledge workbench, a desktop, web, or CLI workspace for browsing, editing, importing, searching, and organizing a Markdown knowledge base. The second is the MCP and Skills bridge: one command installs or repairs both the MCP config and the packaged MindOS Skill, and mindos doctor agents then verifies what the README calls real agent readiness. The third is a native agent runtime with resumable sessions, cancellation, reconnect and reattach support, and reviewable output history where the runtime exposes it. The fourth covers workflow and audit surfaces: YAML workflows, an Agent Inspector, run ledgers, backlinks, graph views, and importer progress. Delivery is cross-platform through desktop releases or an npm package that includes the CLI and a prebuilt local web runtime. The data flow implied by that layout is straightforward: agents call the MCP server, the server reads and writes files in the local Markdown base, and the workbench and audit surfaces let a human inspect what changed.
Install paths and the commands the README gives
There are two documented install routes. Desktop builds for macOS, Windows, and Linux are published on GitHub Releases and the project website; the README describes them as double-click to install, no terminal needed. The npm route is npm install -g @geminilight/mindos@latest, and the README notes the package carries the CLI plus a prebuilt local web runtime. The README also promotes an agent-assisted path: paste a prompt into any MCP-capable agent asking it to install MindOS from the GitHub URL with MCP and Skills, using the English template. That is convenient, but it delegates the actual configuration to a model, so the resulting MCP config is worth reading afterwards. The one verification command named in the material is mindos doctor agents, which the README says checks real agent readiness after the bridge is installed or repaired. Beyond that, the excerpt does not list the config file paths, the MCP server entry name, or the Skill directory layout, so treat those as things to read out of the installed package rather than assumptions.
Where the design is deliberately narrow
The local-first choice is the product's main constraint and its main selling point, and it cuts both ways. Plain-text files in a local directory give you ownership and speed, and they also mean there is no server-side sync, no hosted index, and no shared team workspace described in the material. If you work across two machines, the README does not describe a sync mechanism; you would be relying on your own file syncing, and the consequences of two agents writing the same note are not addressed in the excerpt. The audit surfaces, run ledgers, and Agent Inspector are qualified in the module table with the phrase where the runtime exposes it, which suggests coverage varies by agent rather than being uniform. The reviewable output history is only as complete as the underlying runtime allows. Anyone expecting a uniform audit trail across every connected agent should verify that per-agent behaviour before depending on it.
What a plain Markdown vault does differently
The obvious comparison is an ordinary Markdown vault edited by hand, such as an Obsidian-style folder of notes. The difference is not the storage format, since MindOS also keeps plain text. The difference is that MindOS ships an MCP server and a packaged Skill as part of the install, so an agent gets a defined path into the base instead of being pointed at a directory and trusted to behave. A plain vault gives you backlinks, graph views, and editing, and it gives an agent nothing unless you build the integration yourself. MindOS also adds run ledgers and an Agent Inspector on the agent side, which a vault has no concept of. The trade is weight: a vault is a folder, while MindOS is a desktop app, an npm CLI, a web runtime, and a set of configuration surfaces that can drift out of sync. The mindos doctor agents command exists precisely because that drift is expected.
Release cadence and what maintenance looks like
The release history shows desktop builds at v0.4.14, v0.4.15, and v0.4.16, dated late June, early July, and early September 2026. The gaps between those three are uneven, and the version numbers sit in the 0.4 range, so the desktop line is still pre-1.0. The npm package is versioned separately under @geminilight/mindos, which means a desktop update and a CLI update are not the same event and the two can be out of step. The project is MIT licensed, which permits commercial use, modification, and redistribution provided the licence and copyright notice are preserved; that is a permissive baseline, not legal advice, and anyone embedding MindOS in a shipped product should read the LICENSE file in the repository rather than this summary. Because the base is plain text, the cost of leaving is low, which is the strongest maintenance argument in the project's favour.
The parts the material does not settle
Several questions a reader would ask are simply not answered in the supplied README excerpt. There is no stated minimum agent version, no list of which agents are tested beyond the Claude Code and Cursor examples, and no description of how the MCP server authenticates or scopes access to the base. There is no benchmark, no performance figure, and no statement about how large a knowledge base the search and graph views handle before they slow down. The npm install line in the excerpt is truncated mid-string, so the exact published version tag should be read from the registry rather than copied from here. None of this makes the project unsound; it means the documentation covers the shape of the product better than its edges. The honest position is that MindOS is worth evaluating on a real notes directory, with mindos doctor agents as the first checkpoint, and that the evaluation should include a second agent writing to the same base before you trust the shared-context claim.
Editorial conclusion
Adopt MindOS if you already keep notes in Markdown, you use an MCP-capable agent such as Claude Code or Cursor, and you want one local directory that several tools read instead of pasting context into each new chat. Do not adopt it if you need a hosted service with a server-side API and no desktop component, or if your team cannot maintain a Markdown tree by hand. Before committing, install with npm install -g @geminilight/mindos@latest, run mindos doctor agents, and confirm that the MCP config it writes points at a directory you are willing to expose to every agent you connect. The doctor command is the real gate: it reports whether the agent side is actually reachable, and that answer decides whether the rest of the product is usable.
Community notes