brain

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

brain is an MCP server that runs on your computer (macOS, Linux or Windows) 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; agents in the cloud (Claude.ai, Manus on the web…) can reach it through an optional private URL.

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.

curl -fsSL https://raw.githubusercontent.com/Lautaro005/brain/main/install.sh | bash      # macOS and Linux

irm https://raw.githubusercontent.com/Lautaro005/brain/main/install.ps1 | iex               # Windows (PowerShell)

Then type brain and the dashboard opens.

Website: https://lautaro005.github.io/brain/ · Docs: https://lautaro005.github.io/brain/docs/ · Changelog: https://lautaro005.github.io/brain/changelog/

---

Contents

• What you can do
• Installation
• Getting started
• The dashboard
• Connecting agents
• How it works
• Connections
• Fact check
• MCP tools
• The brain command
• Data, privacy and security
• Troubleshooting
• Uninstalling
• Development
• License
• Security

---

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.
• Chat with your memory. A local Ollama model that already knows your profile and memory. Ask it things, or have it save, add or edit notes for you. Chats are kept in Chroma, and you can pop the chat out into a floating window that stays on top of your other apps.
• See how everything connects. An interactive graph shows your profile, memories, projects, skills, sources and tags, and how they relate. When the chat or an agent wants to link or unlink notes, you first see an image of the change and approve it.
• Check facts, with the evidence in view. Fact check splits a text into claims, looks in your memory first and on the web only if needed, reads every page, looks for counter-evidence and gives a verdict by rules, with quotes, dates and limitations.
• Undo anything. Every write goes into a version history. If an agent deletes or overwrites something, you get it back.
• Bring your apps along. Plug other MCP servers into brain (GitHub, Notion, Gmail…, or hundreds of apps through Composio): their tools show up in every agent you connected, and whatever they fetch is saved to your memory automatically.
• Private by design. Embeddings are computed on your machine with Ollama, and your data never leaves your computer (the only request brain makes on its own is checking GitHub for a new version; Fact check searches the web only when you run it).

Installation

Requirements: macOS, Linux or Windows, and git. The installer takes care of the rest.

Missing git? macOS: xcode-select --install. Linux: your distro’s package manager (sudo apt install git). Windows: the installer tries winget, or get it from git-scm.com. brain-setup.exe isn’t code-signed yet, so Windows SmartScreen may ask you to confirm (More info → Run anyway).

Every commit to main runs the tests and both installers on macOS, Linux and Windows in GitHub Actions, and every release attaches the Windows .exe and the Linux installer.

The installer:

1. Installs 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 if needed (Homebrew on macOS, winget on Windows, the official script on Linux when sudo doesn’t ask for a password; otherwise it tells you the command), and pulls the nomic-embed-text embedding model (~270 MB). Without Homebrew, it tells you where to download Ollama. The chat model (llama3.2, ~2 GB) is optional and not pulled automatically: it powers the Chat tab, source summaries (abstract) and entity extraction for the graph. Get it with ollama pull llama3.2 or the Download llama3.2 button in the Chat tab; without it those three features are skipped and everything else works. Use another model with BRAIN_SUMMARY_MODEL=, or turn summaries and entities off with BRAIN_SUMMARY_MODEL=off.
5. Creates the brain command in ~/.local/bin (%USERPROFILE%\.local\bin\brain.cmd on Windows) and adds it to your PATH if it wasn’t there.

On Linux, Chromium needs some system libraries; if they’re missing the installer prints the one command to add them (sudo uv run playwright install-deps chromium).

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

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

Open in Obsidian (in the sidebar, can be hidden from Settings like any view) opens the vault in Obsidian, with its folders and files in order. brain adds the vault to Obsidian’s vault list (with Obsidian closed, keeping a .bak-brain copy of its settings) and, the first time, a small .obsidian/ config so links are written the way brain writes them and the graph is colored by folder. If Obsidian isn’t installed, it tells you where to get it and which folder to open.

The bottom of the sidebar has the theme (system, light or dark; in system everything, the graph included, follows your OS when it switches between light and dark), the language (English / Español), an i button that lists the services (Chroma, Ollama, MCP Inspector) and their state, and Settings (the gear), a full view where you can:

• see the installed version and check for updates: brain asks GitHub for the latest release when the dashboard opens, every 3 hours while it’s open, and when you click the button. If there’s a newer one, Settings shows it with a link to the release notes and the gear turns green; the green Update and restart button next to Check for updates closes brain, updates it and reopens it (the page reloads by itself), or run brain update;
• reorder the sidebar and hide the views you don’t use (a hidden view is still reachable by its URL, e.g. #logs);
• pick the default chat model, used when the chat opens and on every new chat;
• set the chat’s context window: each model’s maximum with a cap for all (16k by default), everything each model supports, or a value per model, with a table of the detected models and what they support;
• make a backup of everything local (vault, history, settings, connections and what’s indexed in Chroma, embeddings included) and restore it; credentials are left out unless you tick the box, and restoring first saves a backup of the current state;
• set up an automatic backup (Automatic backup…): the folder (any folder, e.g. an external drive or a synced folder, with a folder picker), how often (every X hours, every day or once a week, at a set time), the file name ({date}, {time}, {version}, {n}), how many to keep, whether to include credentials and whether to skip it when nothing changed. It runs while brain is open, and catches up when you open it if one was missed;
• write a system prompt for the chat: how you want it to answer (tone, format, language, focus), added to brain’s own instructions; the chat’s fixed app context is shown below it, read-only;
• turn on system notifications for uploads, changes and deletions in your vault, whether an agent, the chat or you made them;
• note format: fill in type, created and updated on older notes in one click (new writes get them automatically);
• give each graph node type (Brain, brain files, Profile, Memory, Projects, Skills, Sources, Notes, Folders, Tags, Entities) its own color, or go back to black and white.

The button next to the logo collapses the sidebar into a narrow rail of icons.

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 (.bak-brain).

Paths are the macOS ones; on Windows they’re under %APPDATA% and on Linux under ~/.config. All the local agents launch the same server (uv run --directory ~/.brain python server.py) with absolute paths, so they work from any folder.

Remote access by URL

For agents that run in the cloud or on another computer (Manus on the web, Claude.ai custom connectors, ChatGPT developer mode…), Connect agent → By URL publishes brain’s MCP server through a Cloudflare tunnel. Off by default.

• brain runs server.py --http on 127.0.0.1:8770 and cloudflared publishes it; no ports are opened on your router. The first time, Install cloudflared downloads it from Cloudflare’s GitHub release and checks the published SHA256 (or brain uses the one you installed with brew, winget or apt).
• The URL is https://…//mcp; without the token every request gets 404. Apps that prefer a header can use …/mcp with Authorization: Bearer . Generate a new URL cuts off the old one right away, and Read-only leaves only the tools that read and search.
• Without a Cloudflare account the URL is a *.trycloudflare.com address that changes each time it starts. For a fixed one, create a tunnel in your account pointing to http://localhost:8770 and paste its hostname and token under Fixed URL with your Cloudflare account.
• Through the URL, save_url and read_url only fetch public addresses, never your computer or local network.
• It stays up until you turn it off or close brain. While it’s on, brain keeps the computer from going to sleep by itself (the screen can still turn off; untick Keep the computer from sleeping to allow it). If the computer sleeps anyway (closing the lid), a watchdog checks the tunnel on wake: cloudflared reconnects with the same URL, and if it can’t, or the tunnel no longer exists on Cloudflare’s side, brain reopens it by itself. A quick tunnel then gets a new *.trycloudflare.com URL and the card tells you; a named tunnel keeps its URL. Reconnect does the same by hand.

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. If the app only takes a URL, use remote access: pointing it at the dashboard’s address returns 403, because the dashboard only accepts requests from its own page.

The Connect agent tab shows these values already filled in for your machine, each with a copy button. Once the app uses brain for the first time, it appears under My connections on its own.

Connections

brain is also an MCP client. In the Connections tab you add other MCP servers, and brain re-exposes their tools to every agent you connected, prefixed with the connection’s name (github__create_issue, composio__GMAIL_FETCH_EMAILS) so they never clash with brain’s own tools.

• Local command (recommended): an MCP server that runs on your Mac, e.g. npx -y @modelcontextprotocol/server-github with GITHUB_TOKEN=…. The token stays on your machine.
• URL: a remote MCP server, with optional headers (Authorization: Bearer …).
• Composio (optional). Composio stores your accounts’ OAuth tokens in its own cloud; brain keeps the key, the configuration and everything it fetches locally. Two kinds of key work:
  • Consumer key (ck_…, the usual one from dashboard.composio.dev): paste it and click Save and connect. brain connects to https://connect.composio.dev/mcp with the x-consumer-api-key header, and the apps you already linked in Composio come with it. No user ID needed.
  • Project key (ak_…): fill in the user ID, click Choose apps, pick the auth configs, and brain creates the MCP server through Composio’s developer API (x-api-key).
  • Disconnect removes the Composio connection and wipes the key from .env.

Every connection has two switches: Active (turn it off and its tools disappear from your agents right away) and Save to memory. With the second one on, each result is written to vault/knowledge/connections//…md (or knowledge/composio//…), with the tool name, arguments and time in its frontmatter, and indexed in Chroma: what you fetched from GitHub or Gmail becomes searchable with search_knowledge and shows up in the graph.

Secrets (env values, headers, the Composio API key) live in ~/.brain/.env with 600 permissions, outside the vault and never committed. The connection list lives in ~/.brain/data/connections.json.

Fact check

The Fact check view verifies claims with a process you can see, instead of a “true/false” button:

1. The local chat model splits the text into checkable claims and marks opinions, predictions and vague statements as not verifiable.
2. Each claim is searched in brain first. If nothing relevant is saved, it’s old, your notes disagree, there’s no primary source or it’s a current topic, brain searches the web (if you allow it) and tells you it did.
3. It runs a neutral query, an evidence query, a counter-evidence query and a primary-source query; opens and reads every page (a page it can’t open is marked not fully inspected and doesn’t count); types each source (official, academic, fact-checker, news, reference, social, other) by what it is; and groups pages from the same site or with copied text into one line of evidence.
4. The model says whether each source supports, contradicts or supports with limits, and must quote the exact sentence; a quote that isn’t in the page doesn’t count.
5. The verdict comes from fixed rules over independent lines of evidence: never “supported” with a single secondary source, and conflicting evidence is shown as a conflict.

Preferences (level, freshness, primary sources, counter-evidence, claim types, high-risk topics with extra rigor, regions, languages, source types, search engine, blocked domains) are set once in the view.

FACT-CHECK.md (at the root of the vault, next to FORMAT.md) is the same method written for any AI: when to leave brain and search the web, what counts as a source, how to quote and what verdict to give, and how to answer. Its Preferences block rewrites itself whenever you change them in the view, so every agent follows the same rules. Agents are told to read it (server instructions, fact_check and search_knowledge when it finds nothing), and the chat gets a reminder in every answer and the full guide with /factcheck or automatic checking on.

Nothing is saved to your vault unless you click Save to brain. It also works from the chat (/factcheck) and for agents (fact_check, which always applies your preferences). Turn on Let the chat and all your agents check facts that aren’t in brain and every connected agent gets that instruction, and search_knowledge suggests fact_check when it finds nothing. For health, law, finance or safety it reminds you it’s informational, not professional advice.

How it works

flowchart LR
    subgraph Agents
        A1[Claude Desktop]
        A2[ChatGPT]
        A3[Claude Code / Cursor / …]
    end
    subgraph brain["brain (your Mac)"]
        S1[server.pyone process per agent]
        V[(vault/Markdown)]
        H[(data/history.sqlite3versions)]
        C[(Chromashared HTTP server)]
        O[Ollamanomic-embed-text]
        P[Playwrightheadless Chromium]
        D[Dashboard127.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
    S1 -- MCP client --> X[Your connectionsGitHub · Notion · Composio…]
    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 and tells the model to read BRAIN.md, your profile and your memory first. With remote access on, the dashboard also runs one copy over streamable HTTP (server.py --http, 127.0.0.1:8770) behind a Cloudflare tunnel.
• Vault (~/.brain/vault/). Markdown files with YAML frontmatter:
  • BRAIN.md: the root and short index the agent reads first. Everything comes out of it: FORMAT.md (the vault’s structure, note types, fields and how to connect notes), FACT-CHECK.md (what to do when the vault isn’t enough), profile.md and the base folders. brain keeps a block at its top with those links; the rest is yours.
  • 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.
  • Every note carries type (Project, SubProject, File, Memory, Skill, Source…; inside projects/, a project’s main note is a Project, a subfolder’s main note a SubProject and everything else a File, and the graph links each part to its project), created and updated, filled in by brain on every write: a small profile of the Open Knowledge Format, so any AI can tell what a note is and how current it is. FORMAT.md at the root of the vault explains the structure, every type and field, where a new note goes and how to connect it (a project and its files share the project’s tag) to your agents. Links can be [text](path.md) or [[name]].
  • Core files are yours. BRAIN.md, FORMAT.md, FACT-CHECK.md and the base folders can’t be written, moved or deleted through the tools (the chat included): agents read them and ask you for changes, and you edit them in the graph. When you change FORMAT.md or FACT-CHECK.md, brain stops updating them on new versions (managed: user).
• 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 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 chunks of up to ~500 words (50-word overlap) that follow its structure: a heading stays with its first paragraph, lists, tables and code blocks aren’t cut, and a chunk that starts mid-section carries the section title, which also goes into the chunk’s metadata.
4. It embeds each chunk with Ollama and stores it in Chroma, with metadata pointing back to the source .md. The same chunks go into a keyword index (SQLite FTS5, data/search.sqlite3), which catches proper names, IDs and exact numbers that embeddings miss.
5. If a chat model is installed in Ollama, it adds a short abstract (pages over 800 words) and the entities it names (people, places, organizations, projects) to the frontmatter. Both are optional: without the model the page is saved the same way.
6. It writes knowledge/sources/.md with the full text, its chunk ids, type: Source, title, resource (the URL) and, when the page shows them, author and published. Saving the same URL again updates it instead of duplicating it.

Search (search_knowledge) runs the semantic search and the keyword search, and merges both lists with reciprocal rank fusion. If Chroma or Ollama is down, keyword search keeps working and the answer says so.

Memory over time: each fact carries the date it was saved (an HTML comment at the end of the bullet, invisible when reading). When a fact changes, add_memory(new, supersede=old) moves the old one to a ## Historial section with the date it stopped being true, so agents only see what’s current and the past isn’t lost.

Entities in the graph: notes in knowledge/ and memory/ get an entities list. Two notes that name the same person or project end up connected through a shared entity node, even if nobody linked them.

Reflect (Profile tab) reviews what’s stored and suggests fixes: facts duplicated across categories, facts that probably contradict each other, and recent notes without entities. It never writes anything; each suggestion shows the tool call that would apply 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

Every write validates the note’s YAML frontmatter. If an agent writes a value that breaks it (typically an unquoted : in a description), brain quotes it automatically; if it can’t be repaired, the write is rejected with a clear error, so metadata never silently disappears from the graph.

The brain command

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 (Settings → Update and restart does it from the dashboard)
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 by default. Embeddings are computed with Ollama on your machine. brain only goes online when you save or refresh a URL, use a connection that talks to a remote service, checks GitHub for a new version (it only reads the latest release number), runs a Fact check that needs the web (the claims go as queries to the search engine you chose, and the result pages are opened; never pages on your machine or local network), or keeps the Cloudflare tunnel open if you turn on remote access. Composio, if you use it, keeps your app tokens in its cloud.
• 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.
• Remote access is opt-in and locked with a token. The URL carries a secret token (regenerate it any time), can be set to read-only, and the server behind it listens only on 127.0.0.1. The token is in ~/.brain/data/remote.json (600).
• Agents can’t leave the vault. The tools reject paths with .., absolute paths, hidden files and symlinks that point outside. Inside it, BRAIN.md, FORMAT.md, FACT-CHECK.md and the base folders are read-only for them.
• Secrets stay out of the vault and the repo. Connection tokens and API keys are in ~/.brain/.env, and OAuth sign-ins in ~/.brain/data/oauth.json (both permissions 600, gitignored); the dashboard never shows them back, and backups leave them out unless you ask.
• Agents can propose, not install. An agent (or the chat’s /add-mcp) can only propose a new connection; nothing runs until you click Add and see the exact command or URL. The same goes for graph changes: nothing changes until you approve the image.
• Everything can be undone. Any write can be reverted with file_history + restore_file, and Settings → Backup keeps full copies you can restore.

The website’s privacy policy covers the site too (its chat assistant is provided by DokBot).

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

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: technical guide for agents working on the repo (architecture, conventions and gotchas).
• CHANGES.md: the log of every change and decision. New changes are appended at the end.
• BUILD.md: the original spec.
• docs/: the website, published with GitHub Pages.

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 with the Commons Clause © 2026 Lautaro Silva.

You can use, study, modify and share brain for free, including at work. The Commons Clause adds one restriction: you may not sell it, meaning you can’t charge third parties for a product or service (hosting, support or consulting included) whose value comes entirely or substantially from brain. It applies to every version of brain.

Both parts are in LICENSE: the Commons Clause condition first, then the MIT text. GitHub only auto-detects standard license templates, and MIT + Commons Clause isn’t one, so the sidebar shows “View license” instead of a license name. That is expected: the only way to get an “MIT” label would be to drop the condition, and plain MIT would allow selling it.

Security

To report a vulnerability, see SECURITY.md. Please don’t open a public issue for it.