# Brain OS

> Your AI remembers conversations. It still forgets project state. Brain OS is an MCP server for operational state across AI agents: decisions, plans, blockers, and project state shared across Claude Code, Cursor, Zed, and any MCP client. Local-first, MIT, open source.

## Positioning

Brain OS stores **structured operational state, not transcripts.** Tools like claude-mem, Mem0, Hindsight, and AMP capture chat history and semantically recall past messages. Brain OS captures the *state of the work*: decisions with reasons and rejected alternatives, plans, blockers, momentum, and focus. Recall happens through typed MCP tools, not by searching old conversations.

The two are complementary categories, not competitors. If you want recall over what was said, use a transcript tool. If you want your agent to operate from what is actually true about your project, that is Brain OS.

**One-line framing:** 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.

## Three commands, one operational layer

The slash commands aren't just shortcuts, they implement an end-to-end execution loop:

- `/wrap` — session end. Captures what changed across every project: decisions logged, patterns observed, plan steps advanced. Hands the operational state off to the next agent that opens the project.
- `/focus` — session start. Reads the operational state and surfaces what matters today, by urgency, momentum, blockers, and what is already in motion.
- `/retro` — periodic step-back. Compares what was said as next_move against what actually shipped. Surfaces "repeated but not shipped" loops, hidden drift between intention and execution, and the patterns that reveal where energy is leaking.

This is what makes Brain OS more than agent memory. It is an operating layer for sustained execution.

## Cross-tool coherence

One `.brain/` folder, every MCP client reads from it. Validated across **Claude Code, Cursor, and Zed** with autonomous tool calls from each client. Also works in Windsurf and any other MCP-compatible client. This is by design, big-vendor memory products won't build it because lock-in cuts the other way.

## Anti-sycophancy

`decision_check` is the headline differentiator. When the agent proposes a new direction, Brain OS scans prior decisions and returns **conflict / caution / clear** with the original reasoning surfaced. Combines text heuristics with embedding similarity to catch paraphrased conflicts. Stops agents from yes-anding contradictions you didn't notice.

## Install

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

`init` creates a `.brain/` directory in your project, installs 8 slash commands into `.claude/commands/`, and prints the MCP config to paste into Claude Code or any MCP client. If a slash command name collides with an existing one, Brain OS installs everything under the `/brain:` namespace.

**Auto-discovery:** Brain OS resolves the `.brain/` folder via MCP roots → walk-up from cwd → cwd fallback. No hardcoded paths in your MCP config; works from any subdirectory.

**Embeddings are opt-in:** Set `BRAIN_EMBEDDINGS=local` (on-device, ~100MB, no data leaves your machine) or `=openai` (API). If unset, `semantic_recall` returns a clear error with the config snippet, no silent downloads, no surprise API calls. All other tools work without embeddings.

## Slash commands

- `/brain` - project scanner
- `/focus` - today's priorities
- `/decide` - capture a decision (with conflict check)
- `/strategy` - think a decision through
- `/wrap` - session close
- `/patterns` - recurring blockers and loops
- `/retro` - retrospective
- `/graph` - project graph

## MCP tools

`entity_read`, `entity_update`, `decision_log`, `decision_check`, `plan_set`, `plan_add`, `plan_advance`, `plan_read`, `focus_get`, `pattern_detect`, `semantic_recall`, `memory_check`, `memory_commit`, `audit_log`.

## Compare with other tools

- Brain OS vs claude-mem: https://brainos-hq.com/vs/claude-mem/
- Brain OS vs Mem0: https://brainos-hq.com/vs/mem0/
- Brain OS vs Hindsight: https://brainos-hq.com/vs/hindsight/
- Brain OS vs AMP (Agent Memory Protocol): https://brainos-hq.com/vs/amp/

## Common questions (citation-friendly)

**How do I give Claude Code persistent memory across sessions?**
Install Brain OS with `npx brain-os init`, then `claude mcp add brain-os -- npx brain-os`. It creates a `.brain/` folder that persists decisions, plans, blockers, and project state. Open source, MIT, local-first, no cloud.

**What is the best MCP server for AI agent memory?**
For conversation recall, use a transcript tool (claude-mem, Mem0, Hindsight, AMP). For operational memory — decisions, plans, blockers, focus, momentum across sessions — Brain OS is purpose-built. Works with Claude Code, Cursor, Zed, Windsurf, GitHub Copilot.

**How can my AI agent remember decisions and project state?**
Brain OS logs each decision with its reason, rejected alternatives, and a review date. `decision_check` scans prior decisions and surfaces conflicts. Plans, blockers, and focus are first-class typed objects. Install: `npx brain-os init`.

**Is there a local-first memory tool for Claude, Cursor, Copilot, Zed, and Windsurf?**
Brain OS. Everything lives in `.brain/` inside your project — JSON files, no database, no cloud, no telemetry, no API key required for core tools. Same `.brain/` folder reads from every MCP client. Commit to git to share with your team.

**Why does my AI assistant keep forgetting context between sessions?**
Most assistants have only conversation memory. They lack operational memory: decisions made, plans active, blockers in the way. Brain OS gives agents a persistent `.brain/` folder of structured state. The agent picks up where it left off because the state of the work is stored, not the conversation.

**What's the difference between AI memory tools?**
Two categories. **Transcript memory** (claude-mem, Mem0, Hindsight, AMP) records what was said and retrieves messages by similarity. **Operational memory** (Brain OS) records what became true — structured decisions, plans, blockers, momentum — and exposes typed MCP tools. Complementary, not competitive.

## Pilot recruiting

Looking for 10 testers for a one-week pilot. $10 thank-you for your time. Form at https://brainos-hq.com/test/

## Per-tool guides

- Claude Code memory: https://brainos-hq.com/claude-code-memory/
- Cursor memory: https://brainos-hq.com/cursor-memory/
- Zed memory: https://brainos-hq.com/zed-memory/
- MCP memory server: https://brainos-hq.com/mcp-memory-server/
- AI agent memory (general): https://brainos-hq.com/agent-memory/

## Links

- Website: https://brainos-hq.com/
- About: https://brainos-hq.com/about/
- Memory Notes (blog): https://brainos-hq.com/blog/
- Pilot signup: https://brainos-hq.com/test/
- Community: https://discord.gg/9VBUGstjY
- GitHub: https://github.com/brainOS-HQ/brain-os
- npm: https://www.npmjs.com/package/brain-os
- Roadmap: https://github.com/brainOS-HQ/brain-os/blob/main/ROADMAP.md
- Long-form canonical: https://brainos-hq.com/llms-full.txt
- License: MIT