# brain

**Your local second brain for Claude, ChatGPT and any AI agent.**

brain is an [MCP](https://modelcontextprotocol.io) server that runs on your Mac and gives your AI agents a shared memory: your notes, your projects, what they know about you and the web pages you saved, with semantic search. Connect it once to Claude, ChatGPT, Cursor or whatever agent you use, and they all read and write the same knowledge base. Everything stays on your computer.

It ships with a web dashboard so you never have to touch the terminal: turn services on and off, fill in your profile, import the memory other chatbots have about you, connect agents, explore the connection graph and search what you saved.

```bash
curl -fsSL https://raw.githubusercontent.com/Lautaro005/brain/main/install.sh | bash
```

Then type `brain` and the dashboard opens.

**Website:** https://lautaro005.github.io/brain/

---

## Contents

- [What you can do](#what-you-can-do)
- [Installation](#installation)
- [Getting started](#getting-started)
- [The dashboard](#the-dashboard)
- [Connecting agents](#connecting-agents)
- [How it works](#how-it-works)
- [MCP tools](#mcp-tools)
- [The `brain` command](#the-brain-command)
- [Data, privacy and security](#data-privacy-and-security)
- [Troubleshooting](#troubleshooting)
- [Uninstalling](#uninstalling)
- [Development](#development)
- [License](#license)

---

## What you can do

- **Let your agents know you.** Write a profile (who you are, what you do, how you like to work) and import the memory ChatGPT, Claude or Gemini already have about you. Every connected agent reads it when it starts and saves anything new it learns with `add_memory`.
- **One knowledge base, shared by every agent.** Markdown notes organized into projects and skills. What Claude writes today, ChatGPT can read tomorrow.
- **Save the web.** Give brain a URL and it downloads the page, extracts the text (including sites built with JavaScript), indexes it and makes it available to semantic search: you search by meaning, not exact words.
- **See how everything connects.** An interactive graph shows your profile, memories, projects, skills, sources and tags, and how they relate.
- **Undo anything.** Every write goes into a version history. If an agent deletes or overwrites something, you get it back.
- **Private by design.** Embeddings are computed on your machine with [Ollama](https://ollama.com), and nothing leaves your computer.

## Installation

**Requirements:** macOS (Apple Silicon or Intel) and git (`xcode-select --install` if you don't have it). The installer takes care of the rest.

```bash
curl -fsSL https://raw.githubusercontent.com/Lautaro005/brain/main/install.sh | bash
```

The installer:

1. Installs [uv](https://docs.astral.sh/uv/) if you don't have it (it manages Python and the dependencies without touching the system Python).
2. Downloads brain into `~/.brain`.
3. Installs the dependencies and the headless Chromium used to scrape JavaScript sites.
4. Installs [Ollama](https://ollama.com) with Homebrew if needed, and pulls the `nomic-embed-text` embedding model (~270 MB). Without Homebrew, it tells you where to download Ollama.
5. Creates the `brain` command in `~/.local/bin` and adds it to your `PATH` if it wasn't there.

Running it again updates the install. To install somewhere else, set `BRAIN_HOME=~/some/folder` before `bash`.

<details>
<summary>Manual installation</summary>

```bash
git clone https://github.com/Lautaro005/brain ~/.brain && cd ~/.brain
uv sync
uv run playwright install chromium
ollama pull nomic-embed-text
./brain.sh
```
</details>

## Getting started

1. **Open the dashboard:** `brain`. It opens at `http://127.0.0.1:8765` and starts Ollama and the Chroma server if they aren't running. Keep it open while you use your agents; Ctrl+C closes it.
2. **Connect your agents:** **Connect agent** tab → *Connect* on Claude Desktop, ChatGPT or whichever you use.
3. **Tell it who you are:** **Profile** tab → fill in "About you" and import your memory from another chatbot.
4. **Try it:** in Claude, ask *"what do you know about me according to brain?"* or *"save this URL to brain: …"*.

## The dashboard

| Tab | What it's for |
|---|---|
| **Dashboard** | Switches to turn **Chroma**, **Ollama** and the **MCP Inspector** (a UI to try the tools by hand) on and off. Vault metrics, activity charts for the last 30 days, sources by domain, operations, system health and recent changes. |
| **Profile** | Your details (name, headline, about me) and your memory. The importer takes 3 steps: pick the chatbot, copy a prompt that asks it for all its memory in a fixed format, and paste the answer (or upload a `.txt`, `.md` or `.json`). You get a preview before importing and can drop anything you don't want. |
| **Connect agent** | Connect and disconnect brain from Claude Desktop, ChatGPT, Claude Code, Codex, Cursor, VS Code, Windsurf and Gemini CLI in one click, plus manual setup for anything else. **My connections** shows which agents are connected and whether they point to this install. |
| **Graph** | Interactive map of the vault: profile, memory, projects, skills, sources, folders and tags. Click a node to see its content and connections. Controls to zoom in, zoom out and **re-center** (also the `0` key or double-clicking the background). |
| **Knowledge** | Save a URL (optionally forcing JavaScript rendering), semantic search with a relevance score, and the list of saved sources. |
| **Logs** | Live output of every service the dashboard manages. |

The bottom of the sidebar has the theme (system, light or dark) and the language (**English / Español**).

When you close the dashboard, it only stops what it started. If Ollama was already running (for example the menu-bar app), it shows up as **External** and is left alone.

## Connecting agents

Each agent keeps its list of MCP servers in its own file. When you click *Connect*, brain adds its entry without touching the rest of the file, and saves a backup first (`<file>.bak-brain`).

| Agent | Where it's configured | Notes |
|---|---|---|
| **Claude Desktop** (chat and Cowork) | `~/Library/Application Support/Claude/claude_desktop_config.json` | Claude rewrites this file when it quits, so it's edited with the app closed. If it's open, the dashboard offers to quit it, connect and reopen it. |
| **ChatGPT** (desktop app) | `~/.codex/config.toml` | Works in **Codex** and **ChatGPT Work** modes; regular ChatGPT chat doesn't use local servers. Afterwards: *Settings → MCP servers → Restart*. Shares its config with Codex CLI. |
| **Claude Code** | `~/.claude.json` (via `claude mcp add -s user`) | Available in all your projects. |
| **Codex CLI** | `~/.codex/config.toml` | Same config as ChatGPT. |
| **Cursor** | `~/.cursor/mcp.json` | |
| **VS Code** (Copilot, agent mode) | `~/Library/Application Support/Code/User/mcp.json` | |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | |
| **Gemini CLI** | `~/.gemini/settings.json` | |
| **Anything else** | | The dashboard gives you ready-to-copy config as JSON, TOML, a command, or field by field. |

All of them launch the same server (`uv run --directory ~/.brain python server.py`) with absolute paths, so they work from any folder.

### Apps with an "Add MCP server" form

Many apps have a dialog with two options, **Run a command** and **Connect to a URL**. Choose **Run a command**: brain is a local (stdio) server and doesn't expose a URL, so "Connect to a URL" won't work. Pointing it at the dashboard's address returns `403`, because the dashboard only accepts requests from its own page.

| Field | Value |
|---|---|
| Server name | `brain` |
| Executable command | the absolute path to `uv`, e.g. `/Users/you/.local/bin/uv` (`which uv` prints it) |
| Arguments (one per line) | `run`<br>`--directory`<br>`/Users/you/.brain`<br>`python`<br>`server.py` |
| Environment | empty |

The **Connect agent** tab shows these values already filled in for your machine, each with a copy button.

## How it works

```mermaid
flowchart LR
    subgraph Agents
        A1[Claude Desktop]
        A2[ChatGPT]
        A3[Claude Code / Cursor / …]
    end
    subgraph brain["brain (your Mac)"]
        S1[server.py<br/>one process per agent]
        V[(vault/<br/>Markdown)]
        H[(data/history.sqlite3<br/>versions)]
        C[(Chroma<br/>shared HTTP server)]
        O[Ollama<br/>nomic-embed-text]
        P[Playwright<br/>headless Chromium]
        D[Dashboard<br/>127.0.0.1:8765]
    end
    A1 & A2 & A3 -- MCP over stdio --> S1
    S1 --> V
    S1 --> H
    S1 -- embeddings --> O
    S1 -- chunks --> C
    S1 -- JS sites --> P
    D --> V & H & C
    D -. starts/stops .-> C & O
```

**Pieces:**

- **MCP server (`server.py`).** Each agent launches its own process and talks to it over stdio (MCP's standard for local servers). It exposes the [tools](#mcp-tools) and tells the model to read `BRAIN.md`, your profile and your memory first.
- **Vault (`~/.brain/vault/`).** Markdown files with YAML frontmatter:
  - `BRAIN.md`: a short index the agent reads first.
  - `profile.md`: your profile.
  - `memory/`: one file per category ("Work", "Preferences"…) with one fact per bullet.
  - `projects/` and `skills/`: your notes and reusable instructions.
  - `knowledge/sources/`: the full text of every saved URL.
- **History (`data/history.sqlite3`).** Every write stores the file's previous and new content. A cross-process file lock makes writes atomic, so Claude, ChatGPT and the dashboard can write at the same time without clobbering each other.
- **Chroma.** The vector database behind semantic search. It runs as a single HTTP server on `127.0.0.1:8055`, so every process shares it without fighting over the disk.
- **Ollama.** Computes embeddings on your machine with `nomic-embed-text`, using the prefixes the model expects (`search_document:` when indexing, `search_query:` when searching).

**What happens when you save a URL (`save_url`):**

1. [trafilatura](https://trafilatura.readthedocs.io) downloads the page and extracts clean text.
2. If it gets fewer than 30 words (typical of JavaScript-built sites) or the download fails, it renders the page in headless Chromium with Playwright and extracts again.
3. It splits the text into ~500-word chunks with a 50-word overlap.
4. It embeds each chunk with Ollama and stores it in Chroma, with metadata pointing back to the source `.md`.
5. It writes `knowledge/sources/<slug>.md` with the full text and its chunk ids. Saving the same URL again updates it instead of duplicating it.

**How memory import works:** the dashboard's prompt asks the chatbot for its memory grouped as `## Category` / `- fact`. The parser also accepts plain lists, bold labels, numbered lists and JSON. It deduplicates, strips date prefixes, and when a memory mentions one of your projects by name, links them in the graph.

## MCP tools

| Tool | What it does |
|---|---|
| `list_vault(prefix?)` | Lists vault files with their description |
| `read_file(path)` | Reads a file |
| `write_file(path, content)` | Creates or replaces a file |
| `append_file(path, content)` | Appends to a file |
| `str_replace_file(path, old, new)` | Targeted replace (`old` must appear exactly once) |
| `delete_file(path)` | Deletes a file (recoverable) |
| `file_history(path)` | A file's versions |
| `restore_file(path, version_id)` | Restores a file to an earlier version (also brings back deleted files) |
| `add_memory(fact, category?)` | Saves a fact about you to your memory, without duplicates |
| `list_skills()` / `get_skill(name)` | Skills: reusable instructions in `skills/` |
| `save_url(url, render_js?)` | Scrapes, indexes and saves a URL |
| `search_knowledge(query, top_k?)` | Semantic search over what you saved |
| `list_sources()` | Every saved URL |

## The `brain` command

```text
brain                 opens the dashboard and starts Ollama and Chroma
brain --port 8766     dashboard on another port
brain --no-autostart  don't start Ollama/Chroma automatically
brain --no-browser    don't open the browser
brain update          updates to the latest version
brain path            shows where it's installed
brain uninstall       removes the command (keeps your data)
brain help            help
```

## Data, privacy and security

- **Everything is local.** Your data lives in `~/.brain/vault/` and `~/.brain/data/`. Both folders are in `.gitignore`, so they're never uploaded anywhere, not even if you fork the repo.
- **No external services.** Embeddings are computed with Ollama on your machine. brain only goes online when you ask it to save a URL.
- **The dashboard only accepts requests from your own machine.** It listens on `127.0.0.1`, rejects requests with any other `Host` (DNS-rebinding protection), and its actions require a custom header browsers won't send from other pages. No website you have open can start processes or write to your vault.
- **Agents can't leave the vault.** The tools reject paths with `..`, absolute paths, hidden files and symlinks that point outside.
- **Everything can be undone.** Any write can be reverted with `file_history` + `restore_file`.

To start from scratch: close the dashboard and your agents, and delete `~/.brain/vault` and `~/.brain/data`. They're recreated empty on the next start.

## Troubleshooting

| Problem | Fix |
|---|---|
| "Ollama isn't running" | Turn on the Ollama switch in the Dashboard, or open the Ollama app. |
| "The Chroma server isn't running" | Open the dashboard (`brain`); it starts Chroma. Agents need it for `save_url` and `search_knowledge`. |
| An app returns `403` when connecting | You used "Connect to a URL". Use **Run a command** with the values from [Apps with an "Add MCP server" form](#apps-with-an-add-mcp-server-form). |
| brain doesn't show up in Claude Desktop | Connect it from **Connect agent** and restart Claude. Check **My connections**. |
| brain doesn't show up in ChatGPT | Use **Codex** or **ChatGPT Work** mode and go to *Settings → MCP servers → Restart*. Regular chat doesn't use local servers. |
| "Couldn't extract text from that URL" | The site may be paywalled or require a login. Try *Force JS rendering*. |
| `brain: command not found` | Open a new terminal. If it persists, add `export PATH="$HOME/.local/bin:$PATH"` to your `~/.zshrc`. |
| Port 8765 is taken | `brain --port 8766` |

## Uninstalling

1. In the dashboard, **Connect agent** → disconnect your agents (or remove the `brain` entry from their config).
2. `brain uninstall` removes the command.
3. `rm -rf ~/.brain` deletes the app **and your data**.

## Development

- [`CLAUDE.md`](CLAUDE.md): technical guide for agents working on the repo (architecture, conventions and gotchas).
- [`CHANGES.md`](CHANGES.md): the log of every change and decision. New changes are appended at the end.
- [`BUILD.md`](BUILD.md): the original spec.
- [`docs/`](docs/): the website, published with GitHub Pages.

```bash
git clone https://github.com/Lautaro005/brain && cd brain
uv sync && ./brain.sh
```

The dashboard UI is available in English and Spanish; the internal docs (`CLAUDE.md`, `CHANGES.md`, `BUILD.md`) are in Spanish.

## License

[MIT](LICENSE) © 2026 Lautaro Silva