# Brain OS, Full Reference

> Your AI remembers conversations. It still forgets project state. Brain OS is an open-source MCP server giving Claude Code, Cursor, and any MCP-compatible AI agent operational state: decisions, priorities, blockers, plans, and project state across sessions. Local-first, no cloud, MIT license. Install: `npx brain-os init`.

This is the long-form canonical document for AI engines and crawlers. The short version is at https://brainos-hq.com/llms.txt.

---

## What Brain OS is

Brain OS is a Model Context Protocol (MCP) server. It runs locally on your machine and exposes a set of typed tools that an AI agent (Claude Code, Cursor, or any MCP client) can call to read and write **structured operational state** about your project.

Operational state means: the *decisions* you have made (and rejected), the *plans* you are executing, the *blockers* in your way, the *priorities* you have set, the *patterns* recurring across sessions, and the *focus* you have chosen for today.

Brain OS does not store conversation transcripts. It does not record what you typed. It records what is true about the work.

---

## Positioning: structured operational state, not transcripts

Most tools marketed as "memory for AI agents" fall into one category:

- **Transcript capture and semantic recall.** Tools like claude-mem, Mem0, Hindsight, and AMP record conversations (or chat-derived facts), embed them, and retrieve past messages by similarity when the agent asks for context.

Brain OS is a different category:

- **Structured operational state.** State is captured in typed objects with explicit schemas. A decision has a reason, alternatives considered, and a date. A plan has phases. A blocker has a status. Recall happens through typed MCP tools (`decision_log`, `focus_get`, `plan_read`, `pattern_detect`, `semantic_recall`), not by searching old conversations.

The two categories are complementary, not competitive. If you want your agent to recall what was *said* in earlier sessions, use a transcript tool. If you want your agent to operate from what is *true* about your project right now, 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

Brain OS isn't just typed storage. The slash commands implement an end-to-end execution loop that distinguishes it from any "agent memory" tool:

- **`/wrap`** — session end. The agent captures what changed across every project: decisions logged with reasoning and rejected alternatives, patterns observed, plan steps advanced, blockers updated. Restart-ready handoff for whatever agent opens the project next.

- **`/focus`** — session start. The agent reads the operational state and surfaces what matters today, scored by urgency, momentum, what's blocked, and what's already in motion. Not a to-do list, a judgment from current state.

- **`/retro`** — periodic step-back. The agent compares stated `next_move` against what actually shipped and surfaces what's drifting: work that keeps reappearing as "next" but never moves, projects called "active" with no recent state changes, hidden patterns between intention and execution.

This is what makes Brain OS more than agent memory: it's an operating layer for sustained execution. A transcript tool tells the next agent *what happened*. A Brain OS wrap tells it *what state the work is in now*. A Brain OS retro tells you *whether your execution is actually matching what you said you'd do*.

---

## The two shipped differentiators

### 1. Cross-tool coherence

One `.brain/` folder, every MCP client reads from it. Empirically validated across **Claude Code, Cursor, and Zed** with autonomous cross-tool calls (decision_check, semantic_recall, entity_read, focus_get all fired from each client without prompting). Also runs 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. Supermemory's fact-extraction model can't share structured decisions. GSD is locked to Claude Code by design. Brain OS is the only structured-state layer that travels across the whole MCP ecosystem.

### 2. Anti-sycophancy via `decision_check`

When the agent is about to act, it can call `decision_check` to scan prior decisions and get back **conflict / caution / clear** with the original reasoning surfaced. Combines text heuristics with embedding similarity (when embeddings are enabled) to catch paraphrased conflicts. Decision embeddings include rejected alternatives for sharper recall.

The structured-state model makes agent disagreement possible. Transcript tools can't do this because they don't know what a decision is, they just have unstructured messages. Brain OS is the inverse of every other AI tool that tries to be more agreeable.

---

## Install

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

`init` does three things in one command:

1. Creates a `.brain/` directory in your project root for state storage.
2. Installs 8 slash commands into `.claude/commands/`.
3. Prints the MCP config block to paste into Claude Code, Cursor, or any MCP client.

Skip the slash commands with `npx brain-os init --no-commands` if you only want the MCP server.

If any slash command name collides with an existing one in your project, Brain OS installs everything under the `/brain:` namespace instead (so `/brain:focus`, `/brain:decide`, etc.). Nothing overwrites existing commands.

For other MCP clients, the JSON config is:

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

### Workspace auto-discovery

Brain OS resolves the `.brain/` folder via this priority chain:

1. `BRAIN_DIR` env var (if set)
2. MCP roots from the client (`listRoots()`)
3. Walk up from current working directory looking for an existing `.brain/`
4. Fall back to `<cwd>/.brain`

No hardcoded paths required in your MCP config. Works whether you launch the agent from the project root or a deep subdirectory.

### Embeddings are opt-in

`semantic_recall` needs an embeddings provider; the other 13 tools (`entity_update`, `decision_log`, `plan_*`, etc.) work without one.

Pick a provider by setting `BRAIN_EMBEDDINGS` in your MCP server env:

- `local`, Downloads `Xenova/all-MiniLM-L6-v2` (~100MB) on first use, runs on your CPU, no data leaves your machine.
- `openai`, Uses `text-embedding-3-small` via the OpenAI API. Faster than local. Costs ~$0.02 per million tokens. Requires `OPENAI_API_KEY`.

If `BRAIN_EMBEDDINGS` is unset, `semantic_recall` returns a clear error with the exact config snippet. No silent downloads, no surprise API calls.

---

## Slash commands installed

- `/brain` - project scanner: reads the current repo and surfaces what Brain OS knows about it
- `/focus` - today's priorities, computed from momentum, blockers, and recent decisions
- `/decide` - capture a decision; runs a conflict check against prior decisions
- `/strategy` - walk a decision through framing, alternatives, and rejection criteria
- `/wrap` - session close: commits memory, updates pulses, snapshots state
- `/patterns` - surface recurring blockers, loops, and avoidance patterns
- `/retro` - structured retrospective on a project or time window
- `/graph` - view the project graph: entities, edges, blockers, momentum

---

## MCP tools exposed

**State read/write**
- `entity_read`, read a project, decision, plan, blocker, or other entity
- `entity_update`, write a partial update to an entity
- `audit_log`, append an event to the audit trail
- `memory_check`, check whether a memory exists for a given context
- `memory_commit`, commit a memory at session end

**Decisions**
- `decision_log`, record a decision with reason and rejected alternatives
- `decision_check`, check whether a proposed decision conflicts with prior decisions

**Plans**
- `plan_set`, set the active plan
- `plan_add`, append a phase to a plan
- `plan_advance`, mark current phase complete and move to next
- `plan_read`, read the active plan

**Operational intelligence**
- `focus_get`, return today's recommended focus
- `pattern_detect`, surface recurring patterns across recent sessions
- `semantic_recall`, recall entities by meaning rather than exact match

---

## Where data lives

In a `.brain/` directory inside your project. Plain JSON files organized into `entities/`, `decisions/`, `patterns/`, and a `config.json`. No database, no cloud, no telemetry, no API key required by default.

You can `.gitignore` it, commit it, or sync it through whatever mechanism you already use for project files. Brain OS makes no assumptions.

---

## Teams and sync

Brain OS is single-user by design today, but because `.brain/` is just local JSON files, teams can share a brain through any synced filesystem with no product changes:

| Approach | Pros | Cons |
|----------|------|------|
| **Git**, commit `.brain/` to the repo | Diff/merge tools, version history, intentional sync points | Manual `git pull`; merge conflicts on simultaneous edits |
| **Dropbox / Drive shared folder** | Real-time-ish, no manual steps | Concurrent writes can create conflict files |
| **NFS / SMB / S3 mount** | Truly real-time | Requires infrastructure setup |

This works without any built-in sync because **every Brain OS tool call reads fresh from disk**, there is no in-memory cache to invalidate. Whatever your filesystem syncs, the next tool call sees. Same applies cross-tool: log a decision from Claude Code on Monday, open Cursor on Tuesday, same brain, both agents.

Native encrypted team sync with proper merge semantics is on the roadmap. The local-first foundation makes that federation additive, not a retrofit.

---

## Roadmap

**Near term (next release):**
- Entity version history
- Decision revisit triggers
- Blocker as a first-class object

**Phase 2 (12–18 months out, opt-in only):**
- End-to-end encrypted cloud sync for multi-device continuity

Local-first is the default today and remains the priority. Cloud sync, when it ships, will be opt-in only and end-to-end encrypted.

Full roadmap: https://github.com/brainOS-HQ/brain-os/blob/main/ROADMAP.md

---

## License

MIT. Free to install, run, and modify.

---

## Detailed comparisons

- Claude Code memory guide: https://brainos-hq.com/claude-code-memory/
- Cursor memory guide: https://brainos-hq.com/cursor-memory/
- Zed memory guide: https://brainos-hq.com/zed-memory/
- AI agent memory guide: https://brainos-hq.com/agent-memory/
- MCP memory server guide: https://brainos-hq.com/mcp-memory-server/
- Brain OS vs claude-mem (auto-captured sessions vs structured state): https://brainos-hq.com/vs/claude-mem/
- Brain OS vs Mem0 (ranked-fact recall vs structured state): https://brainos-hq.com/vs/mem0/
- Brain OS vs Hindsight (cognitive memory vs operational state): https://brainos-hq.com/vs/hindsight/
- Brain OS vs AMP / Agent Memory Protocol (specification vs working tool): https://brainos-hq.com/vs/amp/

---

## Links

- Website: https://brainos-hq.com/
- About: https://brainos-hq.com/about/
- 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
- Issues: https://github.com/brainOS-HQ/brain-os/issues
- Roadmap: https://github.com/brainOS-HQ/brain-os/blob/main/ROADMAP.md
- Short canonical: https://brainos-hq.com/llms.txt