Open Brain

Tu infraestructura de conocimiento personal. Captura pensamientos desde cualquier lugar, busca por significado.

Open Brain almacena tus pensamientos con embeddings generados por IA para que cualquier asistente de IA pueda buscar en tu memoria por significado, no por palabras clave. Los pensamientos fluyen desde Telegram, tuberías automatizadas o cualquier cliente de IA compatible con MCP (Claude, ChatGPT y otros) y son buscables al instante. Un grafo de conocimiento enlaza automáticamente pensamientos relacionados, extrae entidades y rastrea patrones de coocurrencia. El mantenimiento automatizado mantiene el grafo saludable: deduplicando casi duplicados, rastreando la evolución de los temas, sintetizando ideas y archivando contenido obsoleto.

Todo reside en tu propia base de datos, por lo que eres dueño de tus datos.

Cómo funciona

flowchart LR
    TG[Telegram Message] --> TGBot[telegram-bot\nEdge Function]
    MCP[AI Client\nClaude/ChatGPT] --> MCPServer[open-brain-mcp\nEdge Function]
    Pipeline[RSS/HF Papers/\nEmergent Mind] --> RunPipeline[run-pipeline\nEdge Function]
    TGBot --> OR1[OpenRouter\nEmbedding + Metadata]
    MCPServer --> OR2[OpenRouter\nEmbedding + Search]
    RunPipeline --> OR3[OpenRouter\nTriage + Embed]
    OR1 --> DB[(Postgres\n+ pgvector)]
    OR2 --> DB
    OR3 --> DB
    MCPServer --> DB
    TGBot --> TGReply[Telegram Reply\nwith Metadata]

Ruta de captura

Cuando envías un mensaje al bot de Telegram, la Edge Function telegram-bot lo recoge mediante un webhook. Envía el mensaje a OpenRouter en paralelo para dos cosas: generar un embedding vectorial (una representación numérica del significado) y extraer metadatos como temas, personas mencionadas, elementos de acción, tema, puntuación de calidad y entidades nombradas. Se comprueba si el pensamiento es un duplicado semántico, se almacena en tu base de datos con conexiones auto-enlazadas a pensamientos relacionados, y el bot responde con un resumen de lo que capturó.

Ruta de la tubería (Pipeline)

La Edge Function run-pipeline ingiere automáticamente ideas de feeds RSS (boletines de IA), artículos diarios de Hugging Face y Emergent Mind (artículos de arXiv en tendencia). Cada elemento se clasifica por relevancia, se embebe, se deduplica y se almacena. Se ejecuta según un horario mediante GitHub Actions (despliegue en Supabase) o un contenedor cron integrado (despliegue en Docker).

Ruta de recuperación

Cualquier cliente de IA conectado mediante MCP (Model Context Protocol) puede buscar en tus pensamientos por significado usando búsqueda semántica, navegar por filtros (tipo, tema, persona, tiempo), obtener estadísticas agregadas o solicitar una revisión semanal de temas. La Edge Function open-brain-mcp maneja estas solicitudes, autenticada con tu clave de acceso personal.

Grafo de conocimiento

Cada pensamiento se enlaza automáticamente a pensamientos relacionados mediante similitud vectorial. Las conexiones con una similitud superior a 0.80 son clasificadas por un LLM en relaciones tipificadas (extiende, contradice, es-evidencia-para, reemplaza). Las entidades nombradas (personas, herramientas, proyectos, organizaciones) se extraen y resuelven en un grafo de entidades compartido. Los bordes de coocurrencia rastrean qué pensamientos se recuperan juntos a lo largo del tiempo, fortaleciendo las conexiones basadas en patrones de uso reales.

Almacenamiento

Todo reside en Postgres con pgvector para una búsqueda de similitud rápida. Los pensamientos se almacenan con sus embeddings (vectores de 1536 dimensiones), metadatos, conexiones tipificadas y referencias a entidades. Puedes desplegar en Supabase (alojamiento gestionado) o auto-alojar con Docker Compose.

Opciones de despliegue

Elige cómo quieres ejecutar Open Brain:

Despliegue en Supabase

Requisitos previos

1. Cuenta de Supabase -- Supabase es una base de datos Postgres alojada con APIs integradas, autenticación y Edge Functions (código sin servidor). Crea una cuenta gratuita en supabase.com. Crea un nuevo proyecto; necesitarás la URL del proyecto (se ve como https://abcdef.supabase.co) y la clave de rol de servicio (una cadena larga que se encuentra en Configuración > API).

2. CLI de Supabase -- La herramienta de línea de comandos para gestionar tu proyecto de Supabase (aplicar migraciones de base de datos, desplegar funciones, establecer secretos).

   npm install -g supabase

3. Cuenta de OpenRouter -- OpenRouter enruta las solicitudes a modelos de IA. Se utiliza aquí para generar embeddings (representaciones vectoriales de tus pensamientos) y extraer metadatos. Crea una cuenta en openrouter.ai y genera una clave API desde el panel de control.

4. Bot de Telegram (recomendado) -- La forma principal de capturar pensamientos sobre la marcha. Crea un bot a través de @BotFather en Telegram y ejecuta el script de configuración (ver abajo). Si solo quieres acceso MCP, puedes saltarte esto.

Inicio rápido

1. Clonar el repositorio

git clone https://github.com/YOUR_USERNAME/open_brain.git
cd open_brain

2. Vincular tu proyecto de Supabase

cd supabase
supabase link --project-ref YOUR_PROJECT_REF
cd ..

Consejo: Tu referencia de proyecto es el subdominio en tu URL de Supabase. Si tu URL es https://abcdef.supabase.co, tu referencia de proyecto es abcdef.

3. Ejecutar bootstrap

./scripts/bootstrap.sh

Bootstrap te guía a través de la configuración de tu entorno. Solicita cada secreto (URL de Supabase, clave de rol de servicio, clave API de OpenRouter, tokens de Telegram, etc.), genera automáticamente una clave de acceso MCP criptográfica y escribe todo en .env.local. Si ya tienes un .env.local, mostrará tus valores existentes y te permitirá actualizar los específicos.

4. Ejecutar deploy

./scripts/deploy.sh

Deploy aplica el esquema de la base de datos (crea la tabla de pensamientos con índices de búsqueda vectorial), sube tus secretos a Supabase y despliega todas las Edge Functions. Muestra una lista de verificación paso a paso a medida que se completa cada operación. Al final, imprime tu URL de conexión MCP y un comando de Claude Code listo para pegar.

5. Ejecutar validate

./scripts/validate.sh

Validate ejecuta 8 comprobaciones contra tu despliegue en vivo para confirmar que todo funciona: acceso a la base de datos, funciones RPC, accesibilidad de Edge Functions, autenticación, captura de pensamientos, búsqueda semántica y listado de pensamientos. Imprime una lista de verificación con éxito/fallo para cada comprobación y un resumen final.

Configurar el bot de Telegram (opcional)

Crea un bot a través de @BotFather en Telegram, luego ejecuta el script de configuración:

./scripts/setup-telegram.sh YOUR_BOT_TOKEN

El script verifica tu token, registra el webhook, configura el autocompletado de comandos e imprime las variables de entorno y secretos a configurar. Sigue las instrucciones impresas para completar la configuración.

Conecta tu cliente de IA

Una vez desplegado, conecta tu cliente de IA para empezar a usar Open Brain. Necesitas dos valores:

• URL del endpoint MCP: https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp (Supabase) o http://localhost:80/functions/v1/open-brain-mcp (Docker)

• Clave de acceso MCP: La clave generada durante la configuración (almacenada en .env.local o .env de Docker)

Consejo: El script de despliegue (Supabase) o el script de inicio (Docker) imprime el comando de conexión exacto con tus valores rellenados.

Claude Code (CLI -- recomendado)

claude mcp add --transport http --header "x-brain-key: YOUR_MCP_KEY" open-brain https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp

Esto registra Open Brain como un servidor MCP que Claude Code puede usar en cualquier conversación. Reemplaza YOUR_MCP_KEY y YOUR_REF con tus valores reales.

Claude Code (proyecto .mcp.json)

Añade esto a un archivo .mcp.json en la raíz de tu proyecto para compartir la conexión con tu equipo:

{
  "mcpServers": {
    "open-brain": {
      "type": "http",
      "url": "https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp",
      "headers": {
        "x-brain-key": "${MCP_ACCESS_KEY}"
      }
    }
  }
}

Nota: La sintaxis ${MCP_ACCESS_KEY} utiliza la expansión de variables de entorno para que tu clave se mantenga fuera del control de versiones. Establece la variable de entorno MCP_ACCESS_KEY en cada máquina que utilice esta configuración.

Claude Desktop

Claude Desktop no admite servidores MCP remotos a través de archivos de configuración. En su lugar:

1. Abre Claude Desktop > Settings > Connectors

2. Haz clic en Add a new connector

3. Introduce la URL del endpoint MCP: https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp

4. Configura la cabecera de autenticación x-brain-key con tu clave de acceso MCP

ChatGPT (Pro/Team/Enterprise/Edu)

1. Ve a Settings > Connectors > Advanced > Developer Mode

2. Añade la URL del servidor MCP: https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp

3. Configura la cabecera de autenticación x-brain-key con tu clave de acceso MCP

Ejemplos de uso

Captura en Telegram

Envía cualquier mensaje a tu bot y Open Brain lo procesa automáticamente:

You: Just had a great meeting with Sarah about the Q3 product roadmap.
     She wants to prioritize the mobile app redesign.

Bot: Captured!
  Type: meeting_note
  Theme: personal
  Topics: q3-roadmap, mobile-app-redesign
  Quality: 0.7
  People: Sarah
  Action items: Prioritize mobile app redesign
  Why: Records a product strategy decision with clear ownership
  Related: "Product planning session notes..." (82% similar)

Cada mensaje se embebe como un vector, se enriquece con metadatos extraídos, se comprueba si hay duplicados, se auto-enlaza a pensamientos relacionados y las entidades se resuelven en un grafo de conocimiento.

Búsqueda semántica

Pide a cualquier cliente de IA conectado que busque en tu cerebro:

You: Search my brain for anything about product roadmap discussions

Claude: I found 3 relevant thoughts:
  1. (0.89 similarity) Meeting with Sarah about Q3 product roadmap...
  2. (0.82 similarity) Product planning session notes...
  3. (0.76 similarity) Quarterly goals discussion...

La búsqueda semántica encuentra pensamientos por significado, incluso si usaste palabras diferentes. Preguntar sobre "planificación de producto" encontrará pensamientos sobre "discusiones de hoja de ruta" porque los significados son similares.

Revisión semanal

Obtén un resumen generado por IA de tu pensamiento reciente:

You: Give me a weekly review of my recent thoughts

Claude: Here's your weekly review:
  Themes: Product planning, team meetings, technical architecture
  Open loops: Mobile redesign decision pending, API migration timeline
  Connections: Sarah mentioned in 3 meetings this week, all about mobile

La revisión semanal analiza los últimos 7 días de pensamientos y sintetiza temas, bucles abiertos, conexiones entre ideas y lagunas en tu pensamiento.

Herramientas disponibles

Consulta docs/cookbook.md para patrones de uso detallados, composiciones de herramientas y comportamientos no obvios.

Habilidades (Flujos de trabajo de Claude Code)

Open Brain incluye habilidades de Claude Code: flujos de trabajo estructurados de múltiples fases que componen las herramientas MCP anteriores en un análisis de nivel superior. Las habilidades se descubren automáticamente desde .claude/skills/ y se invocan como comandos de barra diagonal.

Consulta docs/skills/README.md para descripciones detalladas y uso.

Mantenimiento automatizado

Open Brain ejecuta mantenimiento en segundo plano para mantener el grafo de conocimiento saludable. Estos trabajos se ejecutan automáticamente, mediante GitHub Actions (despliegue en Supabase) o el contenedor cron integrado (despliegue en Docker).

Los archivos de flujo de trabajo de GitHub Actions se incluyen en docs/workflows/ como referencia para personalizar los horarios.

Benchmark

Open Brain incluye un arnés de benchmark LongMemEval que mide la calidad de recuperación a través de 500 preguntas en 6 categorías. Cada pregunta obtiene su propio cerebro aislado: las conversaciones se ingieren como pensamientos, luego las preguntas prueban si se pueden recuperar y responder los recuerdos correctos.

Resultados de referencia (umbral=0.4, límite=20, expansión de grafo activada):

La búsqueda vectorial maneja bien el recuerdo factual directo. La síntesis multisesión y el razonamiento temporal son las principales áreas de mejora