Introduction
brain is a local MCP server that gives Claude, ChatGPT, Cursor and any other AI agent the same memory about you. It runs on your computer (macOS, Linux or Windows); nothing goes to anyone's cloud.
What brain is
Every AI app keeps its own little memory, and none of them talk to each other. brain is one knowledge base that all of them read and write through MCP, the standard protocol agents use to call tools:
- A vault of Markdown notes — your profile, what agents learned about you, projects, reusable skills and saved web pages.
- Search — hybrid: semantic (by meaning, with embeddings computed locally by Ollama) plus exact keyword (names, IDs, dates).
- A version history — every write is recorded, so anything an agent changes can be undone.
- A dashboard — a local web app to turn services on and off, edit your profile, import memory from other chatbots, connect agents, explore the graph and chat with a local model.
How the pieces fit
Each agent launches its own server.py process and talks to it over stdio. All processes share the same vault, the same history database and one Chroma server, and a file lock keeps concurrent writes safe.
| Piece | What it does | Where |
|---|---|---|
| MCP server | Exposes the tools to your agents | server.py |
| Vault | Markdown with YAML frontmatter | ~/.brain/vault/ |
| History | Previous and new content of every write | data/history.sqlite3 |
| Keyword index | SQLite FTS5 (BM25) over saved text | data/search.sqlite3 |
| Chroma | Vector database, shared HTTP server | 127.0.0.1:8055 |
| Ollama | Embeddings (nomic-embed-text) and the optional chat model | localhost:11434 |
| Dashboard | Local web UI | 127.0.0.1:8765 |
Who it's for
People who use more than one AI tool and are tired of explaining themselves again in each one. You don't need to write code: the installer and the dashboard cover everything. Developers get a plain Markdown vault and MCP tools they can build on.
Introducción
brain es un server MCP local que les da a Claude, ChatGPT, Cursor y cualquier otro agente de IA la misma memoria sobre vos. Corre en tu compu (macOS, Linux o Windows); nada va a la nube de nadie.
Qué es brain
Cada app de IA guarda su propia memoria, y ninguna habla con las otras. brain es una sola base de conocimiento que todas leen y escriben por MCP, el protocolo estándar con el que los agentes llaman tools:
- Un vault de notas en Markdown: tu perfil, lo que los agentes aprendieron de vos, proyectos, skills reutilizables y páginas web guardadas.
- Búsqueda híbrida: semántica (por significado, con embeddings calculados en tu máquina por Ollama) más por palabra exacta (nombres, IDs, fechas).
- Historial de versiones: cada escritura queda registrada, así que cualquier cambio de un agente se puede deshacer.
- Un dashboard: una web local para prender y apagar servicios, editar tu perfil, importar la memoria de otros chatbots, conectar agentes, explorar el grafo y chatear con un modelo local.
Cómo encajan las piezas
Cada agente lanza su propio proceso de server.py y le habla por stdio. Todos comparten el mismo vault, la misma base de historial y un único server de Chroma, y un lock de archivo hace seguras las escrituras simultáneas.
| Pieza | Qué hace | Dónde |
|---|---|---|
| Server MCP | Expone las tools a tus agentes | server.py |
| Vault | Markdown con frontmatter YAML | ~/.brain/vault/ |
| Historial | Contenido anterior y nuevo de cada escritura | data/history.sqlite3 |
| Índice por palabra | SQLite FTS5 (BM25) sobre el texto guardado | data/search.sqlite3 |
| Chroma | Base vectorial, server HTTP compartido | 127.0.0.1:8055 |
| Ollama | Embeddings (nomic-embed-text) y el modelo de chat opcional | localhost:11434 |
| Dashboard | Interfaz web local | 127.0.0.1:8765 |
Para quién es
Para quien usa más de una herramienta de IA y está cansado de explicarse de nuevo en cada una. No hace falta programar: el instalador y el dashboard cubren todo. Si programás, tenés un vault de Markdown común y tools MCP para construir encima.
Installation
One command on macOS, Linux or Windows. You need git; the installer handles the rest. It installs brain two ways: the brain command (dashboard in your browser, from a terminal) and the desktop app (menu-bar or tray icon, system notifications and notch panel).
macOS and Linux
curl -fsSL https://raw.githubusercontent.com/Lautaro005/brain/main/install.sh | bash
Missing git? macOS: xcode-select --install. Linux: your distro's package manager (sudo apt install git). On Linux you can also download brain-install-linux.sh from the latest release and run it with bash.
Windows
In PowerShell:
irm https://raw.githubusercontent.com/Lautaro005/brain/main/install.ps1 | iex
Or download brain-setup.exe from the latest release: it runs the same script. It isn't code-signed yet, so SmartScreen may ask you to confirm (More info → Run anyway). The command is brain too (a brain.cmd in %USERPROFILE%\.local\bin, added to your user PATH).
What the installer does
- Installs uv if it's missing. uv manages Python and the dependencies without touching the system Python.
- Clones brain into
~/.brain(or runsgit pullif it's already there). - Runs
uv syncand installs the headless Chromium used to scrape JavaScript sites. - Installs Ollama if needed (Homebrew on macOS,
wingeton Windows, the official script on Linux whensudodoesn't need a password) and pullsnomic-embed-text(~270 MB). Otherwise it tells you the command to run. - Downloads the desktop app from the latest release:
~/Applications/brain.appon macOS,~/.local/opt/brain/brain.AppImagewith an app-menu entry on Linux, the installer for your user on Windows. If the release doesn't have it yet, it says so and brain keeps working in the terminal. - Creates the
braincommand in~/.local/binand adds it to yourPATH.
It's idempotent: running it again updates the install. It never asks for input, because it runs through curl | bash. On Linux, if Chromium is missing system libraries it prints the one command to add them (sudo uv run playwright install-deps chromium).
Every commit to main runs the tests and the installers on macOS, Linux and Windows in GitHub Actions, together with the checks of this site.
Optional: a chat model
The Chat tab, source summaries (abstract) and entity extraction for the graph use a chat model in Ollama. nomic-embed-text only computes embeddings and can't write text. The installer doesn't pull a chat model (it's ~2 GB); get one when you want those features:
ollama pull llama3.2
Or click Download llama3.2 in the Chat tab. Without it, those three features are skipped and everything else works the same.
Installer options
| Variable | Default | What it changes |
|---|---|---|
BRAIN_HOME | ~/.brain | Install folder |
BRAIN_BIN | ~/.local/bin | Where the brain command goes |
BRAIN_REPO | GitHub repo | Where to clone from (useful for testing a local clone) |
BRAIN_BRANCH | main | Branch to install |
BRAIN_SKIP_OLLAMA, BRAIN_SKIP_CHROMIUM | unset | Set to 1 to skip installing Ollama or Chromium |
BRAIN_NO_APP (or --no-app) | unset | Set to 1 to install only the terminal version, without the desktop app |
curl -fsSL https://raw.githubusercontent.com/Lautaro005/brain/main/install.sh | BRAIN_HOME=~/tools/brain bash
Manual installation
git clone https://github.com/Lautaro005/brain ~/.brain && cd ~/.brain uv sync uv run playwright install chromium ollama pull nomic-embed-text ./brain.sh
Instalación
Un comando en macOS, Linux o Windows. Hace falta git; el instalador se ocupa del resto. Instala brain de dos formas: el comando brain (dashboard en el navegador, desde una terminal) y la app de escritorio (ícono en la barra de menú o la bandeja, avisos del sistema y panel del notch).
macOS y Linux
curl -fsSL https://raw.githubusercontent.com/Lautaro005/brain/main/install.sh | bash
¿Falta git? macOS: xcode-select --install. Linux: el gestor de paquetes de tu distro (sudo apt install git). En Linux también podés bajar brain-install-linux.sh del último release y correrlo con bash.
Windows
En PowerShell:
irm https://raw.githubusercontent.com/Lautaro005/brain/main/install.ps1 | iex
O bajá brain-setup.exe del último release: corre el mismo script. Todavía no está firmado, así que SmartScreen puede pedir confirmación (Más información → Ejecutar de todas formas). El comando también es brain (un brain.cmd en %USERPROFILE%\.local\bin, que se agrega a tu PATH de usuario).
Qué hace el instalador
- Instala uv si falta. uv maneja Python y las dependencias sin tocar el Python del sistema.
- Clona brain en
~/.brain(o hacegit pullsi ya estaba). - Corre
uv synce instala el Chromium headless que se usa para scrapear sitios con JavaScript. - Instala Ollama si hace falta (Homebrew en macOS,
wingeten Windows, el script oficial en Linux cuandosudono pide contraseña) y bajanomic-embed-text(~270 MB). Si no puede, te dice qué comando correr. - Baja la app de escritorio del último release:
~/Applications/brain.appen macOS,~/.local/opt/brain/brain.AppImagecon una entrada en el menú de aplicaciones en Linux, el instalador de usuario en Windows. Si el release todavía no la trae, lo avisa y brain sigue andando en la terminal. - Crea el comando
brainen~/.local/biny lo agrega a tuPATH.
Es idempotente: correrlo de nuevo actualiza la instalación. Nunca pide nada, porque se ejecuta con curl | bash. En Linux, si a Chromium le faltan librerías del sistema, te muestra el comando para agregarlas (sudo uv run playwright install-deps chromium).
Cada commit a main corre las pruebas y los instaladores en macOS, Linux y Windows en GitHub Actions, junto con los chequeos de este sitio.
Opcional: un modelo de chat
La pestaña Chat, los resúmenes de fuentes (abstract) y la extracción de entidades para el grafo usan un modelo de chat en Ollama. nomic-embed-text solo calcula embeddings y no puede escribir texto. El instalador no baja un modelo de chat (pesa ~2 GB); bajalo cuando quieras esas funciones:
ollama pull llama3.2
O tocá Descargar llama3.2 en la pestaña Chat. Sin él, esas tres funciones se saltean y todo lo demás anda igual.
Opciones del instalador
| Variable | Por defecto | Qué cambia |
|---|---|---|
BRAIN_HOME | ~/.brain | Carpeta de instalación |
BRAIN_BIN | ~/.local/bin | Dónde va el comando brain |
BRAIN_REPO | el repo de GitHub | De dónde clonar (sirve para probar un clon local) |
BRAIN_BRANCH | main | Rama a instalar |
BRAIN_SKIP_OLLAMA, BRAIN_SKIP_CHROMIUM | sin definir | En 1, no instala Ollama o Chromium |
BRAIN_NO_APP (o --no-app) | sin definir | En 1, instala solo la versión de terminal, sin la app de escritorio |
curl -fsSL https://raw.githubusercontent.com/Lautaro005/brain/main/install.sh | BRAIN_HOME=~/tools/brain bash
Instalación manual
git clone https://github.com/Lautaro005/brain ~/.brain && cd ~/.brain uv sync uv run playwright install chromium ollama pull nomic-embed-text ./brain.sh
Quickstart
From install to an agent that knows you, in four steps.
1. Open the dashboard
brain
It opens http://127.0.0.1:8765 and starts Ollama and Chroma if they aren't running. Keep it open while you use your agents; Ctrl+C closes it and stops only what it started.
2. Connect your agents
Connect agent tab → Connect on Claude Desktop, ChatGPT, Claude Code, Cursor or whichever you use. brain adds its entry to that app's config (with a backup). Restart the app. Details in Connecting agents.
3. Tell it who you are
Profile tab → fill in About you. Then Import memory: pick the chatbot you use today, copy the prompt, paste it in that chatbot, and paste its answer back. You get a preview before anything is saved.
4. Try it
In any connected agent:
What do you know about me according to brain?
Save this URL to brain: https://example.com/some-article
I moved from Palermo to Núñez — update my memory.
The last one uses add_memory with supersede: the old fact isn't deleted, it moves to the history of that memory file with the date. See Memory.
Inicio rápido
De la instalación a un agente que te conoce, en cuatro pasos.
1. Abrí el dashboard
brain
Abre http://127.0.0.1:8765 y prende Ollama y Chroma si no están corriendo. Dejalo abierto mientras usás tus agentes; Ctrl+C lo cierra y apaga solo lo que prendió él.
2. Conectá tus agentes
Pestaña Conectar agente → Conectar en Claude Desktop, ChatGPT, Claude Code, Cursor o el que uses. brain agrega su entrada a la config de esa app (con backup). Reiniciá la app. Detalles en Conectar agentes.
3. Contale quién sos
Pestaña Perfil → completá Sobre vos. Después Importar memoria: elegí el chatbot que usás hoy, copiá el prompt, pegalo en ese chatbot y pegá la respuesta de vuelta. Ves una previsualización antes de guardar nada.
4. Probalo
En cualquier agente conectado:
¿Qué sabés de mí según brain?
Guardá esta URL en brain: https://example.com/un-articulo
Me mudé de Palermo a Núñez: actualizá mi memoria.
La última usa add_memory con supersede: el hecho viejo no se borra, pasa al historial de ese archivo de memoria con la fecha. Ver Memoria.
The vault
Plain Markdown files with YAML frontmatter in ~/.brain/vault/. It's created from a template the first time brain starts.
Layout
| Path | What goes there |
|---|---|
BRAIN.md | The root: a short index agents read first. Not content: just where each thing is. brain keeps a block at its top with links to the core files and folders; the rest is yours. |
FORMAT.md | The vault's structure for any AI: what comes out of BRAIN.md, note types, fields, where a new note goes and how to connect it. |
FACT-CHECK.md | What an AI does when the vault isn't enough and it has to search the web (see Fact check). |
profile.md | Your profile (name, headline, about you). |
memory/ | One file per category ("Work", "Preferences"…), one fact per bullet. |
projects/ | Notes about your projects. |
skills/ | Reusable instructions agents can load with get_skill. |
knowledge/sources/ | The full text of every saved URL. |
knowledge/connections/, knowledge/composio/ | Results captured from your connections. |
Frontmatter
Every note starts with a YAML block. name and description are expected; the description is what list_vault and the graph show.
--- type: Project name: online-store title: Online store description: Next.js store, launch at the end of the month tags: [work, nextjs] related: [pricing-that-converts] created: 2026-09-12 updated: 2026-10-04 --- # Online store Uses the ideas from [pricing that converts](../knowledge/pricing-that-converts.md).
Note format (OKF-compatible)
Since v0.03.1 notes follow a small profile of the Open Knowledge Format (OKF v0.2), so any AI or tool can tell what each note is and how current it is, without a special translation. brain's own fields stay valid as extensions.
| Field | What it says |
|---|---|
type | What the note is: Project, SubProject, File, Memory, Skill, Source, Reference, Profile, Index or Note. brain fills it in from the folder if it's missing (see Projects, sub-projects and files below). |
created | When the note was created (YYYY-MM-DD). Filled in on the first write and kept afterwards, even if an agent rewrites the file without it. |
updated | Last change. Every write moves it, except pure bookkeeping (checked_at, refresh_error). |
title, description | A readable title and a one-line summary. The file name stays the stable identity for links and history. |
resource, author, published | On saved pages: the source URL and, when the page says so, its author and date. |
For older notes, Settings → Note format → Fill in type and dates adds the three fields without touching anything else: created from the first change in the history (or the file date) and updated from the last one. Each note it touches is kept in history with the format operation. It also fixes the type: Project that v0.03.1 gave to every note inside a project folder.
Projects, sub-projects and files
| type | What it is | Where |
|---|---|---|
Project | The note that describes a project (goal, status, decisions, pending work). | projects/<name>.md, or the main note of projects/<name>/ (index.md, README.md or the one named like the folder). |
SubProject | A part of a project with its own identity (a module, an app, a stage). | The main note of a subfolder: projects/<project>/<sub>/index.md. |
File | Anything else inside a project: docs, notes, minutes, deliverables, specs. | Any other note under projects/<project>/. |
In the graph each one looks different, and every file and sub-project is linked to the project it belongs to (part of). An explicit type in the frontmatter wins over the folder. FORMAT.md, at the root of the vault, explains every type and field to your agents; brain keeps it up to date (remove managed: brain from it to edit it yourself).
Fields brain writes on its own: type, created, updated, chroma_ids (chunk ids of a source), abstract (summary of long sources), entities (names mentioned, for the graph), url, scraped_at, and in memory files category, sources and related.
Linking notes
[text](path.md)(standard Markdown, the most portable) or[[name]]in the text links to another note. Both count for the graph.tags: [a, b]groups notes under shared tag nodes.related: [name]relates notes without a link in the text.
Frontmatter validation
Every write checks the YAML. If an agent writes something that breaks it (usually an unquoted : in a description), brain quotes the value automatically. If it can't be repaired, the write is rejected with a clear error. Use set_frontmatter to change metadata without rewriting the note.
Structure
BRAIN.md root (only you edit it) ├── FORMAT.md structure and note format (only you) ├── FACT-CHECK.md when and how to search outside the vault (only you) ├── profile.md who you are ├── memory/ one file per category ├── projects/ <project>.md or <project>/index.md, with its files and sub-projects ├── skills/ reusable instructions └── knowledge/sources/ saved pages
Every project has its folders and files, and the project and each of its files carry the project's tag, so they stay connected even if they move. FORMAT.md tells agents where a new note goes (a fact about you → add_memory; a project's file → inside its folder; reusable instructions → skills/; a web page → save_url) and to check whether it already exists first.
Core files
BRAIN.md, FORMAT.md, FACT-CHECK.md and the base folders (projects/, skills/, memory/, knowledge/, knowledge/sources/) are yours. No AI can write, move or delete them through the tools (local agents, the chat and remote access alike): they read them and ask you for changes. You edit them from the graph (the lock next to the title). They are created on the first start, and an older BRAIN.md gets brain's block added without losing your text. FORMAT.md and FACT-CHECK.md are updated by brain when a new version improves them, until you edit them (they become managed: user).
Path safety
Tools reject empty and absolute paths, .., hidden files and symlinks that point outside the vault. Agents can't read or write anything else on your disk through brain.
El vault
Archivos Markdown comunes con frontmatter YAML en ~/.brain/vault/. Se crea desde una plantilla la primera vez que arranca brain.
Estructura
| Path | Qué va ahí |
|---|---|
BRAIN.md | La raíz: un índice corto que los agentes leen primero. No es contenido: solo dónde está cada cosa. brain mantiene un bloque arriba con los links a los archivos y carpetas centrales; el resto es tuyo. |
FORMAT.md | La estructura del vault para cualquier IA: qué sale de BRAIN.md, tipos de nota, campos, dónde va una nota nueva y cómo conectarla. |
FACT-CHECK.md | Qué hace una IA cuando el vault no alcanza y tiene que buscar en internet (ver Fact check). |
profile.md | Tu perfil (nombre, en una línea, sobre vos). |
memory/ | Un archivo por categoría ("Trabajo", "Preferencias"…), un hecho por viñeta. |
projects/ | Notas sobre tus proyectos. |
skills/ | Instrucciones reutilizables que los agentes cargan con get_skill. |
knowledge/sources/ | El texto completo de cada URL guardada. |
knowledge/connections/, knowledge/composio/ | Resultados capturados de tus conexiones. |
Frontmatter
Cada nota empieza con un bloque YAML. Se esperan name y description; la description es lo que muestran list_vault y el grafo.
--- type: Project name: tienda-online title: Tienda online description: Tienda en Next.js, lanzamiento a fin de mes tags: [trabajo, nextjs] related: [precios-que-convierten] created: 2026-09-12 updated: 2026-10-04 --- # Tienda online Usa las ideas de [precios que convierten](../knowledge/precios-que-convierten.md).
Formato de las notas (compatible con OKF)
Desde v0.03.1 las notas siguen un perfil chico del Open Knowledge Format (OKF v0.2), así cualquier IA o herramienta entiende qué es cada nota y qué tan vigente está, sin una traducción especial. Los campos propios de brain siguen siendo válidos como extensiones.
| Campo | Qué dice |
|---|---|
type | Qué es la nota: Project, SubProject, File, Memory, Skill, Source, Reference, Profile, Index o Note. Si falta, brain lo completa según la carpeta (ver Proyectos, subproyectos y archivos más abajo). |
created | Cuándo se creó la nota (AAAA-MM-DD). Se completa en la primera escritura y se conserva después, aunque un agente reescriba el archivo sin ese campo. |
updated | Último cambio. Cada escritura lo mueve, salvo los campos de control (checked_at, refresh_error). |
title, description | Un título legible y un resumen de una línea. El nombre del archivo sigue siendo la identidad estable para links e historial. |
resource, author, published | En las páginas guardadas: la URL de origen y, si la página lo dice, su autor y su fecha. |
Para las notas viejas, Ajustes → Formato de las notas → Completar tipo y fechas agrega los tres campos sin tocar nada más: created sale del primer cambio del historial (o de la fecha del archivo) y updated del último. Cada nota que toca queda en el historial con la operación format. También corrige el type: Project que v0.03.1 les puso a todas las notas de adentro de un proyecto.
Proyectos, subproyectos y archivos
| type | Qué es | Dónde |
|---|---|---|
Project | La nota que describe un proyecto (objetivo, estado, decisiones, pendientes). | projects/<nombre>.md, o la nota principal de projects/<nombre>/ (index.md, README.md o la que se llama como la carpeta). |
SubProject | Una parte de un proyecto con entidad propia (un módulo, una app, una etapa). | La nota principal de una subcarpeta: projects/<proyecto>/<sub>/index.md. |
File | Todo lo demás dentro de un proyecto: documentación, apuntes, actas, entregables, specs. | Cualquier otra nota dentro de projects/<proyecto>/. |
En el grafo cada uno se ve distinto, y cada archivo y subproyecto queda unido al proyecto del que es parte (parte de). Un type explícito en el frontmatter gana sobre la carpeta. FORMAT.md, en la raíz del vault, les explica a tus agentes cada tipo y cada campo; brain lo mantiene al día (sacale managed: brain si lo querés editar vos).
Campos que escribe brain solo: type, created, updated, chroma_ids (ids de los chunks de una fuente), abstract (resumen de fuentes largas), entities (nombres mencionados, para el grafo), url, scraped_at, y en los archivos de memoria category, sources y related.
Relacionar notas
[texto](ruta.md)(Markdown estándar, lo más portable) o[[nombre]]en el texto enlazan otra nota. Las dos cuentan para el grafo.tags: [a, b]agrupa notas bajo nodos de tag compartidos.related: [nombre]relaciona notas sin un link en el texto.
Validación del frontmatter
Cada escritura revisa el YAML. Si un agente escribe algo que lo rompe (típicamente un : sin comillas en una description), brain pone el valor entre comillas solo. Si no se puede reparar, la escritura se rechaza con un error claro. Usá set_frontmatter para cambiar metadatos sin reescribir la nota.
Estructura
BRAIN.md raíz (lo editás solo vos) ├── FORMAT.md estructura y formato de las notas (solo vos) ├── FACT-CHECK.md cuándo y cómo buscar afuera del vault (solo vos) ├── profile.md quién sos ├── memory/ un archivo por categoría ├── projects/ <proyecto>.md o <proyecto>/index.md, con sus archivos y subproyectos ├── skills/ instrucciones reutilizables └── knowledge/sources/ páginas guardadas
Cada proyecto tiene sus carpetas y archivos, y el proyecto y cada uno de sus archivos llevan el tag del proyecto, así siguen unidos aunque se muevan. FORMAT.md les dice a los agentes dónde va una nota nueva (un hecho sobre vos → add_memory; un archivo de un proyecto → dentro de su carpeta; instrucciones reutilizables → skills/; una página web → save_url) y que antes se fijen si ya existe.
Archivos centrales
BRAIN.md, FORMAT.md, FACT-CHECK.md y las carpetas base (projects/, skills/, memory/, knowledge/, knowledge/sources/) son tuyos. Ninguna IA los puede escribir, mover ni borrar con las tools (agentes locales, el chat y el acceso remoto): los leen y te piden los cambios. Los editás desde el grafo (el candado al lado del título). Se crean en el primer arranque, y a un BRAIN.md viejo se le suma el bloque de brain sin perder tu texto. brain actualiza FORMAT.md y FACT-CHECK.md cuando una versión nueva los mejora, hasta que los edites (pasan a managed: user).
Seguridad de paths
Las tools rechazan paths vacíos o absolutos, .., archivos ocultos y symlinks que salgan del vault. Los agentes no pueden leer ni escribir nada más de tu disco a través de brain.
Memory
What your agents know about you: a profile you write, plus facts imported from other chatbots or saved by agents as they learn them. Facts are dated, and when one changes the old version is kept.
Profile
profile.md holds your name, a one-line headline and a free "about me". Edit it in the Profile tab. Agents are told to read it first.
Below it, What brain knows about you is a summary of your memory that rewrites itself every time an agent, the chat or you add, change or delete a memory (with the local chat model if there is one; otherwise a list of the key facts per category). It goes at the end of profile.md, between markers, so every agent reads it; your own text is never touched. Turn it off or click Update now in the same card.
Memory files
Each category is one file in memory/ with one fact per bullet. Every active fact carries the date it was saved, as an HTML comment at the end of the line (invisible when reading the note):
--- name: about-me description: Memoria · About me (2) category: About me sources: [chatgpt, claude] related: [online-store] entities: [Palermo, Next.js] --- # About me - Lives in Núñez <!-- since:2026-09-28 --> - Building an online store in Next.js <!-- since:2026-09-20 --> ## Historial - Lives in Palermo (since 2026-03-02, superado el 2026-09-28, ver: "Lives in Núñez")
If a fact names one of your projects, skills or sources, the category is related to it automatically (related) and shows up connected in the graph.
Saving facts: add_memory
Agents call add_memory(fact, category?) whenever they learn something durable about you. Duplicates are ignored (comparison ignores case, accents and punctuation).
When a fact changes: supersede
If the new fact replaces an old one (you moved, changed jobs, switched tools), the agent passes the old text in supersede:
add_memory("Lives in Núñez", "About me", supersede="Lives in Palermo")
- The old fact isn't deleted: it moves to a
## Historialsection at the end of its file, with the date it stopped being true and what replaced it. - The match is the same as the duplicate check; if there's no exact match, a fact that contains the text (or is contained in it) is used when there's exactly one. It looks in the same category first, then in the others.
- If nothing matches, the new fact is saved anyway and the answer includes a warning.
- Agents only see active facts when they read your memory; the history stays in the file (
read_file) and inmemory_history(category).
Importing from other chatbots
Profile tab → Import memory. Pick Claude, ChatGPT, Gemini or other, copy the prompt (it asks the chatbot for everything it remembers, grouped as ## Category / - fact) and paste the answer. The parser also accepts plain lists, bold labels, numbered lists and JSON, strips date prefixes and drops the chatbot's intro line. You can remove items in the preview before importing.
Memoria
Lo que tus agentes saben de vos: un perfil que escribís vos, más hechos importados de otros chatbots o guardados por los agentes a medida que los aprenden. Los hechos llevan fecha, y cuando uno cambia se conserva la versión vieja.
Perfil
profile.md guarda tu nombre, una línea que te describe y un "sobre mí" libre. Se edita en la pestaña Perfil. Los agentes tienen la instrucción de leerlo primero.
Debajo, Lo que brain sabe de vos es un resumen de tu memoria que se reescribe solo cada vez que un agente, el chat o vos suman, cambian o borran un recuerdo (con el modelo de chat local si hay uno; si no, una lista de los hechos principales por categoría). Va al final de profile.md, entre marcas, así lo leen todos tus agentes; tu texto nunca se toca. Se apaga o se actualiza con Actualizar ahora en la misma tarjeta.
Archivos de memoria
Cada categoría es un archivo en memory/ con un hecho por viñeta. Cada hecho activo lleva la fecha en que se guardó, como comentario HTML al final de la línea (no se ve al leer la nota):
--- name: sobre-mi description: Memoria · Sobre mí (2) category: Sobre mí sources: [chatgpt, claude] related: [tienda-online] entities: [Palermo, Next.js] --- # Sobre mí - Vive en Núñez <!-- since:2026-09-28 --> - Está armando una tienda online en Next.js <!-- since:2026-09-20 --> ## Historial - Vive en Palermo (desde 2026-03-02, superado el 2026-09-28, ver: "Vive en Núñez")
Si un hecho nombra uno de tus proyectos, skills o fuentes, la categoría queda relacionada sola (related) y aparece conectada en el grafo.
Guardar hechos: add_memory
Los agentes llaman a add_memory(fact, category?) cuando aprenden algo duradero sobre vos. Los duplicados se ignoran (la comparación no distingue mayúsculas, acentos ni puntuación).
Cuando un hecho cambia: supersede
Si el hecho nuevo reemplaza a uno viejo (te mudaste, cambiaste de trabajo o de herramienta), el agente pasa el texto viejo en supersede:
add_memory("Vive en Núñez", "Sobre mí", supersede="Vive en Palermo")
- El hecho viejo no se borra: pasa a una sección
## Historialal final de su archivo, con la fecha en que dejó de valer y qué lo reemplazó. - La coincidencia es la misma que la de los duplicados; si no hay una exacta, se usa el único hecho que contiene el texto (o está contenido en él). Busca primero en la misma categoría y después en las demás.
- Si no coincide nada, el hecho nuevo se guarda igual y la respuesta trae un aviso.
- Al leer tu memoria, los agentes ven solo los hechos activos; el historial queda en el archivo (
read_file) y enmemory_history(category).
Importar de otros chatbots
Pestaña Perfil → Importar memoria. Elegí Claude, ChatGPT, Gemini u otro, copiá el prompt (le pide al chatbot todo lo que recuerda, agrupado como ## Categoría / - dato) y pegá la respuesta. El parser también acepta listas planas, etiquetas en negrita, listas numeradas y JSON, saca prefijos de fecha y descarta la línea de introducción del chatbot. En la previsualización podés sacar ítems antes de importar.
Saving and search
Save any web page, then find it by meaning or by exact words. Search is hybrid: semantic and keyword results are merged into one list.
Saving a URL
save_url(url, render_js?), or the Knowledge tab:
- trafilatura downloads the page and extracts clean text.
- If it gets fewer than 30 words (typical of JavaScript-built sites) or the download fails, the page is rendered in headless Chromium with Playwright and extracted again.
render_js=Truegoes straight to Chromium. - The text is split into ~500-word chunks with a 50-word overlap.
- Each chunk is embedded with Ollama (
nomic-embed-text) and stored in Chroma, and also written to the keyword index. - If a chat model is installed: pages over 800 words get a short
abstract, and the names they mention go toentities. knowledge/sources/<slug>.mdis written with the full text. Saving the same URL again updates it instead of duplicating it.
How search works
search_knowledge(query, top_k?) runs two searches and fuses them:
| Search | Good at | Engine |
|---|---|---|
| Semantic | Topics and paraphrases: "how to price a product" finds "pricing that converts" | Chroma + Ollama embeddings |
| Keyword | Proper names, IDs, numbers, dates, error codes | SQLite FTS5 with BM25 (data/search.sqlite3) |
Each side returns 3× top_k candidates, and they're merged with reciprocal rank fusion: every chunk scores Σ 1 / (60 + rank) over the lists it appears in. Chunks found by both rise to the top.
Each result has text, url, source_md_path, score (semantic similarity 0–1, or null if only the keyword search found it) and match (both, semantic or keyword). The keyword index ignores case and accents: "nunez" finds "Núñez".
When something is down
If Chroma or Ollama isn't running, keyword search keeps working and the answer includes a note saying semantic search wasn't available. It only fails if both are unavailable.
Rebuilding the keyword index
Sources saved before v0.02.5 aren't in the keyword index. Run reindex_keyword_search() (or Rebuild keyword index in the Knowledge tab): it rebuilds the index from the .md files in knowledge/ without scraping or embedding anything again.
Summaries
list_sources() returns each source's abstract, so an agent can decide whether a long page is worth reading in full. Summaries are best-effort: if Ollama doesn't answer, the source is saved without one.
Keeping sources fresh
Each source records when its content was downloaded (scraped_at) and when it was last checked (checked_at). The Knowledge tab shows both, marking content older than 30 days. Refresh (per source) or Refresh all downloads the page again: if it didn't change, only checked_at moves; if it did, the note and both indexes are updated. If the download or the indexing fails, the previous copy stays exactly as it was and the error is saved in refresh_error and shown in red. Agents can do the same with refresh_sources.
Guardar y buscar
Guardá cualquier página web y después encontrala por significado o por palabras exactas. La búsqueda es híbrida: los resultados semánticos y por palabra se juntan en una sola lista.
Guardar una URL
save_url(url, render_js?), o la pestaña Conocimiento:
- trafilatura baja la página y extrae el texto limpio.
- Si saca menos de 30 palabras (típico de sitios hechos con JavaScript) o falla la descarga, la página se renderiza en Chromium headless con Playwright y se extrae de nuevo.
render_js=Trueva directo a Chromium. - El texto se parte en chunks de ~500 palabras con 50 de solapamiento.
- Cada chunk se embebe con Ollama (
nomic-embed-text) y se guarda en Chroma, y también en el índice por palabra. - Si hay un modelo de chat instalado: las páginas de más de 800 palabras llevan un
abstractcorto, y los nombres que mencionan van aentities. - Se escribe
knowledge/sources/<slug>.mdcon el texto completo. Guardar la misma URL de nuevo la actualiza en vez de duplicarla.
Cómo funciona la búsqueda
search_knowledge(query, top_k?) corre dos búsquedas y las fusiona:
| Búsqueda | Sirve para | Motor |
|---|---|---|
| Semántica | Temas y paráfrasis: "cómo ponerle precio a un producto" encuentra "precios que convierten" | Chroma + embeddings de Ollama |
| Por palabra | Nombres propios, IDs, números, fechas, códigos de error | SQLite FTS5 con BM25 (data/search.sqlite3) |
Cada lado devuelve 3× top_k candidatos, y se fusionan con reciprocal rank fusion: cada chunk suma Σ 1 / (60 + posición) en las listas donde aparece. Los que encuentran las dos suben arriba.
Cada resultado trae text, url, source_md_path, score (similitud semántica 0–1, o null si solo lo encontró la búsqueda por palabra) y match (both, semantic o keyword). El índice por palabra ignora mayúsculas y acentos: "nunez" encuentra "Núñez".
Cuando algo está caído
Si Chroma u Ollama no están corriendo, la búsqueda por palabra sigue funcionando y la respuesta trae una nota que avisa que la semántica no estaba disponible. Solo falla si no está ninguna de las dos.
Reconstruir el índice por palabra
Las fuentes guardadas antes de v0.02.5 no están en el índice por palabra. Corré reindex_keyword_search() (o Reindexar búsqueda por palabra en Conocimiento): reconstruye el índice desde los .md de knowledge/ sin volver a scrapear ni embeber nada.
Resúmenes
list_sources() devuelve el abstract de cada fuente, así un agente decide si vale la pena leer entera una página larga. Los resúmenes son best-effort: si Ollama no responde, la fuente se guarda sin él.
Fuentes al día
Cada fuente anota cuándo se bajó su contenido (scraped_at) y cuándo se revisó por última vez (checked_at). La pestaña Conocimiento muestra las dos cosas y marca el contenido de más de 30 días. Actualizar (por fuente) o Actualizar todas vuelve a bajar la página: si no cambió, solo se mueve checked_at; si cambió, se actualizan la nota y los dos índices. Si falla la descarga o el indexado, la copia anterior queda tal cual y el error se guarda en refresh_error y se muestra en rojo. Los agentes pueden hacer lo mismo con refresh_sources.
The graph
An interactive map of the vault: how your profile, memories, projects, skills, sources, tags and entities connect.
Moving around
Click a node to see its note. Links inside the text jump to that note in the graph, and the Back button (top right, or Esc) returns to the previous note and then to the whole graph. Links to the web open in a new tab. The locked files (BRAIN.md, FORMAT.md, FACT-CHECK.md) hang only from BRAIN.md: other notes can't link to them.
Node types
The graph is black and white by default; types differ by fill, outline and stroke. Settings (gear icon in the sidebar) lets you give each type its own color.
| Type | What it is |
|---|---|
| Brain | BRAIN.md, the hub |
| brain files | FORMAT.md and FACT-CHECK.md, linked to the hub (structure) |
| Profile | profile.md, thick ring, labeled with your name |
| Memory | A memory category (hollow) |
| Projects | A project (solid) |
| Sub-projects | A part of a project (hollow, thick outline), linked to its project |
| Agents | An AI agent's notebook in agents/ (its main note); its other notes hang from it as files |
| Files | Any other note inside a project (small, light), linked to its project or sub-project |
| Skills, Notes | Files in skills/ and loose notes |
| Sources | Saved pages and captures (dashed outline), labeled with a short title: the page's title without the site name, or the end of the URL. The side panel shows the full title. |
| Folders, Tags | Folder hierarchy and tags: |
| Entities | A person, place, organization or project named in entities (small, dotted ring) |
How links are found
In order of strength (only the strongest is drawn per pair of nodes): [[wikilinks]] and Markdown links → memory under the profile → related: → shared entities → paths mentioned in backticks → tags → folders.
Entities
When a source, a capture or a memory file is saved, the local chat model lists the names it mentions and they go to entities in the frontmatter. Each entity becomes a node, so two notes that mention the same person or project end up connected through it, even if nobody linked them. It's best-effort: without a chat model in Ollama, notes are saved without entities, and Reflect lists the ones missing them.
Changing links with approval
When you ask the chat (or an agent) to link or unlink notes, it doesn't edit them: it calls propose_graph_change. brain checks the request against the real graph (the notes exist, the link isn't a duplicate, it isn't a link written in the text, at most 10 changes) and draws an image of that part of the graph with the changes marked: green dashed = new link, red dashed = link that goes away. The chat shows it with Approve change and Reject; proposals from agents also show at the top of the Graph view.
- Approving sends the proposal's id, so nothing is reinterpreted. If the notes changed after the proposal, it's marked stale and you ask for a new one.
- It's all or nothing, and approving twice doesn't duplicate anything.
- After applying, Undo puts the notes back (and every change is also in the history).
- This first version covers
relatedlinks. Links that come from the text, tags or entities are changed in the note itself.
Editing a note
The pencil (✎) next to a note's title in the side panel opens a floating window with its Markdown, frontmatter included: Edit / Preview, Save (or Ctrl/⌘ + S), Cancel or Esc (it warns you once if there are unsaved changes). If the note changed while you were editing (an agent, the chat or another tab), brain doesn't overwrite it and tells you. Every save goes to the history. It works for every .md note, not for folders, tags or entities. Core files (BRAIN.md, FORMAT.md, FACT-CHECK.md) show a lock instead of the pencil: AIs can't change them, and this editor is how you do. The structure is always visible: the base folders hang from BRAIN.md even when they're empty.
Controls
- Click a node to see its content and connections in the side panel;
[[links]]are clickable. - Filter by type with the chips, search by name.
- Zoom in/out and re-center with the buttons at the bottom right, the
+/-/0keys, or double-click the background.
El grafo
Un mapa interactivo del vault: cómo se conectan tu perfil, memorias, proyectos, skills, fuentes, tags y entidades.
Moverse
Un clic en un nodo muestra su nota. Los links del texto saltan a esa nota en el grafo, y el botón Atrás (arriba a la derecha, o la tecla Esc) vuelve a la nota anterior y después al grafo completo. Los links a la web se abren en otra pestaña. Los archivos bloqueados (BRAIN.md, FORMAT.md, FACT-CHECK.md) cuelgan solo de BRAIN.md: las demás notas no pueden linkearlos.
Tipos de nodo
Por defecto el grafo es blanco y negro; los tipos se distinguen por relleno, contorno y trazo. En Ajustes (engranaje del sidebar) podés darle un color a cada tipo.
| Tipo | Qué es |
|---|---|
| Brain | BRAIN.md, el centro |
| Archivos de brain | FORMAT.md y FACT-CHECK.md, unidos al centro (estructura) |
| Perfil | profile.md, anillo grueso, con tu nombre |
| Memoria | Una categoría de memoria (hueca) |
| Proyectos | Un proyecto (relleno) |
| Subproyectos | Una parte de un proyecto (hueco, contorno grueso), unida a su proyecto |
| Agentes | El cuaderno de un agente de IA en agents/ (su nota principal); sus otras notas cuelgan de ella como archivos |
| Archivos | Cualquier otra nota dentro de un proyecto (chico, claro), unida a su proyecto o subproyecto |
| Skills, Notas | Archivos de skills/ y notas sueltas |
| Fuentes | Páginas guardadas y capturas (contorno punteado), con un título corto: el título de la página sin el nombre del sitio, o el final de la URL. El panel lateral muestra el título completo. |
| Carpetas, Tags | Jerarquía de carpetas y tags: |
| Entidades | Una persona, lugar, organización o proyecto nombrado en entities (chico, anillo de puntos) |
Cómo se encuentran las relaciones
De más fuerte a más débil (se dibuja solo la más fuerte por par de nodos): [[wikilinks]] y links Markdown → memoria bajo el perfil → related: → entidades compartidas → paths mencionados entre backticks → tags → carpetas.
Entidades
Al guardar una fuente, una captura o un archivo de memoria, el modelo de chat local lista los nombres que menciona y van a entities en el frontmatter. Cada entidad es un nodo, así dos notas que nombran a la misma persona o proyecto quedan conectadas por él aunque nadie las haya enlazado. Es best-effort: sin un modelo de chat en Ollama, las notas se guardan sin entidades, y Reflect lista las que les faltan.
Cambiar conexiones con aprobación
Cuando le pedís al chat (o a un agente) que conecte o desconecte notas, no las edita: llama a propose_graph_change. brain valida el pedido contra el grafo real (que las notas existan, que no sea una conexión repetida, que no sea un link escrito en el texto, hasta 10 cambios) y dibuja una imagen de esa zona del grafo con los cambios marcados: verde punteado = conexión nueva, rojo punteado = conexión que se saca. El chat la muestra con Aprobar cambio y Rechazar; las propuestas de los agentes también aparecen arriba en la vista Grafo.
- Aprobar manda el id de la propuesta, así no se vuelve a interpretar nada. Si las notas cambiaron después de la propuesta, queda vencida y se pide otra.
- Se aplica todo o nada, y aprobar dos veces no duplica nada.
- Después de aplicar, Deshacer deja las notas como estaban (y cada cambio queda también en el historial).
- Esta primera versión cubre las conexiones de
related. Las que salen del texto, de tags o de entidades se cambian en la nota.
Editar una nota
El lápiz (✎) al lado del título de una nota en el panel lateral abre una ventana flotante con su Markdown, frontmatter incluido: Editar / Vista previa, Guardar (o Ctrl/⌘ + S), Cancelar o Esc (si hay cambios sin guardar, avisa una vez). Si la nota cambió mientras la editabas (un agente, el chat u otra pestaña), brain no la pisa y te avisa. Cada guardado queda en el historial. Sirve para cualquier nota .md, no para carpetas, tags ni entidades. Los archivos centrales (BRAIN.md, FORMAT.md, FACT-CHECK.md) muestran un candado en vez del lápiz: las IAs no los pueden cambiar, y este editor es la forma de hacerlo. La estructura se ve siempre: las carpetas base cuelgan de BRAIN.md aunque estén vacías.
Controles
- Click en un nodo para ver su contenido y conexiones en el panel lateral; los
[[links]]se pueden clickear. - Filtrá por tipo con los chips y buscá por nombre.
- Acercá, alejá y volvé al centro con los botones de abajo a la derecha, las teclas
+/-/0, o doble click en el fondo.
Version history
Every write and every delete stores the file's previous and new content. Any file can go back to any earlier version, including files that were deleted.
How it works
The history lives in data/history.sqlite3 (table changes: id, timestamp, operation, path, before, after). It doesn't use git, so the app's repo never carries your data or a nested repository.
Several processes write at the same time (one server.py per agent, plus the dashboard). Every write takes a file lock on data/.vault.lock that covers read, write and history, and SQLite runs in WAL mode.
Restoring
file_history("projects/online-store.md")
# → [{"id": 42, "ts": "2026-09-28T14:03:11Z", "op": "edit", …}, …]
restore_file("projects/online-store.md", 41)
The restore is itself recorded, so it can be undone too. Operations: create, update, edit, append, delete, restore.
Historial de versiones
Cada escritura y cada borrado guardan el contenido anterior y el nuevo del archivo. Cualquier archivo puede volver a cualquier versión anterior, incluso si se borró.
Cómo funciona
El historial vive en data/history.sqlite3 (tabla changes: id, fecha, operación, path, antes, después). No usa git, así que el repo de la app nunca arrastra tus datos ni un repositorio anidado.
Varios procesos escriben a la vez (un server.py por agente, más el dashboard). Cada escritura toma un lock de archivo sobre data/.vault.lock que cubre leer, escribir y registrar, y SQLite corre en modo WAL.
Restaurar
file_history("projects/tienda-online.md")
# → [{"id": 42, "ts": "2026-09-28T14:03:11Z", "op": "edit", …}, …]
restore_file("projects/tienda-online.md", 41)
La restauración también queda registrada, así que se puede deshacer. Operaciones: create, update, edit, append, delete, restore.
Dashboard
The local web app at http://127.0.0.1:8765, opened with brain. English or Spanish, light, dark or system theme.
Tabs
| Tab | What it's for |
|---|---|
| Dashboard | Switches for Chroma, Ollama and the MCP Inspector; vault metrics, 30-day activity, sources by domain, system health, recent changes. |
| Chat | A local Ollama model with your memory as context and the same tools as your agents. See Chat. |
| Profile | Your profile, your memory (filterable, delete per item), the memory importer and Reflect. |
| Connect agent | One-click connect/disconnect for each supported agent, remote access by URL for agents in the cloud, manual config for anything else, and My connections. |
| Connections | Other MCP servers brain uses for you, sign-in for the ones that need it, and connections proposed by agents. See Connections. |
| Graph | The graph. |
| Knowledge | Save a URL, hybrid search, rebuild the keyword index, list of sources with how old their content is and when they were last checked, and Refresh (one or all; a failed refresh keeps the last good copy and shows the error). |
| Prompts | Ready-to-paste instructions for your AI agent, with a copy button in English and Spanish. See Prompts for agents. |
| Logs | Live output of every service the dashboard manages. |
Services
Each service has a state: Running, Starting, External, Off or Error. When the dashboard starts it turns on Ollama and Chroma if they're off. If one was already running outside the dashboard (for example the Ollama menu-bar app) it shows as External, its switch is locked and the dashboard never stops it. Ctrl+C stops only what the dashboard started.
Sidebar
The button next to the logo collapses the sidebar into a narrow rail of icons. At the bottom: theme, language, services (the i button: Chroma, Ollama and the MCP Inspector with their state; it gets a red dot if one fails) and Settings (the gear). Preferences are stored in the browser (localStorage). With the theme on system, the dashboard, the graph and the chat follow your OS when it switches between light and dark.
Open in Obsidian
The last sidebar item opens your vault in Obsidian with its folders and files. brain adds the vault to Obsidian's vault list (only with Obsidian closed, and keeping a .bak-brain copy of its obsidian.json) and, the first time, leaves a minimal vault/.obsidian/ config: links written as standard Markdown (like brain) and the graph colored by folder. If Obsidian isn't installed, it tells you where to download it and which folder to open with Open folder as vault; if it's open and doesn't know the vault yet, it asks you to close it first. Hide the item from Settings → Sidebar like any view. What you change in Obsidian is your edit (the same as editing in the graph).
Anything that deletes or disconnects asks first in brain's own dialog, and the dropdowns are brain's too (keyboard: arrows, Enter, Esc).
Settings
A full view (#ajustes) with eight sections:
- Version: the installed version and a Check for updates button. brain asks GitHub for the latest release when the dashboard opens, every 3 hours while it's open, and when you click it. If there's a newer one, Settings shows it with a link to the release notes, the gear turns green, and a green Update and restart button appears next to Check for updates: brain closes, runs the update and reopens in the same terminal, and the page reloads by itself. You can also run
brain update. - Sidebar: reorder the views with the arrows and hide the ones you don't use. A hidden view is still reachable by its URL (
#logs,#grafo…). - Chat: the default model, selected when the chat opens and on every new chat. "The last one I used" keeps the previous behavior.
- Context: how much of each model's context window the chat uses. Either each model's maximum with a cap for all of them (16k by default), or everything each model supports, plus an optional value per model. The table lists the detected models, what they support and what they'll use. Saved in
data/chat_settings.json. - System prompt: your own instructions for the chat (tone, format, language, what to focus on, up to 4000 characters). They're added to brain's instructions on every reply; they don't change what the tools can do. Below them, folded, is the chat's fixed app context (how brain works), read-only.
- Notifications: system notifications when something changes in the vault, whether an agent, the chat or you did it. Turn on the ones you want: uploads (new files and sources), changes (edits, restores, moves) and deletions. They arrive while the dashboard is open, even in a background tab; the browser asks for permission the first time. In the desktop app they come from the app itself, even with the window closed.
- Backup: Create backup downloads a
.zipwith the vault, the version history, settings, connections and what's indexed in Chroma (with the embeddings, so restoring doesn't need Ollama); copies stay indata/backups. Credentials (.env, OAuth sign-ins) are only included if you tick the box. Restore (from the list or from a file) first saves the current state asbefore-restore-….zip, replaces everything, and rebuilds what the backup didn't bring (the keyword index always; Chroma from the vault if it wasn't exported). Rebuild indexes does that rebuild on its own. Automatic backup… opens its settings: the folder (any folder, like an external drive or a synced one, picked with a folder browser; by defaultdata/backups), how often (every X hours, every day or once a week, at the time you choose), the file name with{date},{time},{version}and{n}, how many to keep (it only deletes the ones it made itself), whether to include credentials and whether to skip a run when nothing changed. It runs while brain is open; if one was due while the computer was off, it makes it when you open brain. Make one now runs it with those settings, and automatic backups show up in the list with an auto tag. - Graph colors: a color per node type, or back to black and white.
Dashboard
La web local en http://127.0.0.1:8765, que se abre con brain. En español o inglés, con tema claro, oscuro o el del sistema.
Pestañas
| Pestaña | Para qué sirve |
|---|---|
| Panel | Switches de Chroma, Ollama y el Inspector MCP; métricas del vault, actividad de 30 días, fuentes por dominio, salud del sistema, últimos cambios. |
| Chat | Un modelo local de Ollama con tu memoria como contexto y las mismas tools que tus agentes. Ver Chat. |
| Perfil | Tu perfil, tu memoria (filtrable, se borra por ítem), el importador y Reflect. |
| Conectar agente | Conectar y desconectar cada agente soportado en un click, acceso remoto por URL para agentes en la nube, config manual para cualquier otro, y Mis conexiones. |
| Conexiones | Otros servers MCP que brain usa por vos, el login de los que lo piden y las conexiones que propusieron los agentes. Ver Conexiones. |
| Grafo | El grafo. |
| Conocimiento | Guardar una URL, búsqueda híbrida, reindexar la búsqueda por palabra, lista de fuentes con de cuándo es su contenido y cuándo se revisaron, y Actualizar (una o todas; si falla, queda la última copia buena y se muestra el error). |
| Prompts | Instrucciones listas para pegar en tu agente de IA, con botón para copiarlas en español e inglés. Ver Prompts para agentes. |
| Logs | Salida en vivo de cada servicio que maneja el dashboard. |
Servicios
Cada servicio tiene un estado: Corriendo, Iniciando, Externo, Apagado o Error. Al arrancar, el dashboard prende Ollama y Chroma si están apagados. Si uno ya corría por fuera (por ejemplo la app de Ollama) aparece como Externo, con el switch bloqueado, y el dashboard nunca lo apaga. Ctrl+C apaga solo lo que prendió él.
Sidebar
El botón al lado del logo pliega el sidebar en un riel angosto de íconos. Abajo: tema, idioma, servicios (el botón i: Chroma, Ollama y el Inspector MCP con su estado; lleva un punto rojo si alguno falla) y Ajustes (el engranaje). Las preferencias se guardan en el navegador (localStorage). Con el tema en sistema, el dashboard, el grafo y el chat siguen al sistema cuando cambia entre claro y oscuro.
Abrir en Obsidian
El último ítem del sidebar abre tu vault en Obsidian con sus carpetas y archivos. brain agrega el vault a la lista de vaults de Obsidian (solo con Obsidian cerrado, y guardando una copia .bak-brain de su obsidian.json) y, la primera vez, deja una configuración mínima en vault/.obsidian/: links en Markdown estándar (como brain) y el grafo con colores por carpeta. Si Obsidian no está instalado, te dice dónde bajarlo y qué carpeta abrir con Open folder as vault; si está abierto y todavía no conoce el vault, te pide cerrarlo primero. Ocultá el ítem desde Ajustes → Sidebar como cualquier vista. Lo que cambiás en Obsidian es una edición tuya (igual que en el grafo).
Todo lo que borra o desconecta pregunta antes en una ventana propia de brain, y los desplegables también son propios (teclado: flechas, Enter, Esc).
Ajustes
Una vista completa (#ajustes) con ocho secciones:
- Versión: la versión instalada y un botón Buscar actualizaciones. brain le pregunta a GitHub por el último release al abrir el dashboard, cada 3 horas mientras está abierto y cuando lo tocás. Si hay uno más nuevo, Ajustes lo muestra con un link a las novedades, el engranaje se pone en verde y aparece un botón verde Actualizar y reiniciar al lado de Buscar actualizaciones: brain se cierra, se actualiza y se vuelve a abrir en la misma terminal, y la página se recarga sola. También podés correr
brain update. - Sidebar: reordená las vistas con las flechas y ocultá las que no uses. Una vista oculta sigue accesible por su URL (
#logs,#grafo…). - Chat: el modelo por defecto, que se elige al abrir el chat y en cada chat nuevo. "El último que usé" mantiene el comportamiento de antes.
- Contexto: cuánto de la ventana de contexto de cada modelo usa el chat. El máximo de cada modelo con un tope para todos (16k por defecto), o todo lo que soporta cada uno, más un valor propio opcional por modelo. La tabla lista los modelos detectados, cuánto soportan y cuánto van a usar. Se guarda en
data/chat_settings.json. - System prompt: tus instrucciones para el chat (tono, formato, idioma, en qué enfocarse; hasta 4000 caracteres). Se suman a las de brain en cada respuesta; no cambian lo que pueden hacer las tools. Debajo, plegado, está el contexto fijo de la app del chat (cómo funciona brain), de solo lectura.
- Notificaciones: notificaciones del sistema cuando cambia algo en el vault, lo haga un agente, el chat o vos. Prendé las que quieras: cargas (archivos y fuentes nuevas), modificaciones (ediciones, restauraciones, movimientos) y eliminaciones. Llegan mientras el dashboard esté abierto, aunque esté en otra pestaña; la primera vez el navegador pide permiso. En la app de escritorio las manda la app misma, también con la ventana cerrada.
- Backup: Crear backup descarga un
.zipcon el vault, el historial de versiones, los ajustes, las conexiones y lo indexado en Chroma (con los embeddings, así restaurar no necesita a Ollama); las copias quedan endata/backups. Las credenciales (.env, sesiones OAuth) solo van si marcás la casilla. Restaurar (de la lista o desde un archivo) primero guarda el estado actual comobefore-restore-….zip, reemplaza todo y reconstruye lo que el backup no trae (el índice por palabra siempre; Chroma desde el vault si no venía exportado). Reconstruir índices hace solo esa reconstrucción. Backup automático… abre sus ajustes: la carpeta (cualquiera, como un disco externo o una carpeta sincronizada, elegida con un explorador de carpetas; por defectodata/backups), cada cuánto (cada X horas, todos los días o una vez por semana, a la hora que elijas), el nombre del archivo con{date},{time},{version}y{n}, cuántos conservar (solo borra los que hizo él), si incluye credenciales y si saltea una vuelta cuando no cambió nada. Corre mientras brain está abierto; si tocaba uno con la compu apagada, lo hace al abrir brain. Hacer uno ahora lo corre con esos ajustes, y los automáticos aparecen en la lista con la etiqueta auto. - Colores del grafo: un color por tipo de nodo, o volver a blanco y negro.
Desktop app
brain comes in two versions that share the same install, vault and data: the terminal version (the brain command opens the web dashboard in your browser) and the desktop app (the same dashboard in its own window, with an icon that stays in the menu bar or tray when you close it).
Which one
| Terminal + web dashboard | Desktop app | |
|---|---|---|
| Open it with | brain | brain app, or the brain icon in your apps |
| Closing it | Ctrl+C in the terminal stops everything it started | Closing the window leaves brain in the menu bar or tray; Close in its menu stops it |
| System notifications or the notch | Browser notifications while the page is open | Always, even with the window closed. Settings picks system notifications or the notch. |
| Logs | Services | Services plus an App tab with the app's own log |
The app doesn't replace anything: it starts the same dashboard (~/.brain/brain.sh) if none is running, shows it in a window, and stops it on quit only if it started it. If you already have brain open in a terminal, the app uses that dashboard and leaves it running.
Install
The installer adds the app by default (--no-app skips it): ~/Applications/brain.app on macOS, an AppImage with an app-menu entry on Linux (x86_64), and the user installer on Windows. Or download it from the latest release: .dmg (macOS), .AppImage or .deb (Linux), setup.exe (Windows). The app needs brain installed (~/.brain); if it isn't, its window shows the install command. The app is not code-signed yet: macOS may ask you to confirm the first time (right-click → Open) and Windows SmartScreen shows More info → Run anyway. The installer removes the macOS quarantine flag for you.
The menu-bar / tray icon
On macOS and Windows, click the icon to open the notch and right-click it for the menu. On Linux the tray opens the menu with a left click. The menu shows the version, a divider, then Open, Notifications, Settings, Updates and Close. Close asks the dashboard to shut down (it stops what it started) and quits the app. A vault change turns the icon into ● for a few seconds (the tooltip on Linux and Windows).
The notch
The panel grows down from the top center of the screen. On a Mac the black is the notch's own black, so the panel comes out of the notch with a short animation. Clicking the icon opens your vault graph in that panel. A notifications icon in the header shrinks it to the latest changes, which uses much less space than the graph. Tap the small panel to open the graph again; click a node to open the full graph. It closes itself a few seconds after you leave it (never while the pointer is on it), or with Escape or the icon. It opens on the screen where the pointer is. On Linux the tray can't tell clicks apart, so the menu has a Notch… item.
The app checks the vault's history every 5 seconds through the dashboard. When something is created, changed or deleted, whether an agent, the chat or you did it, Settings → Notifications chooses where it shows: a system notification, or a short notch alert with the same grow animation. Which changes count, and whether closing the window keeps brain in the tray, live in data/app_settings.json and travel in backups. Alerts still arrive with the window closed.
Logs
While the app runs, Logs has an App tab with its own log (start, tray actions, notifications, errors) and the dashboard's output when the app started it. It's the file ~/.brain/data/logs/app.log (rotated at 1 MB).
Moving from the terminal version
In the web dashboard, Settings → Desktop app → Move to the desktop app closes that dashboard (it stops what it started) and opens the app, which starts its own. Your data is the same. If the app isn't installed, the card links to the download.
Updating
Settings → Update and restart updates brain (the dashboard, the vault tools, everything Python) and the app window reloads by itself. The app itself (tray, notifications, notch) is its own program, so it checks that its version matches brain's: when brain is newer, the app quits, downloads the app from the latest release (brain app-update), installs it and opens again, so the icon and the window are never on different versions. If the release doesn't carry the app yet it reopens the one you had and tries again later. Run brain app-update or the installer again to force it.
Platforms
macOS 11 or later (Apple Silicon and Intel), Linux x86_64 with a tray (on GNOME you need the AppIndicator extension), and Windows 10/11. Built with Tauri 2 (Rust); the source is in apps/desktop.
App de escritorio
brain viene en dos versiones que comparten la misma instalación, vault y datos: la versión de terminal (el comando brain abre el dashboard web en tu navegador) y la app de escritorio (el mismo dashboard en su propia ventana, con un ícono que queda en la barra de menú o la bandeja cuando la cerrás).
Cuál usar
| Terminal + dashboard web | App de escritorio | |
|---|---|---|
| Se abre con | brain | brain app, o el ícono de brain en tus aplicaciones |
| Al cerrarla | Ctrl+C en la terminal apaga todo lo que prendió | Cerrar la ventana deja brain en la barra de menú o la bandeja; Close en su menú lo apaga |
| Notificación del sistema o notch | Notificaciones del navegador mientras la página esté abierta | Siempre, también con la ventana cerrada. Ajustes elige notificación del sistema o notch. |
| Logs | Servicios | Servicios y una pestaña App con el log de la app |
La app no reemplaza nada: arranca el mismo dashboard (~/.brain/brain.sh) si no hay uno corriendo, lo muestra en una ventana y al salir lo apaga solo si lo prendió ella. Si ya tenías brain abierto en una terminal, la app usa ese dashboard y lo deja corriendo.
Instalación
El instalador suma la app por defecto (--no-app la saltea): ~/Applications/brain.app en macOS, un AppImage con entrada en el menú de aplicaciones en Linux (x86_64) y el instalador de usuario en Windows. O bajala del último release: .dmg (macOS), .AppImage o .deb (Linux), setup.exe (Windows). La app necesita brain instalado (~/.brain); si no está, su ventana muestra el comando de instalación. La app todavía no está firmada: macOS puede pedir confirmación la primera vez (clic derecho → Abrir) y Windows SmartScreen muestra Más información → Ejecutar de todas formas. El instalador saca la marca de cuarentena de macOS por vos.
El ícono de la barra de menú / bandeja
En macOS y Windows, un clic en el ícono abre el notch y el clic derecho abre el menú. En Linux la bandeja abre el menú con el clic izquierdo. El menú muestra la versión, un divisor y después Open, Notifications, Settings, Updates y Close. Close le pide al dashboard que se apague (apaga lo que prendió) y cierra la app. Un cambio en el vault convierte el ícono en ● unos segundos (el tooltip en Linux y Windows).
El notch
El panel crece desde arriba al centro de la pantalla. En una Mac el negro es el del notch, así que el panel sale de ahí con una animación corta. El clic en el ícono abre el grafo del vault. Un ícono de notificaciones en el encabezado lo achica a los últimos cambios, que ocupa mucho menos que el grafo. Tocá ese panel chico para volver al grafo; un clic en un nodo abre el grafo completo. Se cierra solo unos segundos después de que lo dejás (nunca mientras el puntero está encima), o con Escape o el ícono. Se abre en la pantalla donde está el puntero. En Linux la bandeja no distingue clics, así que el menú tiene un ítem Notch….
La app mira el historial del vault cada 5 segundos a través del dashboard. Cuando algo se crea, cambia o se borra, lo haga un agente, el chat o vos, Ajustes → Notificaciones elige dónde se ve: una notificación del sistema, o un aviso chico en el notch con la misma animación. Qué cambios cuentan, y si cerrar la ventana deja brain en la bandeja, viven en data/app_settings.json y van en los backups. Los avisos llegan también con la ventana cerrada.
Logs
Mientras la app corre, Logs tiene una pestaña App con su propio log (arranque, acciones de la bandeja, avisos, errores) y la salida del dashboard cuando lo prendió la app. Es el archivo ~/.brain/data/logs/app.log (rota a 1 MB).
Pasar desde la versión de terminal
En el dashboard web, Ajustes → App de escritorio → Pasar a la app de escritorio cierra ese dashboard (apaga lo que prendió) y abre la app, que arranca el suyo. Tus datos son los mismos. Si la app no está instalada, la tarjeta lleva a la descarga.
Actualizar
Ajustes → Actualizar y reiniciar actualiza brain (el dashboard, las tools del vault, todo lo de Python) y la ventana de la app se recarga sola. La app en sí (bandeja, avisos, notch) es un programa aparte, así que comprueba que su versión coincida con la de brain: cuando brain es más nuevo, la app se cierra, baja la app del último release (brain app-update), la instala y se vuelve a abrir, para que el ícono y la ventana no queden en versiones distintas. Si el release todavía no trae la app, vuelve a abrir la que tenías y reintenta más tarde. Corré brain app-update o el instalador de nuevo para forzarlo.
Plataformas
macOS 11 o más nuevo (Apple Silicon e Intel), Linux x86_64 con bandeja (en GNOME hace falta la extensión AppIndicator) y Windows 10/11. Hecha con Tauri 2 (Rust); el código está en apps/desktop.
Chat
Talk to a local Ollama model that already knows your profile and memory, and can look things up and edit your vault with the same tools your agents have.
Context
The system prompt includes a fixed guide to how brain works (so the chat can tell you where things are in the app; you can read it in Settings → System prompt), profile.md, all your active memories (up to ~12k characters), BRAIN.md, the fragments of past chats most similar to your question, and your own instructions from Settings.
Tools
The chat gets exactly the tools your agents get, including your connections'. Every call is listed under the answer; expand it to see the arguments and the result. Up to 6 rounds of tool calls per answer.
How it works through a request
The system prompt starts with a short set of working rules: understand what result you want before acting, ask at most one short question and only when a missing detail would change the result, use just the tools it needs (read the file directly instead of listing everything), never claim a change the tool didn't confirm, and answer with the result first, ending with a line about what changed and where. Two guards in the loop keep it from going in circles: the same tool call with the same arguments isn't run again in one answer, and if it runs out of rounds (or used tools and said nothing) it gets one last round without tools to answer with what it found, instead of stopping mid-way.
HTML in answers
Answers are Markdown and can also include HTML when it reads better: tables with merged cells, <details> for long parts, <mark>, <kbd>, inline colors or a simple <svg> diagram. It's sanitized before it's shown: no scripts, forms, iframes or <style>; images only from brain itself, so a saved page with hidden instructions can't make the model leak data in an image URL; and no styles that load URLs or cover the interface.
HTML preview
When the model writes an html (or svg) code block, you see it rendered as soon as the answer is done. The Preview / Code toggle in its top-right corner switches to the source, and Copy copies it. The preview runs in an isolated frame (no access to the chat, the dashboard or brain's API) with no scripts and nothing loaded from the internet; if the HTML has JavaScript, Run scripts runs it in that same frame and lets it load scripts, styles and images from the web (it still can't send requests). Drag the bottom-right corner to make it taller.
Models that can't take native tools (common with GGUF models pulled from Hugging Face, which fail with "Unable to generate parser for this template") switch to text mode: the tools are described in the prompt and the model asks for them with <tool_call>{…}</tool_call>. The mode is remembered per model while the dashboard runs.
History and floating window
Chats are stored in Chroma (collection chats) with embeddings, so past conversations feed the context of new ones. Without Chroma the chat works but isn't saved. Float opens the chat in an always-on-top window (Document Picture-in-Picture in Chrome, Edge and Arc; a regular pop-up elsewhere).
Choosing a model
The selector lists your installed chat models with their size and context window. Without any, click Download llama3.2. Small models sometimes don't follow the tool format; larger ones (llama3.2, qwen2.5, mistral) do better.
You pick the model in a new chat, before the first message. From then on it stays fixed for that chat (the selector becomes a tag with a lock) and reopening the chat uses it again. To use another model, start a new chat. If the chat's model was uninstalled, the selector comes back.
The + button
At the start of the message box, + opens a menu with the commands and your skills (filterable; clicking one writes /name in the box, same as typing /) and a Search Lumina switch. See OpenCue, Lumina and WorkStudio.
OpenCue agents
If you have OpenCue, its agents are listed in the model selector as OpenCue · name. They answer with your profile and memory as context and run in OpenCue with their own tools.
Context window
The circle to the left of the send button fills up as the conversation uses the model's context window, and turns red past 90% (the model starts forgetting the beginning: better start a new chat). Hover it to see the tokens. By default brain asks Ollama for the model's full window capped at 16,384 tokens, so it doesn't eat all your RAM; a model with a smaller window uses its own. Change it in Settings → Context. When it fills up, /compact frees it without leaving the chat, and at 85% the chat compacts by itself before answering.
Compacting
/compact works like Claude Code's: the model writes a summary with fixed sections — main request, every instruction you gave, decisions, exact data (names, numbers, paths), changes made with tools, pending work and what it was doing right before — and from then on gets that summary instead of the old messages, which stay visible. Add instructions after the command to steer it (/compact focus on the dates). A previous summary is always carried over, and a conversation that doesn't fit in the window is summarized in parts. When a chat reaches 85% of the window, it compacts by itself before answering (BRAIN_AUTO_COMPACT, 0 turns it off). Right after compacting, brain preloads the new context in Ollama while you read the summary, so the next answer doesn't have to process the whole profile and memory again; the context circle shows the new size.
Title
A chat takes its title from the first message. The pencil next to the title renames it (Enter saves, Esc cancels).
Commands
Type / in the message box to see the commands, with a short description in your language. Arrows move, Enter or Tab picks.
| Command | What it does |
|---|---|
/organize | Organizes the vault and its graph with a built-in skill (adapted from file-organizer). It looks at a snapshot of the vault (loose notes, notes with no links, no description, repeated or near-duplicate tags, similar names), asks you a few questions, proposes a plan and only changes what you approve, with move_file, set_frontmatter and friends. It never touches BRAIN.md, profile.md, memory/ or knowledge/sources/. The chat stays in this mode, so you can just answer its questions. Add text after the command to focus it: /organize only projects/. |
/add-mcp | Sets up a connector from a URL or instructions and proposes it; you add it with one click. See Connections. |
/factcheck | Verifies what you write after it with Fact check and shows each claim's verdict with its sources, without changing it. |
/compact | Compacts the session: the model summarizes the conversation so far (requests, decisions, files it changed, what's pending) and from then on gets that summary instead of the old messages, which stay visible in the chat. The context circle empties and you keep going in the same chat. |
/reflect | Brings Reflect's suggestions into the chat (duplicates, contradictions, notes without entities) and applies only the ones you confirm. |
/new | Starts a new chat. |
Your skills
Below brain's commands, under Your skills and with a skill tag, the menu lists the skills saved in skills/ of your vault, usually written by your agents with distill_skill + write_file. Type to filter. /name loads that skill's instructions into the chat and keeps it in that mode; add text after it to apply it right away: /write-emails ask Juan for the report. A skill named like one of brain's commands stays hidden behind the command.
Chat
Hablá con un modelo local de Ollama que ya conoce tu perfil y tu memoria, y que puede consultar y editar tu vault con las mismas tools que tus agentes.
Contexto
El system prompt incluye una guía fija de cómo funciona brain (así el chat te puede decir dónde está cada cosa en la app; la podés leer en Ajustes → System prompt), profile.md, todas tus memorias activas (hasta ~12k caracteres), BRAIN.md, los fragmentos de chats anteriores más parecidos a tu pregunta y tus instrucciones de Ajustes.
Tools
El chat recibe exactamente las tools de tus agentes, incluidas las de tus conexiones. Cada llamada aparece debajo de la respuesta; desplegala para ver los argumentos y el resultado. Hasta 6 vueltas de tools por respuesta.
Cómo resuelve un pedido
El system prompt empieza con unas reglas de trabajo cortas: entender qué resultado querés antes de actuar, preguntar como mucho una cosa y solo si falta un dato que cambia el resultado, usar las tools justas (leer el archivo directo en vez de listar todo), no decir que cambió algo si la tool no lo confirmó, y responder con el resultado primero y una línea final de qué cambió y dónde. Dos controles en el loop evitan que dé vueltas: la misma tool con los mismos argumentos no se vuelve a ejecutar en una respuesta, y si se le acaban las vueltas (o usó tools y no dijo nada) recibe una última vuelta sin tools para contestar con lo que encontró, en vez de cortarse.
HTML en las respuestas
Las respuestas son Markdown y además pueden traer HTML cuando se entiende mejor: tablas con celdas combinadas, <details> para lo largo, <mark>, <kbd>, colores o un diagrama simple en <svg>. Se sanitiza antes de mostrarse: sin scripts, formularios, iframes ni <style>; imágenes solo del propio brain, así una página guardada con instrucciones escondidas no puede hacer que el modelo filtre datos en la URL de una imagen; y sin estilos que carguen URLs o tapen la interfaz.
Vista previa de HTML
Cuando el modelo escribe un bloque de código html (o svg), lo ves renderizado apenas termina la respuesta. El selector Vista previa / Código de arriba a la derecha pasa al código fuente, y Copiar lo copia. La vista previa corre en un marco aislado (sin acceso al chat, al dashboard ni a la API de brain), sin scripts y sin cargar nada de internet; si el HTML trae JavaScript, Ejecutar scripts lo corre en ese mismo marco y le deja cargar scripts, estilos e imágenes de la web (igual no puede hacer pedidos). Arrastrá la esquina de abajo a la derecha para agrandarla.
Los modelos que no aceptan tools nativas (típico de GGUF bajados de Hugging Face, que fallan con "Unable to generate parser for this template") pasan al modo texto: las tools van descritas en el prompt y el modelo las pide con <tool_call>{…}</tool_call>. El modo se recuerda por modelo mientras corre el dashboard.
Historial y ventana flotante
Los chats se guardan en Chroma (colección chats) con embeddings, así las conversaciones anteriores alimentan el contexto de las nuevas. Sin Chroma el chat funciona pero no se guarda. Ventana flotante abre el chat en una ventana siempre visible (Document Picture-in-Picture en Chrome, Edge y Arc; una ventana emergente común en el resto).
Elegir un modelo
El selector lista tus modelos de chat instalados con su tamaño y su ventana de contexto. Si no hay ninguno, tocá Descargar llama3.2. Los modelos chicos a veces no siguen el formato de tools; los más grandes (llama3.2, qwen2.5, mistral) andan mejor.
El modelo se elige en un chat nuevo, antes del primer mensaje. Desde ahí queda fijo para ese chat (el selector pasa a ser una etiqueta con candado) y al reabrirlo se usa el mismo. Para usar otro modelo, empezá un chat nuevo. Si desinstalaste el modelo del chat, vuelve el selector.
El botón +
Al principio de la caja de mensaje, + abre un menú con los comandos y tus skills (con filtro; al tocar uno escribe /nombre en la caja, igual que al escribir /) y un interruptor Buscar en Lumina. Ver OpenCue, Lumina y WorkStudio.
Agentes de OpenCue
Si tenés OpenCue, sus agentes aparecen en el selector de modelo como OpenCue · nombre. Responden con tu perfil y tu memoria como contexto y corren en OpenCue con sus propias tools.
Ventana de contexto
El círculo a la izquierda del botón de enviar se va llenando a medida que la conversación ocupa la ventana de contexto del modelo, y se pone rojo pasado el 90% (el modelo empieza a olvidar lo primero: conviene un chat nuevo). Pasá el mouse para ver los tokens. Por defecto brain le pide a Ollama la ventana completa del modelo con un tope de 16.384 tokens, para no comerse toda la RAM; un modelo con una ventana más chica usa la suya. Se cambia en Ajustes → Contexto. Cuando se llena, /compact la libera sin salir del chat, y al 85% el chat se compacta solo antes de responder.
Compactar
/compact funciona como el de Claude Code: el modelo escribe un resumen con secciones fijas —pedido principal, cada instrucción que diste, decisiones, datos exactos (nombres, números, paths), cambios hechos con tools, pendientes y en qué estaba justo antes— y desde ahí recibe ese resumen en vez de los mensajes viejos, que siguen visibles. Podés sumar instrucciones después del comando (/compact enfocate en las fechas). Un resumen anterior siempre se conserva, y una conversación que no entra en la ventana se resume por partes. Cuando un chat llega al 85% de la ventana, se compacta solo antes de responder (BRAIN_AUTO_COMPACT; 0 lo apaga). Apenas compacta, brain precarga el contexto nuevo en Ollama mientras leés el resumen, así la respuesta siguiente no tiene que volver a procesar todo el perfil y la memoria; el círculo de contexto muestra el tamaño nuevo.
Título
Un chat toma el título del primer mensaje. El lápiz al lado del título lo cambia (Enter guarda, Esc cancela).
Comandos
Escribí / en la caja de mensaje para ver los comandos, con una descripción corta en tu idioma. Flechas para moverte, Enter o Tab para elegir.
| Comando | Qué hace |
|---|---|
/organize | Ordena el vault y su grafo con una skill integrada (adaptada de file-organizer). Mira un panorama del vault (notas sueltas, sin conexiones, sin descripción, tags repetidos o con variantes, nombres parecidos), te hace unas preguntas, propone un plan y cambia solo lo que apruebes, con move_file, set_frontmatter y compañía. Nunca toca BRAIN.md, profile.md, memory/ ni knowledge/sources/. El chat queda en ese modo, así que alcanza con responderle. Podés sumar texto para enfocarlo: /organize solo projects/. |
/add-mcp | Arma un conector a partir de una URL o instrucciones y lo propone; lo agregás con un click. Ver Conexiones. |
/factcheck | Verifica lo que escribas después con Fact check y muestra el veredicto de cada afirmación con sus fuentes, sin cambiarlo. |
/compact | Compacta la sesión: el modelo resume lo hablado (pedidos, decisiones, archivos que cambió, lo pendiente) y desde ahí recibe ese resumen en vez de los mensajes viejos, que siguen visibles en el chat. El círculo de contexto se vacía y seguís en el mismo chat. |
/reflect | Trae al chat las sugerencias de Reflect (duplicados, contradicciones, notas sin entidades) y aplica solo las que confirmes. |
/new | Empieza un chat nuevo. |
Tus skills
Debajo de los comandos de brain, en Tus skills y con la etiqueta skill, el menú lista los skills guardados en skills/ de tu vault, que suelen escribir tus agentes con distill_skill + write_file. Escribí para filtrar. /nombre carga las instrucciones de ese skill en el chat y lo deja en ese modo; sumá texto después para aplicarlo de una: /escribir-mails pedile a Juan el informe. Un skill que se llame igual que un comando de brain queda tapado por el comando.
Connecting agents
Each agent keeps its list of MCP servers in its own file. Connect adds brain's entry without touching anything else, after saving a backup (<file>.bak-brain).
Supported agents
| Agent | Config | Notes |
|---|---|---|
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | Claude rewrites this file when it quits, so it's edited with the app closed; the dashboard offers to quit, connect and reopen it. |
| ChatGPT (desktop) | ~/.codex/config.toml | Works in Codex and ChatGPT Work modes; regular chat doesn't use local servers. Then Settings → MCP servers → Restart. |
| Claude Code | claude mcp add -s user | Available in all your projects. |
| Codex CLI | ~/.codex/config.toml | Same file as ChatGPT. |
| Cursor | ~/.cursor/mcp.json | |
| VS Code (Copilot) | ~/Library/Application Support/Code/User/mcp.json | If the file has comments (JSONC) it isn't rewritten; you get the snippet to paste. |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | |
| Gemini CLI | ~/.gemini/settings.json | |
| OpenMausBot | ~/.openmausbot/config.json | It reads its MCP servers when it opens, so it's edited with the app closed; the dashboard offers to quit, connect and reopen it. |
| DeepSeek Harness | ~/.dsh/cordis.patch.yml | The user patch layer that the desktop app and the dsh CLI share. brain adds its own block (an @deepseek-ai/dsh-mcp-client row with transport: stdio) and removes only that block; dsh reloads it without restarting. Its tools show up as mcp__brain__…. |
| Manus Studio | its own form | Manus adds local servers with its Run a command form and has no config file brain can edit: copy the command and arguments from Any other MCP client on the same page; its card switches to Detected once Manus uses brain. Manus on the web can use remote access. |
Paths are the macOS ones; on Windows they're under %APPDATA% and on Linux under ~/.config, and the dashboard shows the right one for your system. All local agents launch the same command with absolute paths, so they work from any folder:
/Users/you/.local/bin/uv run --directory /Users/you/.brain python server.py
Apps with an "Add MCP server" form
Choose Run a command. If the app only accepts a URL (or runs in the cloud), use remote access: pointing an app at the dashboard's address returns 403.
| Field | Value |
|---|---|
| Name | brain |
| Command | absolute path to uv (which uv) |
| Arguments (one per line) | run, --directory, /Users/you/.brain, python, server.py |
The Connect agent tab shows these values filled in for your machine, with copy buttons.
My connections
Lists the agents brain configured, plus every app that has used brain: brain records the client name each app sends in the MCP handshake (data/clients.json), so apps you set up with a form appear the first time they use it. You can also note an app by hand.
Conectar agentes
Cada agente guarda su lista de servers MCP en su propio archivo. Conectar agrega la entrada de brain sin tocar nada más, después de guardar un backup (<archivo>.bak-brain).
Agentes soportados
| Agente | Config | Notas |
|---|---|---|
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | Claude reescribe este archivo al cerrarse, así que se edita con la app cerrada; el dashboard ofrece cerrarla, conectar y volver a abrirla. |
| ChatGPT (escritorio) | ~/.codex/config.toml | Funciona en los modos Codex y ChatGPT Work; el chat común no usa servers locales. Después: Settings → MCP servers → Restart. |
| Claude Code | claude mcp add -s user | Disponible en todos tus proyectos. |
| Codex CLI | ~/.codex/config.toml | El mismo archivo que ChatGPT. |
| Cursor | ~/.cursor/mcp.json | |
| VS Code (Copilot) | ~/Library/Application Support/Code/User/mcp.json | Si el archivo tiene comentarios (JSONC) no se reescribe; te da el fragmento para pegar. |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | |
| Gemini CLI | ~/.gemini/settings.json | |
| OpenMausBot | ~/.openmausbot/config.json | Lee sus servers MCP al abrirse, así que se edita con la app cerrada; el dashboard ofrece cerrarla, conectar y volver a abrirla. |
| DeepSeek Harness | ~/.dsh/cordis.patch.yml | La capa de parches del usuario que comparten la app de escritorio y el CLI dsh. brain agrega un bloque propio (una fila @deepseek-ai/dsh-mcp-client con transport: stdio) y al desconectar saca solo ese bloque; dsh lo recarga sin reiniciar. Sus tools aparecen como mcp__brain__…. |
| Manus Studio | su formulario | Manus agrega servers locales con su formulario Run a command y no tiene un archivo de config que brain pueda editar: copiá el comando y los argumentos de Cualquier otro cliente MCP, en la misma página; su tarjeta pasa a Detectado cuando Manus usa brain. Manus en la web puede usar el acceso remoto. |
Los paths son los de macOS; en Windows están en %APPDATA% y en Linux en ~/.config, y el dashboard muestra el de tu sistema. Todos los agentes locales lanzan el mismo comando con paths absolutos, así funcionan desde cualquier carpeta:
/Users/vos/.local/bin/uv run --directory /Users/vos/.brain python server.py
Apps con formulario "Add MCP server"
Elegí Run a command. Si la app solo acepta una URL (o corre en la nube), usá el acceso remoto: apuntar una app a la dirección del dashboard devuelve 403.
| Campo | Valor |
|---|---|
| Nombre | brain |
| Comando | path absoluto de uv (which uv) |
| Argumentos (uno por línea) | run, --directory, /Users/vos/.brain, python, server.py |
La pestaña Conectar agente muestra estos valores completos para tu máquina, con botones de copiar.
Mis conexiones
Lista los agentes que configuró brain, más cada app que usó brain: brain anota el nombre de cliente que manda cada app en el handshake MCP (data/clients.json), así las apps que agregaste con un formulario aparecen la primera vez que lo usan. También podés anotar una app a mano.
Remote access by URL
Publishes brain's MCP server at an internet URL through a Cloudflare tunnel, so agents in the cloud or on another computer can use your memory. Off by default.
Turning it on
In Connect agent → By URL, flip the Remote access by URL switch. The first time, Install cloudflared downloads Cloudflare's program from its official GitHub release into data/bin/ and checks it against the SHA256 Cloudflare publishes (if you already have cloudflared installed with brew, winget or apt, brain uses that one). brain then starts two processes:
server.py --http: the same MCP server your local agents use, over streamable HTTP, listening only on127.0.0.1:8770.cloudflared: an outbound tunnel that publishes that port. No ports are opened on your router.
When the tunnel is ready the card shows the URL to copy. It stays on across restarts until you turn it off; it only works while the dashboard is open.
The URL and its token
The URL looks like https://…/<token>/mcp. Without the token every request gets a 404. Apps that prefer a header can use https://…/mcp with Authorization: Bearer <token> (the card shows both). Treat the URL like a password:
- Test the URL (shown while it is published) makes the same two requests a cloud agent makes, through the tunnel, and says where it breaks: unresolved address, tunnel down, wrong token or a server that isn't brain. The server answers without sessions or event streams (
GETgets a405), which is what Cloudflare's free quick tunnels support, and a trailing slash in the URL (…/mcp/) works. - Generate a new URL changes the token: the old URL stops working right away, without restarting anything.
- Read-only leaves agents using the URL with the tools that read and search (
read_file,search_knowledge,list_vault…); writing, deleting and your connections' tools are hidden and refused. - Through the URL,
save_urlandread_urlonly fetch public addresses, never your computer or local network.
Quick or fixed URL
Without a Cloudflare account the tunnel is a quick tunnel: a *.trycloudflare.com address that changes every time it starts, so you have to paste it again in each agent. For a fixed address, create a tunnel in your Cloudflare account (Zero Trust → Networks → Tunnels → Create a tunnel), point its public hostname to http://localhost:8770, and paste the hostname and the tunnel token under Fixed URL with your Cloudflare account. The token is passed to cloudflared as an environment variable and stored in data/remote.json (600).
When the computer sleeps
The URL stays up until you turn remote access off or close brain. While it's on, brain keeps the computer from going to sleep by itself (caffeinate on macOS, systemd-inhibit on Linux, SetThreadExecutionState on Windows); the screen can still turn off. Untick Keep the computer from sleeping to allow it. If it sleeps anyway (closing a laptop lid), a watchdog checks the tunnel when it wakes up: cloudflared usually reconnects with the same URL (the card says Reconnecting… meanwhile); if it can't within about a minute, or the tunnel no longer exists on Cloudflare's side, brain reopens it, and also restarts the MCP server or cloudflared if either closed. A quick tunnel then gets a new URL and the card tells you to paste it again; a named tunnel keeps its URL, so use one if your agents must always find brain. Reconnect does the same by hand, and Generate a new URL also reopens the tunnel if it was down.
Which agents
Any MCP client that connects to a URL with streamable HTTP: Manus on the web (Settings → Connectors → Custom MCP), Claude.ai (Settings → Connectors → Add custom connector), ChatGPT in developer mode, or a local agent on another computer. They show up in My connections once they use brain.
Acceso remoto por URL
Publica el server MCP de brain en una URL de internet con un túnel de Cloudflare, así agentes en la nube o en otra computadora pueden usar tu memoria. Viene apagado.
Prenderlo
En Conectar agente → Por URL, prendé el switch de Acceso remoto por URL. La primera vez, Instalar cloudflared baja el programa de Cloudflare de su release oficial en GitHub a data/bin/ y lo verifica con el SHA256 que publica Cloudflare (si ya tenés cloudflared instalado con brew, winget o apt, brain usa ese). Después brain prende dos procesos:
server.py --http: el mismo server MCP que usan tus agentes locales, por streamable HTTP, escuchando solo en127.0.0.1:8770.cloudflared: un túnel de salida que publica ese puerto. No se abren puertos en tu router.
Cuando el túnel está listo, la tarjeta muestra la URL para copiar. Queda prendido entre reinicios hasta que lo apagues; solo funciona mientras el dashboard esté abierto.
La URL y su token
La URL tiene la forma https://…/<token>/mcp. Sin el token, todo pedido recibe un 404. Las apps que prefieren un header pueden usar https://…/mcp con Authorization: Bearer <token> (la tarjeta muestra las dos). Tratá la URL como una contraseña:
- Probar la URL (aparece mientras está publicada) hace desde el túnel los mismos dos pedidos que hace un agente en la nube y dice dónde se corta: dirección que no resuelve, túnel caído, token que no coincide o un server que no es brain. El server contesta sin sesiones ni streams de eventos (el
GETda405), que es lo que soportan los túneles rápidos gratis de Cloudflare, y una barra final en la URL (…/mcp/) también anda. - Generar otra URL cambia el token: la URL vieja deja de andar en el acto, sin reiniciar nada.
- Solo lectura deja a los agentes por URL con las tools que leen y buscan (
read_file,search_knowledge,list_vault…); escribir, borrar y las tools de tus conexiones quedan ocultas y se rechazan. - Por la URL,
save_urlyread_urlsolo leen direcciones públicas, nunca tu computadora ni tu red local.
URL rápida o fija
Sin cuenta de Cloudflare el túnel es un quick tunnel: una dirección *.trycloudflare.com que cambia cada vez que se prende, así que hay que volver a pegarla en cada agente. Para una dirección fija, creá un túnel en tu cuenta de Cloudflare (Zero Trust → Networks → Tunnels → Create a tunnel), apuntá su hostname público a http://localhost:8770 y pegá el hostname y el token del túnel en URL fija con tu cuenta de Cloudflare. El token le llega a cloudflared por una variable de entorno y se guarda en data/remote.json (600).
Cuando la compu se duerme
La URL sigue viva hasta que apagás el acceso remoto o cerrás brain. Mientras está prendido, brain evita que la compu se duerma sola (caffeinate en macOS, systemd-inhibit en Linux, SetThreadExecutionState en Windows); la pantalla se puede apagar igual. Destildá Que la compu no se duerma sola para permitirlo. Si se duerme igual (al cerrar la tapa), un watchdog revisa el túnel al despertar: cloudflared casi siempre se reconecta con la misma URL (mientras tanto la tarjeta dice Reconectando…); si en un minuto no puede, o el túnel ya no existe del lado de Cloudflare, brain lo reabre, y también vuelve a prender el server MCP o cloudflared si alguno se cerró. Un túnel rápido recibe entonces una URL nueva y la tarjeta te avisa que la pegues de nuevo; uno con nombre conserva su URL, así que usá uno si tus agentes tienen que encontrar a brain siempre. Reconectar hace lo mismo a mano, y Generar otra URL también reabre el túnel si estaba caído.
Qué agentes
Cualquier cliente MCP que se conecte a una URL con streamable HTTP: Manus en la web (Settings → Connectors → Custom MCP), Claude.ai (Settings → Connectors → Add custom connector), ChatGPT en modo desarrollador, o un agente local en otra computadora. Aparecen en Mis conexiones apenas usan brain.
Prompts for your agent
Ready-to-paste instructions so any AI uses brain well: what to read, what to cite and what not to touch. They are also in the dashboard, in the Prompts view, with a copy button in English and Spanish.
How to use them
- Connect your agent (Connecting agents): cloud agents by URL, the ones on your computer with the one-click button.
- Paste Project instructions into the agent's project instructions (in Cursor or Claude Code, the rules file).
- Replace
<project>with the name of your folder inprojects/. - Try an everyday prompt and check in the agent which tool it called: each prompt says which one it should use.
- To have the agent write its own rules, paste Let the agent configure itself as the first message.
Without brain tools (an AI that isn't connected), use When the AI has no brain tools and paste the note's content. If you ask an agent directly to write BRAIN.md, FORMAT.md or FACT-CHECK.md it may try, and brain stops it: only you edit them, from the graph.
Set up an agent with brain
Paste them into the project instructions (Claude, ChatGPT, Gemini, Mistral or Cursor) and replace <project> with the name of your folder in projects/.
Project instructions
Tool: list_vault, read_file · Tested in: Mistral, Manus.
Use brain as the main context source for this project. 1. At the start of a conversation, list the notes in projects/<project>/ with list_vault and read the main note projects/<project>.md. 2. Before answering about the project, read the relevant notes with read_file. If the information is not there, say so. Do not invent facts. 3. When you use something from brain, cite the source note path. 4. Do not save anything to brain unless I ask. If I ask you to save something, show me the exact text first. 5. Never try to write BRAIN.md, FORMAT.md, FACT-CHECK.md or the base folders. If a change is needed there, ask me. 6. If brain does not have enough and you need web sources, follow FACT-CHECK.md before answering.
Coding agents (Claude Code, Cursor, Codex)
Tool: read_file · Not tried in a client yet.
Before changing code in <project>, read projects/<project>/arquitectura.md and projects/<project>/decisiones.md through brain. Respect the decisions you find there. If a task contradicts a decision, stop and ask me. When you finish, propose the entry for the repo's CHANGES.md; do not write anything to brain unless I ask.
When the AI has no brain tools
Tool: — · Tested in: Manus.
I can't reach brain from this conversation. I'm pasting the content of the note <name>. Work only with that text, say which part you use in each answer, and tell me what information is missing.
Topic kickoff (once per chat)
Tool: list_vault, read_file · Tested in: Mistral.
Before answering, look up the context about <topic> in brain: list projects/ with list_vault, read the notes that cover it and give me three points with the source note of each. Then answer my question: <question>.
Let the agent configure itself
Tool: list_vault, read_file · Tested in: Manus.
Expected: The agent checks which tools it has, reads BRAIN.md and FORMAT.md, asks its questions in one batch, proposes up to 8 rules and waits for your OK before applying them.
I want you to configure how you will use brain with me, based on the tools you have. Do it in this order and do not answer my underlying question yet: 1. Check which brain tools you have available (for example list_vault, read_file, search_knowledge, add_memory, fact_check). If you see none, say so and ask me to paste the content of the note you need. 2. Read BRAIN.md and FORMAT.md to understand the vault structure. They are read-only for you. 3. Ask me only what is necessary, in a single batch: which project it is (the folder in projects/), what you will use it for (explain, decide, write or review code, research) and whether you should save things in brain or only read. 4. With my answers, write a summary of up to 8 lines with your working rules: what to read before answering, when to cite the source note, when to search the web, what not to touch. Show it to me and wait for my OK. 5. After the OK, apply the summary for the whole conversation. Fixed rules: before saving anything to brain, show me the exact text and wait for my OK. Never write BRAIN.md, FORMAT.md, FACT-CHECK.md or the base folders. If a tool fails, say which one and what you did instead; do not invent content. If you are a coding agent (Claude Code, Cursor, Codex), treat the decisions in projects/<project>/decisiones.md as constraints before proposing changes.
Everyday prompts
To use once the project is set up. Each one says which tool the AI should use, so you can check it did it right.
Explain a project
Tool: list_vault, read_file · Tested in: Mistral.
Expected: A list of notes, a read of the main note and five points, each with its path.
What is <project> according to brain? Answer in five points and cite the note for each one.
Find how something works
Tool: read_file · Tested in: Mistral.
Find in brain how <topic> works. Read the full note before answering and tell me which note it is in.
Project to-dos
Tool: read_file · Tested in: Mistral.
Read the to-do note of <project> and give me only what is not done yet, ordered by priority.
Decisions and their reasons
Tool: read_file · Tested in: Mistral.
Why did we decide <decision> in <project>? Find the reason in decisiones and quote the original text.
Save a fact about me
Tool: add_memory · Tested in: Mistral.
Expected: First the confirmation with the exact text; then add_memory, with supersede if it replaces a fact.
Save this fact about me in brain: <fact>. Before saving it, show me the exact text. If it replaces an earlier fact, pass the old one in supersede.
Add a to-do with permission
Tool: append_file · Tested in: Mistral.
Add this line at the end of projects/<project>/pendientes.md: - [ ] <task>. Show me the change and wait for my OK before writing.
Ask for a change in a core file (it should refuse)
Tool: append_file · Tested in: Mistral.
Expected: It should refuse, explain that the user edits BRAIN.md from the graph and return the exact text to paste.
I want to add <text> to BRAIN.md. Do it.
Check a fact
Tool: fact_check · Tested in: tool directa.
Check whether this claim still holds: <claim>. Look in brain first and, if needed, search the web. Show me the sources with their date and the verdict.
Save a web source and search it
Tool: save_url, search_knowledge · Tested in: Mistral.
Expected: It needs the embeddings model (nomic-embed-text) in Ollama. With a specific question the search finds the section, not just the front page.
Save this page in brain: <url>. Then search it for: <question>, and quote the passage.
Search the web
Tool: web_search, read_url · Not tried in a client yet.
Expected: A list of results with title, URL and date; then it reads the pages it picks and cites where each fact comes from.
Search the web for <topic> with web_search, pick the two or three most reliable results and read them with read_url. Answer citing the URL and date of each fact; if they disagree, say so.
What was tested
On 2026-10-25, with brain running on an Ubuntu VM and Mistral connected by URL (the project instructions, the topic kickoff and the everyday prompts), and Manus (the English instructions, the pasted-content prompt and Let the agent configure itself). The central-file guard held: when a request was direct (“do it”), the agent tried to write and brain refused. fact_check was run as a direct tool call: it returns the sources, but without a chat model in Ollama the verdict is “inconclusive”. Saving a page needs the nomic-embed-text model in Ollama. Still to try: HuggingChat, and what happens when a tool fails.
Prompts para tu agente
Instrucciones listas para pegar, para que cualquier IA use brain bien: qué leer, qué citar y qué no tocar. También están en el dashboard, en la vista Prompts, con botón para copiarlos en español e inglés.
Cómo usarlos
- Conectá tu agente (Conectar agentes): los de la nube por URL, los de tu compu con el botón de un clic.
- Pegá Instrucciones de proyecto en las instrucciones del proyecto del agente (en Cursor o Claude Code, el archivo de reglas).
- Reemplazá
<proyecto>por el nombre de tu carpeta enprojects/. - Probá un prompt de uso diario y mirá en el agente qué tool llamó: cada prompt dice cuál debería usar.
- Para que el agente arme sus propias reglas, pegá Que el agente se configure solo como primer mensaje.
Sin tools de brain (una IA sin conectar), usá Cuando la IA no tiene tools de brain y pegale el contenido de la nota. Si le pedís directo a un agente escribir BRAIN.md, FORMAT.md o FACT-CHECK.md, puede intentarlo y brain lo frena: los editás solo vos, desde el grafo.
Configurar un agente con brain
Pegalos en las instrucciones del proyecto (Claude, ChatGPT, Gemini, Mistral o Cursor) y reemplazá <proyecto> por el nombre de tu carpeta en projects/.
Instrucciones de proyecto
Tool: list_vault, read_file · Probado en: Mistral, Manus.
Usá brain como fuente principal de contexto para este proyecto. 1. Al empezar una conversación, listá las notas de projects/<proyecto>/ con list_vault y leé la nota principal projects/<proyecto>.md. 2. Antes de responder sobre el proyecto, leé las notas relevantes con read_file. Si no encontrás la información, decilo. No inventes datos. 3. Cuando uses algo de brain, indicá la ruta de la nota de origen. 4. No guardes nada en brain sin pedirmelo. Si te pido guardar algo, mostrame el texto exacto antes. 5. Nunca intentes escribir BRAIN.md, FORMAT.md, FACT-CHECK.md ni las carpetas base. Si hace falta un cambio ahí, pedimelo a mí. 6. Si brain no alcanza y hace falta buscar en internet, seguí FACT-CHECK.md antes de responder.
Agentes de código (Claude Code, Cursor, Codex)
Tool: read_file · Sin probar en un cliente.
Antes de cambiar código de <proyecto>, leé con brain projects/<proyecto>/arquitectura.md y projects/<proyecto>/decisiones.md. Respetá las decisiones que aparezcan. Si una tarea contradice una decisión, frenate y preguntame. Al terminar, proponé la entrada para CHANGES.md del repo; no escribas nada en brain sin pedirmelo.
Cuando la IA no tiene tools de brain
Tool: — · Probado en: Manus.
No tengo acceso a brain desde esta conversación. Te pego el contenido de la nota <nombre>. Trabajá solo con ese texto, indicá qué parte usás en cada respuesta y decime qué información te falta.
Arranque de tema (una vez por chat)
Tool: list_vault, read_file · Probado en: Mistral.
Antes de responder, buscá en brain el contexto sobre <tema>: listá projects/ con list_vault, leé las notas que lo traten y devolveme tres puntos con la nota de origen de cada uno. Después respondé mi pregunta: <pregunta>.
Que el agente se configure solo
Tool: list_vault, read_file · Probado en: Manus.
Se espera: El agente revisa qué tools tiene, lee BRAIN.md y FORMAT.md, hace sus preguntas en una sola tanda, propone hasta 8 reglas y espera tu OK antes de aplicarlas.
Quiero que configures cómo vas a usar brain conmigo, según las herramientas que tengas. Hacelo en este orden y no respondas todavía a mi pregunta de fondo: 1. Revisá qué herramientas de brain tenés disponibles (por ejemplo list_vault, read_file, search_knowledge, add_memory, fact_check). Si no ves ninguna, decilo y pedime que pegue el contenido de la nota que necesitás. 2. Leé BRAIN.md y FORMAT.md para entender la estructura del vault. Son de solo lectura para vos. 3. Preguntame solo lo necesario, en una sola tanda: qué proyecto es (la carpeta en projects/), para qué lo vas a usar (explicar, decidir, escribir o revisar código, investigar) y si querés que guardes cosas en brain o solo leas. 4. Con mis respuestas, escribí un resumen de hasta 8 líneas con tus reglas de trabajo: qué leer antes de responder, cuándo citar la nota de origen, cuándo buscar en la web, qué no tocar. Mostrámelo y esperá mi OK. 5. Después del OK, aplicá el resumen en toda la conversación. Reglas fijas: antes de guardar algo en brain, mostrame el texto exacto y esperá mi OK. Nunca escribas BRAIN.md, FORMAT.md, FACT-CHECK.md ni las carpetas base. Si una tool falla, decí cuál y qué hiciste en su lugar; no inventes contenido. Si sos un agente de código (Claude Code, Cursor, Codex), tomá las decisiones de projects/<proyecto>/decisiones.md como restricciones antes de proponer cambios.
Prompts de uso diario
Para usar una vez configurado el proyecto. Cada uno dice qué tool debería usar la IA, así podés comprobar si lo hizo bien.
Explicar un proyecto
Tool: list_vault, read_file · Probado en: Mistral.
Se espera: Lista de notas, lectura de la nota principal y cinco puntos, cada uno con su ruta.
¿Qué es <proyecto> según brain? Respondé en cinco puntos y citá la nota de cada punto.
Buscar cómo funciona algo
Tool: read_file · Probado en: Mistral.
Buscá en brain cómo funciona <tema>. Leé la nota completa antes de responder y decime en qué nota está.
Pendientes del proyecto
Tool: read_file · Probado en: Mistral.
Leé la nota de pendientes de <proyecto> y devolveme solo lo que todavía no está hecho, ordenado por prioridad.
Decisiones y sus motivos
Tool: read_file · Probado en: Mistral.
¿Por qué decidimos <decisión> en <proyecto>? Buscá el motivo en decisiones y citá el texto original.
Guardar un dato sobre mí
Tool: add_memory · Probado en: Mistral.
Se espera: Primero la confirmación con el texto exacto; después add_memory, con supersede si reemplaza un dato.
Guardá en brain este dato sobre mí: <dato>. Antes de guardarlo, mostrame el texto exacto. Si reemplaza un dato anterior, pasá el viejo en supersede.
Agregar un pendiente con permiso
Tool: append_file · Probado en: Mistral.
Agregá al final de projects/<proyecto>/pendientes.md esta línea: - [ ] <tarea>. Mostrame el cambio y esperá mi OK antes de escribir.
Pedir un cambio en un archivo central (debe negarse)
Tool: append_file · Probado en: Mistral.
Se espera: Que se niegue, explique que BRAIN.md lo edita el usuario desde el grafo y devuelva el texto exacto para pegar.
Quiero agregar <texto> a BRAIN.md. Hacelo.
Verificar un dato
Tool: fact_check · Probado en: tool directa.
Verificá si esta afirmación sigue vigente: <afirmación>. Primero mirá en brain y, si hace falta, buscá en la web. Mostrame las fuentes con su fecha y el veredicto.
Guardar una fuente web y buscar en ella
Tool: save_url, search_knowledge · Probado en: Mistral.
Se espera: Necesita el modelo de embeddings (nomic-embed-text) en Ollama. Con una pregunta específica la búsqueda encuentra la sección, no solo la portada.
Guardá en brain esta página: <url>. Después buscá en ella: <pregunta>, y citá el fragmento.
Buscar en internet
Tool: web_search, read_url · Sin probar en un cliente.
Se espera: Una lista de resultados con título, URL y fecha; después lee las páginas que elija y cita de dónde sale cada dato.
Buscá en internet <tema> con web_search, elegí los dos o tres resultados más confiables y leelos con read_url. Respondé citando la URL y la fecha de cada dato; si no coinciden, decilo.
Qué se probó
El 2026-10-25, con brain corriendo en una VM Ubuntu y Mistral conectado por URL (instrucciones de proyecto, arranque de tema y los prompts de uso diario), y con Manus (las instrucciones en inglés, el prompt con contenido pegado y Que el agente se configure solo). La guarda de los archivos centrales funcionó: ante un pedido directo («hacelo») el agente intentó escribir y brain lo rechazó. fact_check se corrió como llamada directa a la tool: trae las fuentes, pero sin un modelo de chat en Ollama el veredicto sale «no concluyente». Guardar una página necesita el modelo nomic-embed-text en Ollama. Falta probar HuggingChat y qué pasa cuando una tool falla.
Fact check
Verify claims with a visible, repeatable process: brain searches your memory first and, only if that's not enough, the web. It shows the evidence and its limits; it doesn't promise the truth.
How a check runs
- Claims. The local chat model splits the text into checkable claims (type, risk, sub-claims) and says which ones aren't checkable: opinions, predictions, things too vague.
- brain first. Each claim is searched with the hybrid search. Old notes count as context, not confirmation.
- Web only if needed. If nothing relevant is saved, it's old, your notes disagree, there's no primary source or it's a current topic, it searches the web (if you allow it) and says so: "I didn't find enough evidence in your local memory: I consulted external sources." It runs a neutral query, one for evidence, one for counter-evidence and one for the primary source.
- Read, don't skim. Every page is opened and read in full; a page that can't be opened stays as not fully inspected and doesn't count. Each source is typed (official, academic, professional fact-checker, news, reference, social/forums/blogs, other web) by what it is, never by trusting
.govor.orgalone. - Independence. Pages from the same site, or that copy the same text, count as one line of evidence.
- Compare. The model says whether each source supports, contradicts, supports with limits or doesn't answer, and must quote the exact sentence. If the quote isn't in the page, the source doesn't count.
- Verdict by rules, not a percentage: Supported, Likely supported, Mixed, Inconclusive, Likely false, False or Not verifiable. Never "supported" with a single secondary source; conflicting evidence is shown as a conflict, not averaged.
The report shows each claim, its verdict and why, the sources for and against (type, date, author, quote), what came from brain and what from the web, and the limitations. Actions: copy the report (Markdown), open sources, check again, Save to brain (a separate click; nothing is saved on its own) and Don't use this domain. The last 30 reports are kept in data/factchecks.json.
FACT-CHECK.md
The same method, written for any AI, lives in FACT-CHECK.md at the root of the vault (it hangs from BRAIN.md, next to FORMAT.md): brain first; when to search the web (nothing saved, old, contradictory, or a decision that matters) and never with your personal data in the query; neutral, evidence, counter-evidence and primary-source queries; which sources count and that copies are one line of evidence; a real quote for every claim; the verdict words and their rules; and how to answer without saving anything you didn't ask for. Its Preferences block is rewritten whenever you change them here. Agents are told to read it in the server's instructions, in fact_check and when search_knowledge finds nothing; the chat gets a short reminder in every answer and the whole guide with /factcheck or automatic checking on. Only you can edit it (from the graph).
Preferences
Set once in the view, applied to every new check (and to the chat). Basic: level (Quick, Standard — recommended —, Thorough, Custom), freshness (by topic, 24 hours, 30 days, a year, no limit or custom dates), require a primary source, search for counter-evidence. Advanced: minimum independent sources and maximum to read, which kinds of claims to check, always checking health, law, finance and safety with extra rigor, countries and languages, foreign sources, how much to trust each source type, search engine, blocked domains, and whether the chat may check facts on its own. Restore recommended values puts the defaults back.
Search engine
| Engine | Needs |
|---|---|
| DuckDuckGo (default) | Nothing. |
| SearXNG | The URL of your instance, with JSON output enabled. |
| Brave Search API | An API key. It's stored in data/factcheck.json (600) and never returned by the API. |
| One of your Connections | A search tool you already connected to brain (OpenSEO's get_serp_results, a Composio search tool, Tavily, Exa, Brave's MCP…). Pick it in the list and add fixed arguments as JSON if it needs them (e.g. {"projectId": "…"}). The query goes in the right field, the URLs are read from the result, and nothing it returns is saved to your brain. |
From the chat and agents
/factcheck <text> runs it from the chat, and agents have the fact_check tool, which always applies your preferences. With Let the chat and all your agents check facts that aren't in brain (off by default), every agent gets the instruction: brain's chat in its system prompt, and Claude, ChatGPT and any MCP client in the server instructions and in search_knowledge itself, which suggests fact_check when it finds nothing (or when what it found may not answer). Agents read the server instructions when they connect, so reopen them after turning it on.
For health, law, finance or safety the report reminds you it's informational and doesn't replace a professional. Fact check needs a chat model in Ollama to split claims and compare evidence; without one it says so.
Fact check
Verificá afirmaciones con un proceso visible y repetible: brain busca primero en tu memoria y, solo si no alcanza, en internet. Muestra la evidencia y sus límites; no promete la verdad.
Cómo se verifica
- Afirmaciones. El modelo de chat local separa el texto en afirmaciones verificables (tipo, riesgo, partes) y dice cuáles no se pueden verificar: opiniones, predicciones, cosas demasiado vagas.
- Primero brain. Cada afirmación se busca con la búsqueda híbrida. Las notas viejas cuentan como contexto, no como confirmación.
- Internet solo si hace falta. Si no hay nada guardado, es viejo, tus notas se contradicen, falta una fuente primaria o es un tema actual, busca en internet (si lo permitís) y lo avisa: «No encontré evidencia suficiente en tu memoria local: consulté fuentes externas.» Hace una búsqueda neutral, una de evidencia, una de evidencia en contra y una de la fuente primaria.
- Leer, no hojear. Cada página se abre y se lee entera; si no se puede abrir, queda como no inspeccionada completamente y no cuenta. Cada fuente se clasifica (oficial, académica, verificador profesional, periodística, referencia, redes/foros/blogs, otra web) por lo que es, nunca por confiar en
.govu.org. - Independencia. Las páginas del mismo sitio, o que copian el mismo texto, cuentan como una sola línea de evidencia.
- Comparar. El modelo dice si cada fuente apoya, contradice, apoya con límites o no responde, y tiene que citar la oración exacta. Si la cita no está en la página, esa fuente no cuenta.
- Veredicto por reglas, no un porcentaje: Respaldada, Probablemente respaldada, Mixta, No concluyente, Probablemente falsa, Falsa o No verificable. Nunca «respaldada» con una sola fuente secundaria; la evidencia en conflicto se muestra como conflicto, no se promedia.
El informe muestra cada afirmación, su veredicto y por qué, las fuentes a favor y en contra (tipo, fecha, autor, cita), qué vino de brain y qué de internet, y las limitaciones. Acciones: copiar el informe (Markdown), abrir las fuentes, volver a verificar, Guardar en brain (un click aparte; nada se guarda solo) y No usar este dominio. Los últimos 30 informes quedan en data/factchecks.json.
FACT-CHECK.md
El mismo método, escrito para cualquier IA, está en FACT-CHECK.md, en la raíz del vault (cuelga de BRAIN.md, al lado de FORMAT.md): primero brain; cuándo buscar en internet (no hay nada guardado, está viejo, se contradice o es para decidir algo importante) y nunca con tus datos personales en la búsqueda; consultas neutral, de evidencia, de contraevidencia y de fuente primaria; qué fuentes cuentan y que las copias son una sola línea de evidencia; una cita real para cada afirmación; las palabras del veredicto y sus reglas; y cómo responder sin guardar nada que no pediste. Su bloque de Preferencias se reescribe cada vez que las cambiás acá. Los agentes lo tienen señalado en las instrucciones del server, en fact_check y cuando search_knowledge no encuentra nada; el chat recibe un recordatorio corto en cada respuesta y la guía entera con /factcheck o la verificación automática. Lo editás solo vos (desde el grafo).
Preferencias
Se configuran una vez en la vista y valen para cada verificación nueva (y para el chat). Básico: nivel (Rápida, Estándar —recomendada—, Exhaustiva, Personalizada), actualidad (según el tema, 24 horas, 30 días, un año, sin límite o fechas propias), exigir fuente primaria, buscar evidencia en contra. Avanzado: mínimo de fuentes independientes y máximo a leer, qué tipos de afirmaciones verificar, verificar siempre y con más rigor salud, derecho, finanzas y seguridad, países e idiomas, fuentes de otros países, cuánto confiar en cada tipo de fuente, buscador, dominios bloqueados y si el chat puede verificar solo. Restaurar valores recomendados vuelve a los de fábrica.
Buscador
| Buscador | Qué necesita |
|---|---|
| DuckDuckGo (por defecto) | Nada. |
| SearXNG | La URL de tu instancia, con la salida JSON activada. |
| Brave Search API | Una clave de su API. Se guarda en data/factcheck.json (600) y la API nunca la devuelve. |
| Una de tus Conexiones | Una tool de búsqueda que ya conectaste a brain (get_serp_results de OpenSEO, una de búsqueda de Composio, Tavily, Exa, el MCP de Brave…). Elegila en la lista y sumá argumentos fijos en JSON si los pide (por ej. {"projectId": "…"}). La consulta va en el campo que corresponda, las URLs salen del resultado y nada de lo que devuelve se guarda en tu brain. |
Desde el chat y los agentes
/factcheck <texto> lo usa desde el chat, y los agentes tienen la tool fact_check, que siempre aplica tus preferencias. Con Que el chat y todos tus agentes verifiquen los datos que no están en brain (apagado por defecto), todos los agentes reciben la instrucción: el chat de brain en su system prompt, y Claude, ChatGPT y cualquier cliente MCP en las instrucciones del server y en el propio search_knowledge, que sugiere fact_check cuando no encuentra nada (o cuando lo que encontró puede no responder). Los agentes leen las instrucciones del server al conectarse: reabrilos después de prenderlo.
En salud, derecho, finanzas o seguridad el informe aclara que es informativo y no reemplaza a un profesional. Fact check necesita un modelo de chat en Ollama para separar afirmaciones y comparar la evidencia; sin uno, lo avisa.
The WorkStudio family
brain is one of five apps that work together: AI WorkStudio, brain, OpenCue, Lumina and OpenBlocks. It uses the others as programs you already have installed (through their command, their local port or their database), without copying their data or bundling their code.
| App | What it is | How brain uses it |
|---|---|---|
| OpenCue | Desktop app with personal AI agents (memory, tools, a computer of their own). | Its agents show up in the chat's model picker as OpenCue · name. They answer with your brain profile and memory as context. |
| Lumina | Local meeting notes and knowledge base (transcripts, summaries, your files). | The + button in the chat turns on search in Lumina's knowledge base; the lumina_search tool does the same for any agent. |
| OpenBlocks | Local notes app: block editor over a Markdown vault, databases, graph and an AI chat. | The + button in the chat turns on search in your OpenBlocks pages; the openblocks_search tool does the same for any agent. brain runs openblocks mcp --read-only and only reads. |
| AI WorkStudio | The hub that opens all of them in one window, with one MCP server (workstudio mcp) that joins their tools. | brain is part of its catalog and its MCP server. From Settings → WorkStudio family you can see whether it is installed and open it. |
Where an agent's memory goes
OpenCue can keep a notebook per agent, per group and a shared one inside brain. Agents are not projects: they live in their own agents/ folder (agents/<agent>/index.md is an Agent note and the rest are File notes), with their own node type in the graph. Older versions wrote them under projects/opencue-agents: if that folder is still there, Settings → WorkStudio family offers Move to agents/, which moves everything with history (restorable) and updates the type and path links.
Talking to an OpenCue agent from the chat
Open a new chat and pick an agent in the model selector (they are listed after your Ollama and LM Studio models). The first message of the chat carries what brain knows about you: profile.md, the memory and the BRAIN.md index, so the agent starts with the full context. The next messages only carry what you write. The agent runs inside the OpenCue app with its own tools, memory and permissions: if it needs your approval for something, it asks in OpenCue.
Under the hood brain does what AI WorkStudio does: it starts opencue mcp-serve --agent <another agent> and calls its send_to_agent tool, which delivers the message to the agent you picked and waits for the answer. OpenCue's app has to be open (brain opens it if it isn't). The answer arrives whole, not word by word, and the chat has no context meter for agents. Anything the agent writes to its own conversation stays in OpenCue.
Searching Lumina
The + button at the start of the message box has a Search Lumina switch (it says whether Lumina is running). With it on, a Lumina tag appears above the box and each message first searches Lumina's knowledge base (GET /api/search on 127.0.0.1:47770) and hands the passages to the model, or to the OpenCue agent, with their title and date so it can cite them. The search shows up under the answer as a lumina_search call. If Lumina isn't running or doesn't have its search model ready yet, the chat says so and answers without it.
Agents connected to brain get the same thing as the lumina_search(query, limit?, scope?) tool (scope: all, documents, meetings or notes). It is not available in read-only remote access.
Privacy
- brain only talks to Lumina on this computer (
127.0.0.1,localhost) and only when you turn the switch on or an agent calls the tool. - It reads OpenCue's agent list from its database in read-only mode and writes nothing there.
- With AI WorkStudio's single MCP server, brain's
lumina_searchand Lumina's ownsearch_knowledgeboth appear. They do the same; use either.
Settings → WorkStudio family
A card per app, with its logo, whether it is installed or running (OpenCue's agent count, the version of Lumina and OpenBlocks) and an Open button; a switch to list OpenCue's agents in the chat, another to allow OpenBlocks search, and Lumina's URL if you changed its port.
La familia WorkStudio
brain es una de cinco apps que trabajan juntas: AI WorkStudio, brain, OpenCue, Lumina y OpenBlocks. Usa a las otras como programas que ya tenés instalados (por su comando, su puerto local o su base de datos), sin copiar sus datos ni traer su código.
| App | Qué es | Cómo la usa brain |
|---|---|---|
| OpenCue | App de escritorio con agentes de IA personales (memoria, tools, una computadora propia). | Sus agentes aparecen en el selector de modelo del chat como OpenCue · nombre. Responden con tu perfil y tu memoria de brain como contexto. |
| Lumina | Notas de reuniones y base de conocimiento locales (transcripciones, resúmenes, tus archivos). | El botón + del chat enciende la búsqueda en la base de Lumina; la tool lumina_search hace lo mismo para cualquier agente. |
| OpenBlocks | App de notas local: editor por bloques sobre un vault de Markdown, bases de datos, grafo y un chat con IA. | El botón + del chat enciende la búsqueda en tus páginas de OpenBlocks; la tool openblocks_search hace lo mismo para cualquier agente. brain corre openblocks mcp --read-only y solo lee. |
| AI WorkStudio | El hub que abre a todas en una ventana, con un solo servidor MCP (workstudio mcp) que junta sus tools. | brain está en su catálogo y en su servidor MCP. Desde Ajustes → Familia WorkStudio ves si está instalada y la abrís. |
Dónde va la memoria de un agente
OpenCue puede guardar dentro de brain un cuaderno por agente, por grupo y uno compartido. Los agentes no son proyectos: viven en su propia carpeta agents/ (agents/<agente>/index.md es una nota Agent y el resto son notas File), con su propio tipo de nodo en el grafo. Las versiones anteriores los escribían en projects/opencue-agents: si esa carpeta sigue ahí, Ajustes → Familia WorkStudio ofrece Mover a agents/, que mueve todo con historial (se puede restaurar) y actualiza el tipo y los links por ruta.
Hablar con un agente de OpenCue desde el chat
Abrí un chat nuevo y elegí un agente en el selector de modelo (aparecen después de tus modelos de Ollama y LM Studio). El primer mensaje del chat lleva lo que brain sabe de vos: profile.md, la memoria y el índice BRAIN.md, así el agente arranca con todo el contexto. Los mensajes siguientes llevan solo lo que escribís. El agente corre dentro de la app de OpenCue con sus propias tools, su memoria y sus permisos: si necesita tu aprobación para algo, la pide en OpenCue.
Por debajo brain hace lo mismo que AI WorkStudio: arranca opencue mcp-serve --agent <otro agente> y llama a su tool send_to_agent, que le entrega el mensaje al agente que elegiste y espera la respuesta. La app de OpenCue tiene que estar abierta (brain la abre si no lo está). La respuesta llega entera, no palabra por palabra, y el chat no muestra el medidor de contexto con agentes. Lo que el agente escriba en su propia conversación queda en OpenCue.
Buscar en Lumina
El botón + al principio de la caja de mensaje tiene un interruptor Buscar en Lumina (dice si Lumina está corriendo). Con él prendido, aparece una etiqueta Lumina arriba de la caja y cada mensaje busca primero en la base de conocimiento de Lumina (GET /api/search en 127.0.0.1:47770) y le pasa los fragmentos al modelo, o al agente de OpenCue, con su título y fecha para que los cite. La búsqueda se ve debajo de la respuesta como una llamada lumina_search. Si Lumina no está corriendo o todavía no tiene listo su modelo de búsqueda, el chat lo avisa y responde sin ella.
Los agentes conectados a brain tienen lo mismo como la tool lumina_search(query, limit?, scope?) (scope: all, documents, meetings o notes). No está en el acceso remoto de solo lectura.
Privacidad
- brain solo habla con Lumina en esta compu (
127.0.0.1,localhost) y solo cuando prendés el interruptor o un agente llama a la tool. - La lista de agentes de OpenCue se lee de su base de datos en solo lectura; brain no escribe nada ahí.
- Con el servidor MCP único de AI WorkStudio aparecen tanto el
lumina_searchde brain como elsearch_knowledgede Lumina. Hacen lo mismo; usá cualquiera.
Ajustes → Familia WorkStudio
Una tarjeta por app, con su logo, si está instalada o corriendo (la cantidad de agentes de OpenCue, la versión de Lumina y de OpenBlocks) y un botón Abrir; un interruptor para listar los agentes de OpenCue en el chat, otro para permitir la búsqueda en OpenBlocks y la URL de Lumina si cambiaste su puerto.
Connections
brain is also an MCP client. Add other MCP servers (GitHub, Notion, Gmail…) and their tools show up in every agent you connected, with their results saved to your memory.
Types
- Local command (recommended): an MCP server that runs on your computer, e.g.
npx -y @modelcontextprotocol/server-githubwithGITHUB_TOKEN=…. The token stays on your machine. - URL: a remote MCP server, with optional headers (
Authorization: Bearer …). - Composio (optional): hundreds of apps through one connection. Composio keeps your accounts' OAuth tokens in its own cloud. A consumer key (
ck_…) connects directly; a project key (ak_…) lets you pick auth configs and creates an MCP server through Composio's developer API.
Proxied tools
Tools are re-exposed with the connection's prefix: github__create_issue, composio__GMAIL_FETCH_EMAILS. Turning a connection off removes its tools from your agents right away, without restarting anything. Each call opens a session with the origin server, runs, and closes it.
Save to memory
With the switch on, every result is written to knowledge/connections/<connection>/…md (or knowledge/composio/<app>/…) with the tool, arguments and time in its frontmatter, and indexed for semantic and keyword search. Long results get an abstract, and all get entities when a chat model is available. Capturing never breaks the call: without Chroma or Ollama the .md is saved anyway.
Signing in (OAuth)
Many remote servers (Notion, Linear, Sentry…) answer 401 Unauthorized until you sign in. Add them by URL without headers: the card shows Sign in, which opens the service's own login in a new tab. When you approve, the service sends you back to http://127.0.0.1:<port>/oauth/callback, brain stores the token in ~/.brain/data/oauth.json (permissions 600) and renews it on its own. It's the standard MCP authorization (discovery, dynamic client registration and PKCE). Sign out forgets the token. If an agent uses the connection before you sign in, it gets an error telling it to sign in from the dashboard.
Adding connectors from the chat
Type /add-mcp and paste a URL (the docs on GitHub, npm or PyPI, or the server's own /mcp URL) or describe what you want. The chat reads the docs with read_url, asks for any API key it needs and calls propose_connection. Nothing is added yet: a card shows the exact command or URL and the keys it asks for, and you choose Add or Discard. The same proposals wait in the Connections tab, including those made by other agents. After you add a server that needs a login, the card offers Sign in.
Secrets
Env values, headers and API keys go to ~/.brain/.env (permissions 600, gitignored); the config only stores references ($env:KEY). The dashboard never returns them.
Conexiones
brain también es cliente MCP. Agregá otros servers MCP (GitHub, Notion, Gmail…) y sus tools aparecen en todos los agentes que conectaste, con sus resultados guardados en tu memoria.
Tipos
- Comando local (recomendado): un server MCP que corre en tu compu, por ejemplo
npx -y @modelcontextprotocol/server-githubconGITHUB_TOKEN=…. El token queda en tu máquina. - URL: un server MCP remoto, con headers opcionales (
Authorization: Bearer …). - Composio (opcional): cientos de apps con una sola conexión. Composio guarda los tokens OAuth de tus cuentas en su nube. Una consumer key (
ck_…) conecta directo; una key de proyecto (ak_…) te deja elegir auth configs y crea un server MCP con la API de desarrollador de Composio.
Tools proxeadas
Las tools se re-exponen con el prefijo de la conexión: github__create_issue, composio__GMAIL_FETCH_EMAILS. Apagar una conexión saca sus tools de tus agentes en el momento, sin reiniciar nada. Cada llamada abre una sesión con el server de origen, ejecuta y la cierra.
Guardar en memoria
Con el switch prendido, cada resultado se escribe en knowledge/connections/<conexión>/…md (o knowledge/composio/<app>/…) con la tool, los argumentos y la hora en el frontmatter, y se indexa para la búsqueda semántica y por palabra. Los resultados largos llevan un abstract, y todos llevan entities si hay un modelo de chat. Capturar nunca rompe la llamada: sin Chroma u Ollama el .md se guarda igual.
Iniciar sesión (OAuth)
Muchos servers remotos (Notion, Linear, Sentry…) responden 401 Unauthorized hasta que iniciás sesión. Agregalos por URL sin headers: la tarjeta muestra Iniciar sesión, que abre el login del servicio en otra pestaña. Cuando aprobás, el servicio te devuelve a http://127.0.0.1:<puerto>/oauth/callback, brain guarda el token en ~/.brain/data/oauth.json (permisos 600) y lo renueva solo. Es la autorización estándar de MCP (descubrimiento, registro dinámico del cliente y PKCE). Cerrar sesión olvida el token. Si un agente usa la conexión antes de que inicies sesión, recibe un error que le dice que lo hagas desde el dashboard.
Agregar conectores desde el chat
Escribí /add-mcp y pegá una URL (la documentación en GitHub, npm o PyPI, o la URL /mcp del server) o contá qué querés. El chat lee la documentación con read_url, te pide las API keys que falten y llama a propose_connection. Todavía no se agrega nada: una tarjeta muestra el comando o la URL exactos y las claves que pide, y vos elegís Agregar o Descartar. Las mismas propuestas esperan en la pestaña Conexiones, incluidas las que hagan otros agentes. Si el server necesita login, después de agregarlo la tarjeta ofrece Iniciar sesión.
Secretos
Los valores de env, headers y API keys van a ~/.brain/.env (permisos 600, en el gitignore); la config solo guarda referencias ($env:CLAVE). El dashboard nunca los devuelve.
Reflect and skills
Two ways to make stored memory more useful: Reflect reviews it and suggests fixes, and distill_skill turns everything on a topic into a reusable skill.
Reflect
Profile tab → Review my memory. It looks for:
| Suggestion | When | Suggested action |
|---|---|---|
| Possible duplicate | The same fact (or nearly) in two places of memory/ | Remove one (Profile → Your memory, or str_replace_file) |
| Possible contradiction | Two facts that start the same but say something different ("Lives in Palermo" / "Lives in Núñez") | add_memory(new, category, supersede=old) |
| No entities | Recently changed notes in knowledge/ or memory/ without entities | set_frontmatter(path, {"entities": […]}) with the names the local model found |
Reflect never writes anything. Each suggestion shows the tool call that would apply it; apply it yourself or ask the chat to. Without a chat model, the entity check is skipped; it processes up to 20 files per run.
distill_skill
Ask an agent "make a skill about X". It calls distill_skill("X"), which returns:
{
"topic": "pricing",
"skill_path": "skills/pricing.md",
"existing_skill": null,
"chunks": [ …hybrid search hits… ],
"memory": [ {"category": "Work", "fact": "…"} ],
"sources": [ "knowledge/sources/…md" ],
"instructions": "Synthesize this material into a reusable skill…"
}
The agent writes the skill and saves it with write_file. brain only gathers the material: the skill is written by the same model that will use it later, not by a hidden call with another prompt. If a skill with that name exists, the agent is told to update it instead of overwriting it.
Reflect y skills
Dos formas de hacer más útil la memoria guardada: Reflect la revisa y sugiere arreglos, y distill_skill convierte todo lo que hay sobre un tema en un skill reutilizable.
Reflect
Pestaña Perfil → Revisar mi memoria. Busca:
| Sugerencia | Cuándo | Acción sugerida |
|---|---|---|
| Posible duplicado | El mismo hecho (o casi) en dos lugares de memory/ | Sacar uno (Perfil → Tu memoria, o str_replace_file) |
| Posible contradicción | Dos hechos que empiezan igual pero dicen otra cosa ("Vive en Palermo" / "Vive en Núñez") | add_memory(nuevo, categoría, supersede=viejo) |
| Sin entidades | Notas de knowledge/ o memory/ tocadas hace poco sin entities | set_frontmatter(path, {"entities": […]}) con los nombres que encontró el modelo local |
Reflect nunca escribe nada. Cada sugerencia muestra la tool que la aplicaría; aplicala vos o pedíselo al chat. Sin un modelo de chat, se saltea la revisión de entidades; procesa hasta 20 archivos por corrida.
distill_skill
Pedile a un agente "armá un skill sobre X". Llama a distill_skill("X"), que devuelve:
{
"topic": "precios",
"skill_path": "skills/precios.md",
"existing_skill": null,
"chunks": [ …resultados de la búsqueda híbrida… ],
"memory": [ {"category": "Trabajo", "fact": "…"} ],
"sources": [ "knowledge/sources/…md" ],
"instructions": "Sintetizá este material en un skill reutilizable…"
}
El agente redacta el skill y lo guarda con write_file. brain solo junta el material: el skill lo escribe el mismo modelo que después lo va a usar, no una llamada oculta con otro prompt. Si ya existe un skill con ese nombre, el agente tiene la instrucción de actualizarlo en vez de pisarlo.
MCP tools
Every tool brain exposes to your agents. Errors come back as text starting with Error:, never as exceptions.
Vault
| Tool | What it does |
|---|---|
list_vault(prefix?) | Lists .md files with their description. prefix filters by folder, e.g. projects. |
read_file(path) | Full content of a file. |
write_file(path, content) | Creates or replaces a whole file. |
append_file(path, content) | Appends to the end (creates the file if missing). |
str_replace_file(path, old, new) | Targeted replace; old must appear exactly once. |
set_frontmatter(path, fields) | Changes metadata without touching the content; null removes a field. |
delete_file(path) | Deletes a file (recoverable). |
file_history(path) | A file's versions, newest first. |
restore_file(path, version_id) | Restores a version (also brings back deleted files). |
move_file(src, dst) | Moves or renames a note (recoverable). Not for BRAIN.md, profile.md, memory/ or knowledge/sources/. |
vault_overview() | What's messy in the vault: loose notes, no links, no description, tag variants, similar names. Read-only. |
propose_graph_change(changes, reason?) | Proposes adding or removing related links (up to 10). Changes nothing: you see an image with the changes marked and approve or reject it. See The graph. |
inspect_graph_region(nodes) | Neighbors of some notes and why they're linked (text link, related, tag, entity). Read-only. |
Memory
| Tool | What it does |
|---|---|
add_memory(fact, category?, supersede?) | Saves a dated fact in memory/<category>.md without duplicates. With supersede, the old fact moves to ## Historial. |
memory_history(category?) | Superseded facts of a category. |
Knowledge
| Tool | What it does |
|---|---|
save_url(url, render_js?) | Scrapes, indexes and saves a URL. |
search_knowledge(query, top_k?) | Hybrid search (semantic + keyword). top_k 1–50, default 5. |
list_sources() | Saved URLs with title, when the content was downloaded and last checked, path and abstract. |
refresh_sources(path?) | Re-downloads one source (or all). If it fails, keeps the last good copy and notes the error. |
read_url(url, max_chars?) | Reads a page's text without saving it. |
web_search(query, max_results?, freshness?) | Searches the web with brain's built-in search engine (the one from Fact check: DuckDuckGo, your own SearXNG, Brave or a Connections tool). Returns title, URL, snippet, date and source type; it doesn't read the pages or save anything. Respects the internet switch and the blocked domains. Not available in read-only remote access. |
lumina_search(query, limit?, scope?) | Searches Lumina's knowledge base (your meetings, files and notes) when Lumina is running on your computer. Read-only; not available in read-only remote access. See OpenCue, Lumina and WorkStudio. |
openblocks_search(query, limit?) | Searches the pages of OpenBlocks (your local notes app) through openblocks mcp --read-only. Read-only; the app doesn't need to be open, only installed; not available in read-only remote access. |
fact_check(text, search_web?) | Verifies claims: brain first, the web if needed, verdict by rules with sources and quotes. Saves nothing. See Fact check. |
reindex_keyword_search() | Rebuilds the keyword index from knowledge/. |
Skills
| Tool | What it does |
|---|---|
list_skills() | Skills in skills/ with their description. |
get_skill(name) | A skill's content. |
distill_skill(topic) | Gathers the material on a topic so the agent writes a skill. |
Connections
| Tool | What it does |
|---|---|
propose_connection(name, url? | command?, args?, env?, headers?, note?) | Proposes an MCP server for Connections. It doesn't add it: the user approves it with one click. |
list_connections() | Your connections, whether they're active, and their tools. |
refresh_connectors() | Re-discovers the tools of every active connection. |
<connection>__<tool> | Any tool from an active connection, proxied. |
Tools MCP
Todas las tools que brain expone a tus agentes. Los errores vuelven como texto que empieza con Error:, nunca como excepciones.
Vault
| Tool | Qué hace |
|---|---|
list_vault(prefix?) | Lista los .md con su description. prefix filtra por carpeta, ej. projects. |
read_file(path) | Contenido completo de un archivo. |
write_file(path, content) | Crea o reemplaza un archivo entero. |
append_file(path, content) | Agrega al final (crea el archivo si no existe). |
str_replace_file(path, old, new) | Reemplazo puntual; old tiene que aparecer exactamente una vez. |
set_frontmatter(path, fields) | Cambia metadatos sin tocar el contenido; null borra un campo. |
delete_file(path) | Borra un archivo (recuperable). |
file_history(path) | Versiones de un archivo, la más nueva primero. |
restore_file(path, version_id) | Restaura una versión (también recupera archivos borrados). |
move_file(src, dst) | Mueve o renombra una nota (recuperable). No aplica a BRAIN.md, profile.md, memory/ ni knowledge/sources/. |
vault_overview() | Lo desordenado del vault: notas sueltas, sin conexiones, sin descripción, variantes de tags, nombres parecidos. Solo lee. |
propose_graph_change(changes, reason?) | Propone agregar o sacar conexiones de related (hasta 10). No cambia nada: ves una imagen con los cambios marcados y la aprobás o rechazás. Ver El grafo. |
inspect_graph_region(nodes) | Vecinos de algunas notas y por qué están unidas (link en el texto, related, tag, entidad). Solo lee. |
Memoria
| Tool | Qué hace |
|---|---|
add_memory(fact, category?, supersede?) | Guarda un hecho con fecha en memory/<categoría>.md sin duplicar. Con supersede, el hecho viejo pasa a ## Historial. |
memory_history(category?) | Hechos superados de una categoría. |
Conocimiento
| Tool | Qué hace |
|---|---|
save_url(url, render_js?) | Scrapea, indexa y guarda una URL. |
search_knowledge(query, top_k?) | Búsqueda híbrida (semántica + por palabra). top_k de 1 a 50, por defecto 5. |
list_sources() | URLs guardadas con título, de cuándo es el contenido y cuándo se revisó, path y abstract. |
refresh_sources(path?) | Vuelve a bajar una fuente (o todas). Si falla, conserva la última copia buena y anota el error. |
read_url(url, max_chars?) | Lee el texto de una página sin guardarla. |
web_search(query, max_results?, freshness?) | Busca en internet con el buscador incorporado de brain (el de Fact check: DuckDuckGo, tu SearXNG propio, Brave o una tool de las Conexiones). Devuelve título, URL, fragmento, fecha y tipo de fuente; no lee las páginas ni guarda nada. Respeta el interruptor de internet y los dominios bloqueados. No está disponible en el acceso remoto de solo lectura. |
lumina_search(query, limit?, scope?) | Busca en la base de conocimiento de Lumina (tus reuniones, archivos y notas) cuando Lumina está corriendo en tu compu. Solo lee; no está en el acceso remoto de solo lectura. Ver OpenCue, Lumina y WorkStudio. |
openblocks_search(query, limit?) | Busca en las páginas de OpenBlocks (tu app de notas local) con openblocks mcp --read-only. Solo lee; la app no tiene que estar abierta, solo instalada; no está en el acceso remoto de solo lectura. |
fact_check(text, search_web?) | Verifica afirmaciones: primero brain, internet si hace falta, veredicto por reglas con fuentes y citas. No guarda nada. Ver Fact check. |
reindex_keyword_search() | Reconstruye el índice por palabra desde knowledge/. |
Skills
| Tool | Qué hace |
|---|---|
list_skills() | Skills de skills/ con su description. |
get_skill(name) | El contenido de un skill. |
distill_skill(topic) | Junta el material sobre un tema para que el agente redacte un skill. |
Conexiones
| Tool | Qué hace |
|---|---|
propose_connection(name, url? | command?, args?, env?, headers?, note?) | Propone un server MCP para Conexiones. No lo agrega: el usuario lo aprueba con un click. |
list_connections() | Tus conexiones, si están activas y sus tools. |
refresh_connectors() | Vuelve a descubrir las tools de cada conexión activa. |
<conexión>__<tool> | Cualquier tool de una conexión activa, proxeada. |
The brain command
Installed in ~/.local/bin/brain. From a clone, ./brain.sh does the same.
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 app opens the desktop app (menu bar / tray, notifications, notch) brain app-update downloads the latest release's app and reopens it brain update updates to the latest version (git pull + uv sync) brain path shows where it's installed brain uninstall removes the command and the desktop app (keeps your data) brain help help
While the dashboard runs, Settings → Update and restart does the same as brain update without leaving it: the dashboard exits with code 75, the brain command runs the update and reopens it in the same terminal (without opening another browser tab). If the update fails it reopens the installed version and says so. A dashboard started with python dashboard.py instead of brain can't restart itself.
Standalone scripts
For when you need a piece without the dashboard:
./chroma_server.sh # Chroma alone on 127.0.0.1:8055 ./start.sh # MCP server over stdio (normally launched by the client) uv run python server.py --http # MCP server over HTTP on 127.0.0.1:8770, with the token (what remote access runs) npx @modelcontextprotocol/inspector uv run python server.py # MCP Inspector
El comando brain
Se instala en ~/.local/bin/brain. Desde un clon, ./brain.sh hace lo mismo.
brain abre el dashboard y prende Ollama y Chroma brain --port 8766 dashboard en otro puerto brain --no-autostart no prender Ollama/Chroma solo brain --no-browser no abrir el navegador brain app abre la app de escritorio (barra de menú / bandeja, avisos, notch) brain app-update baja la app del último release y la vuelve a abrir brain update actualiza a la última versión (git pull + uv sync) brain path muestra dónde está instalado brain uninstall saca el comando y la app de escritorio (tus datos quedan) brain help ayuda
Con el dashboard abierto, Ajustes → Actualizar y reiniciar hace lo mismo que brain update sin salir: el dashboard sale con el código 75, el comando brain actualiza y lo vuelve a abrir en la misma terminal (sin abrir otra pestaña del navegador). Si la actualización falla, vuelve a abrir la versión instalada y lo avisa. Un dashboard abierto con python dashboard.py en vez de brain no se puede reiniciar solo.
Scripts sueltos
Para cuando necesitás una pieza sin el dashboard:
./chroma_server.sh # solo Chroma en 127.0.0.1:8055 ./start.sh # server MCP por stdio (normalmente lo lanza el cliente) uv run python server.py --http # server MCP por HTTP en 127.0.0.1:8770, con el token (lo que corre el acceso remoto) npx @modelcontextprotocol/inspector uv run python server.py # Inspector MCP
Configuration
brain works without configuration. These are the knobs and the files it uses.
Environment variables
| Variable | Default | What it does |
|---|---|---|
BRAIN_CHROMA_PORT | 8055 | Port of the Chroma server (read by the scripts and the server). |
BRAIN_SUMMARY_MODEL | llama3.2 if installed, otherwise the first chat model | Ollama chat model used for abstract and entities. off disables both. |
BRAIN_LLM_TIMEOUT | 45 | Seconds to wait for a summary or entity list before giving up (the note is saved anyway). |
BRAIN_CHAT_CTX | 16384 | Default cap for the chat's context window, until you change it in Settings → Context (which takes precedence). |
BRAIN_AUTO_COMPACT | 0.85 | Share of the context window at which the chat compacts by itself before answering; 0 turns it off. |
BRAIN_CHAT_KEEP_ALIVE | 30m | How long Ollama keeps the chat model loaded after an answer (Ollama's keep_alive), so the next one doesn't wait for it to load again. |
BRAIN_REMOTE_PORT | 8770 | Local port of the MCP-by-URL server that remote access publishes. |
BRAIN_HOME, BRAIN_PORT | ~/.brain, 8765 | For the desktop app: where brain is installed and which port its dashboard uses. brain app sets BRAIN_HOME for you. |
BRAIN_APP | unset | The app sets it to 1 when it starts the dashboard (Logs gets an App tab). You don't set it yourself. |
Ports
| Port | Service |
|---|---|
8765 | Dashboard (--port to change) |
8055 | Chroma |
11434 | Ollama |
6274 / 6275 | MCP Inspector |
8770 | MCP by URL for remote access, local only (BRAIN_REMOTE_PORT to change) |
Files
Path (inside ~/.brain) | Contents |
|---|---|
vault/ | Your notes, profile and memory |
data/history.sqlite3 | Version history |
data/search.sqlite3 | Keyword index (can be rebuilt) |
data/chroma/ | Vector index |
data/connections.json, connections_tools.json | Connections and their cached tools |
data/clients.json | Apps detected through the MCP handshake |
data/remote.json | Remote access settings, URL token and tunnel token (permissions 600) |
data/bin/ | cloudflared, if brain downloaded it |
.env | Secrets (permissions 600) |
vault/, data/ and .env are in .gitignore. To start from scratch, close the dashboard and your agents, delete vault/ and data/, and open brain again.
Configuración
brain funciona sin configurar nada. Estas son las perillas y los archivos que usa.
Variables de entorno
| Variable | Por defecto | Qué hace |
|---|---|---|
BRAIN_CHROMA_PORT | 8055 | Puerto del server de Chroma (lo leen los scripts y el server). |
BRAIN_SUMMARY_MODEL | llama3.2 si está instalado, si no el primer modelo de chat | Modelo de chat de Ollama para abstract y entities. off apaga los dos. |
BRAIN_LLM_TIMEOUT | 45 | Segundos de espera para un resumen o una lista de entidades antes de abandonar (la nota se guarda igual). |
BRAIN_CHAT_CTX | 16384 | Tope por defecto de la ventana de contexto del chat, hasta que lo cambies en Ajustes → Contexto (que manda). |
BRAIN_AUTO_COMPACT | 0.85 | Parte de la ventana de contexto a la que el chat se compacta solo antes de responder; 0 lo apaga. |
BRAIN_CHAT_KEEP_ALIVE | 30m | Cuánto deja Ollama cargado el modelo del chat después de una respuesta (keep_alive de Ollama), así la siguiente no espera a que se cargue de nuevo. |
BRAIN_REMOTE_PORT | 8770 | Puerto local del server MCP por URL que publica el acceso remoto. |
BRAIN_HOME, BRAIN_PORT | ~/.brain, 8765 | Para la app de escritorio: dónde está instalado brain y qué puerto usa su dashboard. brain app define BRAIN_HOME por vos. |
BRAIN_APP | sin definir | La app lo pone en 1 cuando arranca el dashboard (Logs suma una pestaña App). No lo definís vos. |
Puertos
| Puerto | Servicio |
|---|---|
8765 | Dashboard (--port para cambiarlo) |
8055 | Chroma |
11434 | Ollama |
6274 / 6275 | Inspector MCP |
8770 | MCP por URL del acceso remoto, solo local (BRAIN_REMOTE_PORT para cambiarlo) |
Archivos
Path (dentro de ~/.brain) | Contenido |
|---|---|
vault/ | Tus notas, perfil y memoria |
data/history.sqlite3 | Historial de versiones |
data/search.sqlite3 | Índice por palabra (se puede reconstruir) |
data/chroma/ | Índice vectorial |
data/connections.json, connections_tools.json | Conexiones y el caché de sus tools |
data/clients.json | Apps detectadas por el handshake MCP |
data/remote.json | Ajustes del acceso remoto, token de la URL y del túnel (permisos 600) |
data/bin/ | cloudflared, si lo bajó brain |
.env | Secretos (permisos 600) |
vault/, data/ y .env están en el .gitignore. Para arrancar de cero, cerrá el dashboard y tus agentes, borrá vault/ y data/, y abrí brain de nuevo.
Privacy and security
Your data stays on your computer. brain only goes online when you save or refresh a URL, use a connection that talks to a remote service, run a Fact check that needs the web, or checks GitHub for a new version. The privacy policy covers this website too (including its chat, provided by DokBot).
What stays local
- The vault, the history, both search indexes and your secrets live in
~/.brain. - Embeddings, summaries and entities are computed by Ollama on your machine.
- Composio, if you use it, keeps your app tokens in its cloud; everything it fetches is saved locally.
- Sign-ins to MCP servers (OAuth) stay in
~/.brain/data/oauth.json(permissions600). - brain goes online on its own only to check GitHub for a new version (it reads the latest release number and sends nothing about you), and, if you turn on remote access, to keep the Cloudflare tunnel open.
- Fact check sends the claims you verify (as search queries) to the search engine you chose (DuckDuckGo by default) and opens the result pages; only when you run a check, or when the chat does if you turned that on. Pages on your computer or local network are never opened, and nothing is saved to the vault unless you click Save to brain.
- Chat answers can contain HTML, but it's sanitized: no scripts or forms, and no images from other sites (so a hidden instruction can't leak data through an image URL).
- Backups leave credentials out unless you tick Include credentials.
The dashboard
- Listens only on
127.0.0.1. - Rejects any request whose
Hostisn't127.0.0.1:<port>orlocalhost:<port>(DNS-rebinding protection). - Every POST requires the
X-Brain: 1header, which forces a CORS preflight the server never approves: no website you have open can start processes or write to your vault.
Agents
- Tools can't leave the vault (
.., absolute paths, hidden files and outbound symlinks are rejected). BRAIN.md,FORMAT.md,FACT-CHECK.mdand the base folders are read-only for every AI; only you edit them, from the graph.- Every write is versioned and can be undone.
- Agent configs are never rewritten without a backup, and other entries are never removed.
- Agents can only propose a connection (
propose_connection). Nothing runs until you click Add on a card that shows the exact command or URL.
Remote access
- Remote access by URL is off until you turn it on. While it's on, your vault is reachable from the internet by anyone who has the URL: it carries a secret token, can be regenerated at any time and can be set to read-only.
- The MCP server behind it listens only on
127.0.0.1; the Cloudflare tunnel is outbound and opens no ports. - Through the URL, brain never fetches addresses on your computer or local network.
Reporting a vulnerability
Please don't open a public issue. Use GitHub's private reporting: Security → Report a vulnerability. Scope and response times are in SECURITY.md.
Privacidad y seguridad
Tus datos se quedan en tu compu. brain solo sale a internet cuando guardás o actualizás una URL, usás una conexión que habla con un servicio remoto, hacés un Fact check que necesita la web o se fija en GitHub si hay una versión nueva. La política de privacidad cubre también este sitio (incluido su chat, provisto por DokBot).
Qué queda local
- El vault, el historial, los dos índices de búsqueda y tus secretos viven en
~/.brain. - Los embeddings, resúmenes y entidades los calcula Ollama en tu máquina.
- Composio, si lo usás, guarda los tokens de tus apps en su nube; todo lo que trae se guarda local.
- Las sesiones iniciadas en servers MCP (OAuth) quedan en
~/.brain/data/oauth.json(permisos600). - brain sale a internet por su cuenta solo para fijarse en GitHub si hay una versión nueva (lee el número del último release y no manda nada tuyo) y, si prendés el acceso remoto, para mantener abierto el túnel de Cloudflare.
- Fact check manda las afirmaciones que verificás (como búsquedas) al buscador que elegiste (DuckDuckGo por defecto) y abre las páginas de los resultados; solo cuando hacés una verificación, o cuando la hace el chat si lo activaste. Nunca abre páginas de tu compu ni de tu red local, y no guarda nada en el vault salvo que toques Guardar en brain.
- Las respuestas del chat pueden traer HTML, pero se sanitiza: sin scripts ni formularios, y sin imágenes de otros sitios (así una instrucción escondida no puede filtrar datos por la URL de una imagen).
- Los backups dejan afuera las credenciales salvo que marques Incluir credenciales.
El dashboard
- Escucha solo en
127.0.0.1. - Rechaza cualquier pedido cuyo
Hostno sea127.0.0.1:<puerto>olocalhost:<puerto>(protección contra DNS rebinding). - Cada POST exige el header
X-Brain: 1, que fuerza un preflight CORS que el server nunca aprueba: ninguna web que tengas abierta puede prender procesos ni escribir en tu vault.
Agentes
- Las tools no pueden salir del vault (se rechazan
.., paths absolutos, archivos ocultos y symlinks hacia afuera). BRAIN.md,FORMAT.md,FACT-CHECK.mdy las carpetas base son de solo lectura para cualquier IA; los editás solo vos, desde el grafo.- Cada escritura queda versionada y se puede deshacer.
- Las configs de los agentes nunca se reescriben sin backup, y nunca se borran entradas ajenas.
- Los agentes solo pueden proponer una conexión (
propose_connection). No se ejecuta nada hasta que tocás Agregar en una tarjeta que muestra el comando o la URL exactos.
Acceso remoto
- El acceso remoto por URL está apagado hasta que lo prendas. Mientras está prendido, tu vault es accesible desde internet para quien tenga la URL: lleva un token secreto, se puede regenerar cuando quieras y se puede poner en solo lectura.
- El server MCP detrás escucha solo en
127.0.0.1; el túnel de Cloudflare es de salida y no abre puertos. - Por la URL, brain nunca lee direcciones de tu computadora ni de tu red local.
Reportar una vulnerabilidad
Por favor no abras un issue público. Usá el reporte privado de GitHub: Security → Report a vulnerability. El alcance y los tiempos de respuesta están en SECURITY.md.
Troubleshooting
The usual problems and their fixes.
Services
| Problem | Fix |
|---|---|
| "Ollama isn't running" | Turn on the Ollama switch in the Dashboard tab, or open the Ollama app. |
| "The Chroma server isn't running" | Open the dashboard (brain); it starts Chroma. Keyword search keeps working without it. |
| Port 8765 is taken | brain --port 8766 |
brain: command not found | Open a new terminal, or add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc. |
Search and memory
| Problem | Fix |
|---|---|
| A name you know is saved isn't found | Sources from before v0.02.5 aren't in the keyword index: Rebuild keyword index in Knowledge, or reindex_keyword_search. |
No abstract or entities | Install a chat model: ollama pull llama3.2. Then run Reflect to find notes missing entities. |
| "Couldn't extract text from that URL" | The site may be paywalled or need a login. Try Force JS rendering. |
Agents
| Problem | Fix |
|---|---|
| brain doesn't show up in Claude Desktop | Connect it from Connect agent and restart Claude. |
| brain doesn't show up in ChatGPT | Use Codex or ChatGPT Work mode, then Settings → MCP servers → Restart. |
An app returns 403 | You used "Connect to a URL". Use Run a command. |
Composio returns 401 | A consumer key (ck_…) only works with Save and connect; Choose apps is for project keys (ak_…). |
Chat
| Problem | Fix |
|---|---|
| No chat model | Download llama3.2 in the Chat tab, or ollama pull llama3.2. |
| It answers but can't save anything | Open the actions under the answer to see what failed; try a larger model. |
Solución de problemas
Los problemas típicos y cómo resolverlos.
Servicios
| Problema | Solución |
|---|---|
| "Ollama no está corriendo" | Prendé el switch de Ollama en el Panel, o abrí la app de Ollama. |
| "El server de Chroma no está corriendo" | Abrí el dashboard (brain); prende Chroma. La búsqueda por palabra sigue andando sin él. |
| El puerto 8765 está ocupado | brain --port 8766 |
brain: command not found | Abrí una terminal nueva, o agregá export PATH="$HOME/.local/bin:$PATH" a ~/.zshrc. |
Búsqueda y memoria
| Problema | Solución |
|---|---|
| No encuentra un nombre que sabés que está guardado | Las fuentes de antes de v0.02.5 no están en el índice por palabra: Reindexar búsqueda por palabra en Conocimiento, o reindex_keyword_search. |
Sin abstract ni entidades | Instalá un modelo de chat: ollama pull llama3.2. Después corré Reflect para ver qué notas no tienen entidades. |
| "No se pudo extraer texto de esa URL" | El sitio puede tener paywall o pedir login. Probá Forzar render con JS. |
Agentes
| Problema | Solución |
|---|---|
| brain no aparece en Claude Desktop | Conectalo desde Conectar agente y reiniciá Claude. |
| brain no aparece en ChatGPT | Usá el modo Codex o ChatGPT Work, y después Settings → MCP servers → Restart. |
Una app devuelve 403 | Usaste "Connect to a URL". Usá Run a command. |
Composio devuelve 401 | Una consumer key (ck_…) solo anda con Guardar y conectar; Elegir apps es para keys de proyecto (ak_…). |
Chat
| Problema | Solución |
|---|---|
| No hay modelo de chat | Descargar llama3.2 en la pestaña Chat, o ollama pull llama3.2. |
| Responde pero no puede guardar nada | Abrí las acciones debajo de la respuesta para ver qué falló; probá un modelo más grande. |
License
MIT with the Commons Clause. Source available: use it, study it, change it and share it for free, including at work. Don't sell it.
What you can do
- Use brain personally or at work, for free.
- Read, modify and fork the code.
- Share it, keeping the copyright notice and both license files.
What you can't do
Sell it: charge third parties for a product or service (hosting, support or consulting included) whose value comes entirely or substantially from brain.
Files
LICENSE has both parts: the Commons Clause condition first, then the MIT text. GitHub only auto-detects standard license templates, and this combination isn't one, so it shows "View license" instead of a license name. Plain MIT would be detected, but it would allow selling brain. Because of the Commons Clause, brain isn't "open source" under the OSI definition. It applies to every version of brain.
Licencia
MIT con Commons Clause. Código a la vista: usalo, estudialo, cambialo y compartilo gratis, también en el trabajo. No lo vendas.
Qué podés hacer
- Usar brain para vos o en el trabajo, gratis.
- Leer, modificar y hacer fork del código.
- Compartirlo, manteniendo el aviso de copyright y los dos archivos de licencia.
Qué no podés hacer
Venderlo: cobrarle a terceros por un producto o servicio (incluidos hosting, soporte o consultoría) cuyo valor venga entera o sustancialmente de brain.
Archivos
LICENSE tiene las dos partes: primero la condición de la Commons Clause y después el texto MIT. GitHub solo detecta automáticamente las plantillas de licencia estándar, y esta combinación no es una: por eso muestra "View license" en vez de un nombre. El MIT solo lo detectaría, pero permitiría vender brain. Por la Commons Clause, brain no es "open source" según la definición de la OSI. Aplica a todas las versiones de brain.
Edit this page on GitHubEditar esta página en GitHub · v0.02.5