Brain OS

Local-first MCP memory server for operational project state: decisions, blockers, plans, patterns, and next moves.

Your AI remembers conversations. It still forgets project state.

Brain OS gives agents operational state: decisions, plans, blockers, and priorities that survive across sessions.

AI agents are powerful inside a session, but long-running work has more state than any one chat: what you decided, what's blocked, what's active, and what should not be reopened. Brain OS gives agents operational state, not conversation logs:

- Entities— track projects, deals, initiatives with status, momentum, blockers, and next moves
- Decisions— log what was decided, why, what alternatives were rejected, and when to revisit
- Patterns— detect recurring blockers, stale work, avoidance signals, and theme convergence
- Focus— prioritize what to work on based on urgency, momentum, leverage, and staleness
- Semantic recall— search memory by meaning, not just ID

Brain OS is anMCP serverthat works with any MCP-compatible client: Claude Code, Cursor, Zed, GitHub Copilot, OpenAI Codex, Windsurf, or any agent that speaks the protocol.

> decision_check({ proposal: "switch to Postgres for the new service" }) { "verdict": "conflict", "conflicting_decision": { "id": "dec_2026_03_14_db_choice", "decision": "Use SQLite for all local-first projects", "reason": "Lower ops burden, no infra to run, fits single-user scope", "rejected_alternatives": ["Postgres", "DuckDB"], "logged_at": "2026-03-14" }, "guidance": "Re-litigating a settled choice. Surface the prior reasoning to the user before proceeding." }

That's the wedge: structured state with enforcement, so agents stop re-opening questions you already answered.
- Creates a.brain/directorywith your entity, decision, and pattern stores.
- Installs slash commandsinto.claude/commands/so you can run/brain,/brain:focus,/brain:decide, etc. directly in Claude Code. Bare aliases (/focus,/decide, etc.) install alongside for brevity.
- Drops agent-instructions pointer filesso any MCP-compatible client behaves consistently:AGENTS.md(canonical, cross-tool) plus thin pointer files for Claude Code (CLAUDE.md), GitHub Copilot (.github/copilot-instructions.md), Cursor (.cursor/rules/brain-os.mdc), Zed (.zed/rules.md), and Windsurf (.windsurfrules).

- npx brain-os init --minimal— install onlyAGENTS.md+CLAUDE.md, skip the other client pointers (clean-repo mode)
- npx brain-os init --no-commands— skip slash commands (MCP server only)
- npx brain-os init --no-agent-instructions— skip all agent-instructions pointer files

claude mcp add brain-os -- npx brain-os serve

{ "brain-os": { "command": "npx", "args": ["-y", "brain-os", "serve"] } }

Thesemantic_recalltool needs an embeddings provider. Everything else (entity_update,decision_log,plan_, etc.) works without one.

# Private, on-device embeddings npm install brain-os @huggingface/transformers # Or OpenAI embeddings npm install brain-os openai

{ "brain-os": { "command": "npx", "args": ["-y", "brain-os", "serve"], "env": { "BRAIN_EMBEDDINGS": "local" } } }

brain-os initinstalls slash commands into.claude/commands/so the agent has a clear vocabulary for working with operational state. Each command installs in two forms:/brain:(canonical, documented form) and a bare alias (/decide,/focus, etc.) for power-user brevity./brainis the namespace root and installs once.

- BRAIN_OS_PROTOCOL.mdat.claude/brain-os/PROTOCOL.md(project) and~/.claude/brain-os/PROTOCOL.md(user). The protocol governs tool routing: when an agent runs a Brain OS slash command, it reads the protocol first, then callsentity_read/plan_read/focus_get/etc. as primary. Pulse files become fallback only.
- brain-os-modesubagentat.claude/agents/brain-os-mode.md. When the main agent delegates Brain OS work to a subagent (e.g. Claude Code's Task tool), it picks up under the same protocol — no risk of subagents falling back to generic file search.
- Optional routing-guard hookattemplates/hooks/brain-os-routing-guard.py. Opt-in PreToolUse hook that warns if pulse files are read while a.brain/workspace exists. Install instructions are printed bybrain-os init.

Re-runninginitis safe and repair-aware: existing Brain OS commands are preserved, and any missing form is installed. If a command path is taken by another tool, that path is skipped and reported — your file is never overwritten. You can install Brain OS into a project with existing/decideor/focuscommands and the namespaced/brain:forms will still land.

.brain/ entities/ — one file per tracked entity decisions/ — decision log patterns/ — detected patterns config.json — workspace settings

- Discord:discord.gg/9VBUGstjY— questions, feedback, what broke for you, what you're shipping with Brain OS
- Site:brainos-hq.com
- Issues:github.com/brainOS-HQ/brain-os/issues

AI Reasoning Cache & Consensus Layer with 50+ reasoning objects across 14 domains. Cache hit/miss with token savings, failure risk check before execution, cross-model verification, and citation tracking. 11 MCP tools via Streamable HTTP.