MindOS: a local-first Markdown knowledge base that agents read through MCP

The context re-transport problem MindOS is built around

Every new chat starts empty. You paste the same project background, the same preferences, the same decisions you already made last week. The README names this directly: switch tools or start a new chat and you are re-transporting context. MindOS treats that as a storage problem rather than a prompting problem. The knowledge base is the durable artifact; the agent is a temporary reader of it.

The intended user is someone who already runs MCP-capable agents and has accumulated notes worth reusing. The README's own examples are personal and project memory: feed it a resume and have the agent organize it, distill a conversation into a reusable SOP, then ask the agent to execute that SOP later. That is a workflow for one person or a small team, not a shared corporate wiki.

The package description in package.json states the same positioning in one line: a local-first knowledge base that syncs your mind to all AI Agents via MCP. The topics listed on the repository (agent, context, knowledge-base, mcp, memory, skill) match that scope.

Local plain text plus an MCP and Skills bridge

The architecture has three visible layers. At the bottom is a local Markdown knowledge base that the README describes as local plain text, kept that way for privacy, ownership and speed. Above it sits a bridge: a built-in MCP server plus packaged Skills, which is the shared path agents use to reach the base. On top are the surfaces you actually look at.

The repository layout confirms the split. There is a packages/ directory alongside a skills/ directory and a templates/ directory, with pnpm-workspace.yaml and turbo.json at the root, so MindOS is a monorepo with the MCP and Skill assets shipped as their own trees rather than generated at install time. The npm package is described as including the CLI and a prebuilt local Web runtime, which means the browser interface is served locally rather than requiring a separate build step on your machine.

The control story is the part worth judging. The README claims review surfaces for agent runs, file changes and important tool activity, and lists Agent Inspector, run ledgers, backlinks and graph views among the workflow and audit surfaces. Those are the mechanisms that make the shared context inspectable. What the README does not document is a rollback path for agent-initiated file changes, so treat the audit surfaces as review tooling rather than as undo.

Installing MindOS and getting one agent to read your notes

There are two install routes. The desktop app is the no-terminal option: the README points to the official website or the GitHub Releases page, and says you double-click to install. The npm route is the one you want if you intend to script anything, and the README gives it as a global install of the scoped package.

npm install -g @geminilight/mindos@latest

After that, the README describes a single command that installs or repairs both the MCP configuration and the packaged MindOS Skill, followed by a doctor command that verifies real agent readiness. The exact subcommand names beyond `mindos doctor agents` are not spelled out in the README, so check the CLI help rather than guessing flags.

mindos doctor agents

If you would rather have an agent do the setup, the README provides a prompt you paste into Claude Code, Cursor or another MCP-capable agent, asking it to install MindOS with MCP and Skills using the English template. Once the bridge is in place, the README's first suggested use is to hand the agent a document and have it organized into the base. Expect the agent to write Markdown files into your knowledge base directory; that directory is the thing to inspect afterward.

Where MindOS is the wrong tool

The strongest limitation is also the design premise. MindOS is local-first and its knowledge base is plain text on your disk. That is good for ownership and speed, and bad for any scenario where several people need concurrent access with permissions. The README does not describe multi-user accounts, roles or a hosted sync service. If your requirement is a shared team wiki with access control, this is not it.

The second constraint is the agent side. The value depends on your agent being MCP-capable. The README names Claude Code and Cursor as examples and lists MCP as a topic, but an agent that cannot speak MCP gets nothing from the bridge, and the local web workspace becomes just another Markdown editor.

The third is release cadence. The desktop release history shows desktop-v0.4.14 on 2026-06-26, desktop-v0.4.15 on 2026-07-01, then desktop-v0.4.16 on 2026-09-09, while the root package.json carries version 1.1.67. Those are different version lines for different artifacts, so pinning matters: a CLI installed today and a desktop build from July are not the same code. The last push to the repository was on 2026-09-10.

MindOS compared with a plain Obsidian vault plus an MCP plugin

The obvious alternative is an existing Markdown vault, Obsidian being the common one, with a community MCP plugin bolted on. The difference is where the integration lives. With a vault and a plugin, the MCP server is third-party code you configure yourself and update on its own schedule; the notes are plain text either way.

MindOS puts the MCP server and the Skill inside the product and ships an installer that writes both, which is why the README can offer a single command that installs or repairs MCP config and the Skill together, and why a doctor command can report agent readiness at all. The trade-off is coupling: you adopt MindOS's packaging, its release line and its CLI to get that convenience.

There is a hint in the repository that the two worlds are not exclusive. The package.json scripts include an `obsidian:matrix` target that runs a script under packages/web to generate an Obsidian real-plugin matrix, which suggests MindOS tracks Obsidian plugin compatibility rather than treating it purely as a rival. The README does not explain that script, so treat it as an open question rather than a supported migration path.

Maintenance cost, the MIT licence, and what the docs leave open

The licence is MIT, which is permissive and places few obligations on how you use or redistribute the code. That is a statement about the licence text, not legal advice about your situation; if you plan to redistribute a modified build, read LICENSE and the notices in the packages you ship.

Upgrade cost is dominated by the split version lines. The desktop app and the npm CLI move on separate schedules, so an upgrade plan needs to name which artifact you are updating. The repository also ships TROUBLESHOOTING.md at the top level, which is where the project itself expects you to look when the install or the bridge misbehaves.

Several things the README does not document: no rollback mechanism for agent file changes, no published compatibility matrix for which agent versions the MCP bridge has been verified against beyond the doctor command, and no stated migration path from an existing vault. The repository is not archived and the last push was on 2026-09-10, so the code is moving, but a moving target is not the same as a documented one.

Editorial conclusion

Adopt MindOS if you already run MCP-capable agents such as Claude Code or Cursor and want one local Markdown base they all read from, with the npm package as the fastest path because `mindos doctor agents` tells you whether the bridge actually works. Skip it if you need a hosted multi-user wiki, or if your notes live in a proprietary database that cannot be exported to plain text. Before committing, verify three things: that the CLI version you install matches the desktop release line you intend to use, that your agent's MCP configuration points at the server the installer wrote, and that your knowledge base directory is one you are willing to keep as plain files on disk.

Frequently asked questions

Official sources

1. GeminiLight/MindOS on GitHub
2. License: MIT
3. Project website
4. README
5. Releases