About Brain OS

MCP server for persistent operational state across AI agents. Brain OS exists because the dominant pattern for AI memory captures conversations, not the work itself.

The problem

Every Claude Code session, every Cursor window, every new conversation: the same loss. You explain the same project again. You re-make the same decisions. You rediscover the same blockers. The agent has tools and intelligence, but no understanding of the work it's doing.

There are two ways to fix this. Most tools picked one. Brain OS picked the other.

The dominant pattern

Most "AI memory" tools (claude-mem, Mem0, Hindsight, AMP) capture the conversation. They auto-record sessions, embed them, and retrieve past messages by similarity when the agent asks. They do this well, and for one job it's the right answer: continuity of dialogue. Remembering what was said.

What Brain OS captures instead

Brain OS doesn't touch transcripts. It captures the state of the work. Not what was said, what is true.

The decisions you've made (and rejected), with reasons
The plans you're executing, with phases
The blockers in your way
The focus you've chosen for today
The momentum on each entity
The patterns recurring across sessions

Your agent reads this through typed MCP tools (focus_get, decision_log, plan_read, pattern_detect, semantic_recall), not by searching old messages. It operates from your project's current truth, not its history.

The opinion

Both categories are useful. Many projects benefit from running one of each. The distinction matters because the right tool depends on the question your agent is asked to answer:

If the question is "what was said?"

Use a transcript tool.

If the question is "what is true about the work?"

That's Brain OS.

How it works in practice

Three slash commands form the operational loop:

/wrap — session end. Capture what changed: decisions, blockers, plan steps. Hand off the operational state to whatever agent opens the project next.
/focus — session start. Agent reads the state and surfaces what matters today, by urgency, momentum, blockers, what's already in motion.
/retro — periodic step-back. Compare stated next_move against what actually shipped. Catch the work that keeps reappearing but never moves.

Most agent-memory tools help an AI remember. Brain OS helps an AI keep work coherent over time. Brain OS doesn't give your agent a diary — it gives it a shift handoff.

How it's built

Brain OS is open source under the MIT license. It runs locally as an MCP server. There is no cloud, no database, no telemetry, no API key required by default. The data lives in a .brain/ folder inside your project, yours to commit, gitignore, or sync however you like.

A few things Brain OS does deliberately:

Auto-discovers your project. Whether you launch your agent from the project root or a deep subdirectory, Brain OS finds the right .brain/ folder via MCP roots and walk-up. No hardcoded paths in your MCP config.
Embeddings are opt-in. Semantic recall asks for an explicit BRAIN_EMBEDDINGS=local|openai. No silent model downloads, no surprise API calls. The other tools work without it.
Reads fresh on every call. No in-memory cache. That makes filesystem sync (git, Dropbox, NFS) work as team-sharing without product changes. Log a decision from Claude Code on Monday, open Cursor on another machine Tuesday, same brain. Native encrypted team sync with proper merge semantics is on the roadmap.
Cross-tool by design. One .brain/ folder, every MCP client reads from it: Claude Code, Cursor, Zed, Windsurf, GitHub Copilot, anything that speaks the protocol. Empirically validated across four engines with autonomous tool calls.

It installs with one command:

Read the full pitch →

Maintained by

brainOS-HQ on GitHub. Source at github.com/brainOS-HQ/brain-os. Package at npmjs.com/package/brain-os. Issues and contributions welcome.