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 Mac; 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.

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.

Instalación

Un comando en macOS (Apple Silicon o Intel). Hace falta git (xcode-select --install); el instalador se ocupa del resto.

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

Qué hace el instalador

1. Instala uv si falta. uv maneja Python y las dependencias sin tocar el Python del sistema.
2. Clona brain en ~/.brain (o hace git pull si ya estaba).
3. Corre uv sync e instala el Chromium headless que se usa para scrapear sitios con JavaScript.
4. Instala Ollama con Homebrew si hace falta y baja nomic-embed-text (~270 MB). Sin Homebrew, te dice de dónde bajar Ollama.
5. Crea el comando brain en ~/.local/bin y lo agrega a tu PATH.

Es idempotente: correrlo de nuevo actualiza la instalación. Nunca pide nada, porque se ejecuta con curl | bash.

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

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

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.

El vault

Archivos Markdown comunes con frontmatter YAML en ~/.brain/vault/. Se crea desde una plantilla la primera vez que arranca brain.

Estructura

Frontmatter

Cada nota empieza con un bloque YAML. Se esperan name y description; la description es lo que muestran list_vault y el grafo.

---
name: tienda-online
description: Tienda en Next.js, lanzamiento a fin de mes
tags: [trabajo, nextjs]
related: [precios-que-convierten]
---
# Tienda online

Usa las ideas de [[precios-que-convierten]].

Campos que escribe brain solo: 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

• [[nombre]] en el texto enlaza otra nota.
• 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.

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.

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.

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 ## Historial al 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 en memory_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.

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:

1. trafilatura baja la página y extrae el texto limpio.
2. 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=True va directo a Chromium.
3. El texto se parte en chunks de ~500 palabras con 50 de solapamiento.
4. Cada chunk se embebe con Ollama (nomic-embed-text) y se guarda en Chroma, y también en el índice por palabra.
5. Si hay un modelo de chat instalado: las páginas de más de 800 palabras llevan un abstract corto, y los nombres que mencionan van a entities.
6. Se escribe knowledge/sources/<slug>.md con 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:

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.

El grafo

Un mapa interactivo del vault: cómo se conectan tu perfil, memorias, proyectos, skills, fuentes, tags y entidades.

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.

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.

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.

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

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

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 y Ajustes (el engranaje). Las preferencias se guardan en el navegador (localStorage).

Ajustes

Una vista completa (#ajustes) con cuatro secciones:

• Versión: la versión instalada y un botón Buscar actualizaciones. brain le pregunta a GitHub por el último release solo cuando lo tocás. Si hay uno más nuevo, Ajustes lo muestra con un link a las novedades y el engranaje se pone en verde hasta que actualices con 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.
• Colores del grafo: un color por tipo de nodo, o volver a blanco y negro.

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 profile.md, todas tus memorias activas (hasta ~12k caracteres), BRAIN.md y los fragmentos de chats anteriores más parecidos a tu pregunta.

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.

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. 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.

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

Todos 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, no "Connect to a URL": brain es un server local (stdio) y no expone una URL MCP. Apuntar una app a la dirección del dashboard devuelve 403.

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.

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 Mac, por ejemplo npx -y @modelcontextprotocol/server-github con GITHUB_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.

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 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:

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.

Tools MCP

Todas las tools que brain expone a tus agentes. Los errores vuelven como texto que empieza con Error:, nunca como excepciones.

Vault

Memoria

Conocimiento

Skills

Conexiones

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 update          actualiza a la última versión (git pull + uv sync)
brain path            muestra dónde está instalado
brain uninstall       saca el comando (tus datos quedan)
brain help            ayuda

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)
npx @modelcontextprotocol/inspector uv run python server.py   # Inspector MCP

Configuración

brain funciona sin configurar nada. Estas son las perillas y los archivos que usa.

Variables de entorno

Puertos

Archivos

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.

Privacidad y seguridad

Tus datos se quedan en tu Mac. brain solo sale a internet cuando guardás una URL o usás una conexión que habla con un servicio remoto.

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.

El dashboard

• Escucha solo en 127.0.0.1.
• Rechaza cualquier pedido cuyo Host no sea 127.0.0.1:<puerto> o localhost:<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).
• Cada escritura queda versionada y se puede deshacer.
• Las configs de los agentes nunca se reescriben sin backup, y nunca se borran entradas ajenas.

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.

Solución de problemas

Los problemas típicos y cómo resolverlos.

Servicios

Búsqueda y memoria

Agentes

Chat

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 el texto MIT y COMMONS-CLAUSE.md la condición. Están separados para que GitHub detecte la licencia base; juntos son la licencia de brain. Por la Commons Clause, brain no es "open source" según la definición de la OSI. Las versiones anteriores a v0.02.0 siguen bajo MIT puro.