MindOS: a shared knowledge base for you and your agents
MindOS
A local Markdown note base with an MCP server and skills: Claude Code, Cursor, Codex and Gemini CLI all read the same context
- 704 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Agents read and write the files of your knowledge base, which often hold personal data and instructions
- The HTTP mode of MCP exposes the base over the network: access rests on a Bearer token and path restrictions, so the token must stay private
Install
- Works in
Manual install
npm install -g @geminilight/mindos@latest && mindos onboardInstalls the CLI and the local web interface, and the setup wizard asks for the base path, ports, auth and model provider. A desktop app exists too.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Agents read and write the files of your knowledge base, which often hold personal data and instructions
- The HTTP mode of MCP exposes the base over the network: access rests on a Bearer token and path restrictions, so the token must stay private
This is third-party code. Review the repository files before installing.
What it does
MindOS keeps your notes as plain Markdown files on disk and serves them to agents through an MCP server with stdio and HTTP transports. Installation sets up the `mindos` CLI and a local web interface, and the `mindos mcp install` command writes MCP and the packaged MindOS skill into agent settings in one pass. You can check the result with `mindos doctor agents`, which shows whether the agent really sees the server. A profile, projects and instructions recorded once are available to every connected agent, so you do not retell them when you switch tools. Results come back to the base as notes and SOP procedures. For people there is a workspace in the browser and a desktop app: search, editing, a link graph, backlinks, file import with automatic sorting and a web clipper for saving pages. A built-in agent converses with the base, and YAML workflows run repeatable agent scenarios. The agent inspector shows tool calls on a timeline, and Git sync keeps human and agent edits reversible. The `plugins/mindos` folder holds a plugin for Claude Code and Codex with working views for people and tasks.
Who it is for. For people who use several agents at once, are tired of repeating project context to them and want to keep it in plain files under their own control.
Good fit when
- You switch between Claude Code, Cursor and Codex and want the profile and project rules kept in one place
- You need memory you can open, read and fix by hand: notes live as Markdown on your disk
- After a long dialogue with an agent you want to save the outcome as a reusable SOP procedure
- You need a log of the agent's tool calls as a filterable timeline, which the Agent Inspector provides
- You collect web pages into a knowledge base with one click through the web clipper
Not a fit when
- You need a ready cloud notes service with sync across phones: MindOS is local, and Git provides sync between devices
- A single `CLAUDE.md` file in the project is enough: a knowledge base with a graph, GUI and MCP is overkill then
- You need dependable multi-agent coordination: the author calls the ACP and A2A protocols early, and durable mailboxes and task boards are still experimental
- You need a strictly published release: the people and task views, personal pages and blocks still live in source and are not on npm
Example request
Here's my resume. Read it and organize the information into MindOS folders, then save the outcome of this conversation as an SOPMCP
- Transport
- stdio, http
- Authentication
- API key
Limitations
The author marks the new capabilities as source candidates: people and task views, personal pages, and custom HTML and CSS blocks with bounded Worker code. They are not in the published npm version yet. The views plugin needs macOS or Linux with Node.js 22.19 or newer, and the runtime must report `capabilityVersion: 1` in `mindos views doctor`.
The package installs with `npm install -g @geminilight/mindos@latest`, and a desktop app exists for macOS, Windows and Linux. The built-in agent runs on a model provider you connect, and the key is needed for it but not for the plugin: the host supplies its own agent. Access to the base is guarded by a Bearer token and path sandboxing, and `INSTRUCTION.md` is write-protected.
The plugin in the `plugins` folder installs from a local clone through Claude Code marketplace commands, not from a shared catalog. After installation the host must be reconnected.
How to disable. Remove the mindos entry from each agent's MCP settings, and uninstall the plugin with `claude plugin uninstall mindos@mindos-local`. Removing the plugin keeps the local records, the runtime and the installation for the other host. The package itself comes off with `npm uninstall -g @geminilight/mindos`, and the notes in your folder stay.
FAQ
How do I install MindOS and connect it to Claude Code?
Install the package with `npm install -g @geminilight/mindos@latest`, go through the `mindos onboard` wizard, then run `mindos mcp install -g -y`. The command sets up MCP and the skill at global scope. Check with `mindos doctor agents`.
Where are my notes stored?
In plain Markdown files in the folder you chose in the wizard. Settings are saved in `~/.mindos/config.json`. You can open the files in any editor, and Git sync makes edits reversible.
Which agents does MindOS work with?
With its own built-in agent and with external ones: Claude Code, Cursor, Gemini CLI and Codex connect through MCP over stdio or HTTP. The author keeps the full list and manual configs in `docs/en/supported-agents.md`.
Do I need an API key?
The built-in agent and AI sorting of files need a model provider key that you enter during setup. Connecting external agents over MCP needs no separate key, since they use their own models.
Is there a desktop version?
Yes, an app for macOS, Windows and Linux downloads from the project site or the GitHub releases page. It starts local processes itself and adds a tray icon and autostart. The npm install gives the same CLI and web interface.
Discussion
No questions or reviews yet.
Related
MCP serversLocal agent memory stores findings and rules in Obsidian-compatible Markdown files with search and controls for recorded changes.
A macOS menu bar app writes the text of your focused windows into markdown, and its MCP server serves that record to agents
DocsMint lets agents search, read and edit knowledge base documents through 22 MCP tools, in the cloud or on your own Docker
A Rust MCP server for a folder of Markdown notes: an agent searches and reads notes and sees backlinks, tags, tasks and version history
Minutes
minutes
A local-first MCP server for meeting memory: on-device recording and transcription into Markdown, searchable from Claude Code, Codex, Cursor and any MCP client
An agent searches, reads and writes a Roam Research graph through the desktop app's local API, with a CLI and a syntax skill
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| MindOS: a shared knowledge base for you and your agents (this card) | no | API key | 704 | |
| Second Brain OS | no | 1,476 | an Obsidian vault template with skills and commands for Claude Code | |
| Mnemon | no | 695 | shared agent memory as a local knowledge graph, without notes for people |
README in short
It opens with the idea of shared memory for a person and agents and three theses: global context sync, transparency and feedback flowing back as instructions. The getting-started section walks through installation, the wizard, filling the base and connecting an agent. Features for people, agents and infrastructure follow.