Brain OS

Memoria operativa para agentes de IA que persiste entre sesiones y herramientas.

Documentación

Brain OS - AI remembers conversations but forgets project state

Servidor de memoria MCP local-first para el estado operativo del proyecto: decisiones, bloqueos, planes, patrones y próximos pasos.

Brain OS

brainos-hq.com

Tu IA recuerda conversaciones. Aún así olvida el estado del proyecto.

Brain OS brinda a los agentes estado operativo: decisiones, planes, bloqueos y prioridades que sobreviven entre sesiones.

¿Qué es esto?

Los agentes de IA son potentes dentro de una sesión, pero el trabajo de largo plazo tiene más estado que cualquier chat: lo que decidiste, lo que está bloqueado, lo que está activo y lo que no debería reabrirse. Brain OS brinda a los agentes estado operativo, no registros de conversación:

Entidades — rastrea proyectos, acuerdos, iniciativas con estado, impulso, bloqueos y próximos pasos
Decisiones — registra lo que se decidió, por qué, qué alternativas se rechazaron y cuándo revisitar
Patrones — detecta bloqueos recurrentes, trabajo obsoleto, señales de evasión y convergencia de temas
Enfoque — prioriza en qué trabajar según urgencia, impulso, apalancamiento y obsolescencia
Recuerdo semántico — busca memoria por significado, no solo por ID

Brain OS es un servidor MCP que funciona con cualquier cliente compatible con MCP: Claude Code, Cursor, Zed, GitHub Copilot, OpenAI Codex, Windsurf, o cualquier agente que hable el protocolo.

Cómo se ve en uso

Antes de que el agente actúe, puede verificar si una acción propuesta entra en conflicto con una decisión existente:

> decision_check({ proposal: "switch to Postgres for the new service" })

{
  "verdict": "conflict",
  "conflicting_decision": {
    "id": "dec_2026_03_14_db_choice",
    "decision": "Use SQLite for all local-first projects",
    "reason": "Lower ops burden, no infra to run, fits single-user scope",
    "rejected_alternatives": ["Postgres", "DuckDB"],
    "logged_at": "2026-03-14"
  },
  "guidance": "Re-litigating a settled choice. Surface the prior reasoning to the user before proceeding."
}

Esa es la cuña: estado estructurado con aplicación, para que los agentes dejen de reabrir preguntas que ya respondiste.

Inicio rápido

Requiere Node.js 20 o superior.

# In your project
npx brain-os init

Esto hace tres cosas:

Crea un directorio .brain/ con tus almacenes de entidades, decisiones y patrones.
Instala comandos de barra en .claude/commands/ para que puedas ejecutar /brain, /brain:focus, /brain:decide, etc. directamente en Claude Code. Los alias simples (/focus, /decide, etc.) se instalan junto para mayor brevedad.
Coloca archivos de puntero de instrucciones para agentes para que cualquier cliente compatible con MCP se comporte de manera consistente: AGENTS.md (canónico, entre herramientas) más archivos de puntero delgados para Claude Code (CLAUDE.md), GitHub Copilot (.github/copilot-instructions.md), Cursor (.cursor/rules/brain-os.mdc), Zed (.zed/rules.md) y Windsurf (.windsurfrules).

Banderas:

npx brain-os init --minimal — instala solo AGENTS.md + CLAUDE.md, omite los otros punteros de cliente (modo repositorio limpio)
npx brain-os init --no-commands — omite los comandos de barra (solo servidor MCP)
npx brain-os init --no-agent-instructions — omite todos los archivos de puntero de instrucciones para agentes

Conectar a Claude Code

claude mcp add brain-os -- npx brain-os serve

Conectar a Cursor / otros clientes MCP

Agrega a tu configuración MCP:

{
  "brain-os": {
    "command": "npx",
    "args": ["-y", "brain-os", "serve"]
  }
}

Configurar búsqueda semántica (opcional)

La herramienta semantic_recall necesita un proveedor de embeddings. Todo lo demás (entity_update, decision_log, plan_*, etc.) funciona sin uno.

Brain OS no instala un SDK de embeddings por defecto. Esto mantiene la instalación principal pequeña y evita arrastrar dependencias nativas de ONNX/Sharp a usuarios que no necesitan búsqueda semántica. Instala el proveedor opcional de OpenAI junto a brain-os, luego agrega BRAIN_EMBEDDINGS al entorno de tu servidor MCP:

npm install brain-os openai

Luego configura el proveedor en el entorno de tu servidor MCP:

{
  "brain-os": {
    "command": "npx",
    "args": ["-y", "brain-os", "serve"],
    "env": {
      "BRAIN_EMBEDDINGS": "openai",
      "OPENAI_API_KEY": "${OPENAI_API_KEY}"
    }
  }
}

Modo	Qué hace	Configuración
`local`	Temporalmente no disponible mientras el proveedor anterior arrastra avisos transitivos de alta severidad sin resolver.	Usa recuerdo por palabras clave o el proveedor de OpenAI hasta que se publique un backend local auditado.
`openai`	Usa `text-embedding-3-small` mediante la API de OpenAI. Más rápido que local. Cuesta ~$0.02 por millón de tokens.	Instala `openai`, establece `BRAIN_EMBEDDINGS=openai`, luego referencia `OPENAI_API_KEY` desde tu entorno de shell.

Si BRAIN_EMBEDDINGS no está establecido, el proveedor de OpenAI falta, o se solicita el modo local, semantic_recall devuelve un error de configuración claro. No ocurre instalación silenciosa de proveedor, descarga de modelo ni llamada a API. Las herramientas principales siguen funcionando normalmente.

Nunca pegues una clave sk-... cruda en tu configuración MCP. ~/.claude.json y archivos de configuración MCP similares son texto plano y fáciles de exponer en pantalla o en copias de seguridad. En su lugar, exporta la clave una vez en tu shell y refiérela desde el entorno del proceso MCP.

Herramientas

Herramienta	Descripción
`entity_read`	Lee el estado operativo de una o todas las entidades rastreadas
`entity_update`	Actualiza el estado de la entidad — estado, impulso, bloqueos, próximos pasos
`decision_log`	Registra una decisión estratégica con razonamiento y alternativas
`decision_check`	Verifica una acción propuesta contra decisiones activas — devuelve claro/precaución/conflicto
`decision_refresh`	Refresca una decisión existente: actualiza review_date, agrega evidencia, cambia estado. Solo metadatos — no muta el contenido de la decisión.
`decision_review`	Bandeja de deuda de revisión: agrupa decisiones vencidas (sigue siendo verdadera / cambiada / archivar / necesita evidencia) y recomienda una acción para cada una. Solo lectura — propone, tú confirmas. Detecta automáticamente decisiones duplicadas tipo stub.
`context_resolve`	Resuelve a qué entidad pertenece el trabajo actual, desde mención explícita / alias / archivos / señales léxicas. Determinista y con puntuación de confianza — enruta contexto conocido, nunca adivina intención.
`focus_get`	Obtén recomendaciones priorizadas sobre en qué trabajar
`project_evidence_scan`	Escaneo de solo lectura del estado operativo nativo de un repositorio (STATE.md, FLAGS, HANDOFF, ROADMAP/PLAN/TODO, actividad git, archivos sucios) para puertas humanas, próximos pasos y no tocar — fundamenta el enfoque en la realidad del repositorio.
`pattern_detect`	Analiza patrones en todas las entidades
`memory_check`	Audita la calidad de la memoria — señala datos obsoletos, contradicciones, ruido
`memory_commit`	Confirmación de fin de sesión — guarda todos los cambios de estado
`semantic_recall`	Busca memoria por significado usando lenguaje natural
`audit_log`	Lee el historial completo de mutaciones — qué cambió, cuándo, quién
`wrap_check`	Detecta si se han acumulado cambios de estado significativos desde el último wrap
`wrap_auto`	Wrap de red de seguridad no interactivo: aplica campos de bajo riesgo y prepara cambios de alto riesgo para revisión
`plan_set`	Establece un plan ordenado para una entidad — el paso 1 se convierte en el próximo paso activo
`plan_advance`	Completa u omite un paso (requiere evidencia/razón) — promueve automáticamente el siguiente
`plan_add`	Agrega pasos a un plan existente
`plan_read`	Ve el progreso del plan y el paso actual
`risk_assess`	Clasifica acciones riesgosas antes de la ejecución, incluidos riesgos de publicación pública y operaciones destructivas
`action_guard`	Aplica plantillas de guardia integradas a acciones comunes de alto riesgo antes de proceder

Comandos de barra

brain-os init instala comandos de barra en .claude/commands/ para que el agente tenga un vocabulario claro para trabajar con el estado operativo. Cada comando se instala en dos formas: /brain:* (forma canónica, documentada) y un alias simple (/decide, /focus, etc.) para brevedad de usuarios avanzados. /brain es la raíz del espacio de nombres y se instala una vez.

También instala:

BRAIN_OS_PROTOCOL.md en .claude/brain-os/PROTOCOL.md (proyecto) y ~/.claude/brain-os/PROTOCOL.md (usuario). El protocolo gobierna el enrutamiento de herramientas: cuando un agente ejecuta un comando de barra de Brain OS, lee el protocolo primero, luego llama a entity_read/plan_read/focus_get/etc. como principal. Los archivos pulse se convierten en respaldo solo.
Subagente brain-os-mode en .claude/agents/brain-os-mode.md. Cuando el agente principal delega trabajo de Brain OS a un subagente (p. ej., la herramienta Task de Claude Code), lo retoma bajo el mismo protocolo — sin riesgo de que los subagentes recurran a búsqueda genérica de archivos.
Gancho opcional de guardia de enrutamiento en templates/hooks/brain-os-routing-guard.py. Gancho PreToolUse opcional que advierte si se leen archivos pulse mientras existe un espacio de trabajo .brain/. Las instrucciones de instalación se imprimen mediante brain-os init.

Comando	Alias	Qué hace
`/brain`	—	Escáner de proyecto: visión general de todas las entidades, frescura, decisiones, alertas
`/brain:focus`	`/focus`	"¿En qué debería trabajar hoy, y por qué?" con evidencia
`/brain:decide`	`/decide`	Captura una decisión estratégica (con verificación de conflicto antes de registrar)
`/brain:strategy`	`/strategy`	Socio de pensamiento estratégico: piensa una decisión antes de construir
`/brain:wrap`	`/wrap`	Wrap de sesión: actualiza el estado de la entidad, captura decisiones, detecta cambios de impulso
`/brain:patterns`	`/patterns`	Detecta patrones entre entidades: bloqueos recurrentes, evasión, temas
`/brain:retro`	`/retro`	Retrospectiva semanal o mensual: qué se envió, qué se estancó, qué está oculto
`/brain:graph`	`/graph`	Muestra cómo se conectan las entidades, oportunidades de apalancamiento, decisiones compartidas

Instalación idempotente

Re-ejecutar init es seguro y consciente de reparación: los comandos existentes de Brain OS se conservan, y cualquier forma faltante se instala. Si una ruta de comando está ocupada por otra herramienta, esa ruta se omite y se informa — tu archivo nunca se sobrescribe. Puedes instalar Brain OS en un proyecto con comandos /decide o /focus existentes y las formas con espacio de nombres /brain:* aún se instalarán.

Cómo funciona

Brain OS almacena todo como archivos JSON locales en un directorio .brain/:

.brain/
  entities/     — one file per tracked entity
  decisions/    — decision log
  patterns/     — detected patterns
  config.json   — workspace settings

Sin nube. Sin base de datos. Sin cuenta. Tus datos permanecen en tu máquina.

¿Por qué sin interfaz de usuario?

La interfaz es el agente. Brain OS se lee y escribe mediante llamadas a herramientas MCP — /brain, /focus, /decide, decision_check, etc. — presentadas en línea por el cliente que uses (Claude Code, Cursor, etc.). No hay un panel separado que mantener abierto, ni una segunda pestaña para cambiar de contexto, ni estado de interfaz que pueda desviarse de los archivos subyacentes.

Esta es una elección de diseño, no una característica faltante. El estado de Brain OS vive al mismo nivel que tu código; el agente ya está allí, ya en la conversación, ya es la superficie correcta para preguntar "¿cuál es la prioridad ahora mismo?". Agregar un panel humano dividiría la atención entre dos interfaces para los mismos datos.

Si quieres una vista visual de un vistazo, .brain/ es JSON plano — renderízalo como quieras. El servidor MCP público permanece nativo para agentes por diseño.

Equipos y sincronización

Brain OS es de un solo usuario por diseño hoy. Pero como .brain/ son solo archivos JSON locales, los equipos pueden compartir un cerebro mediante cualquier sistema de archivos sincronizado — sin cambios de producto necesarios:

Enfoque	Pros	Contras
Git — confirma `.brain/` en el repositorio	Herramientas de diff/merge, historial de versiones, puntos de sincronización intencionales	`git pull` manual; conflictos de merge en ediciones simultáneas
Carpeta compartida de Dropbox / Drive	Casi en tiempo real, sin pasos manuales	Escrituras concurrentes pueden crear archivos de conflicto; `embeddings.json` reescribe a menudo
Montaje NFS / SMB / S3	Verdaderamente en tiempo real	Requiere configuración de infraestructura

Esto funciona sin sincronización integrada porque cada llamada a herramienta de Brain OS lee fresco desde el disco — no hay caché en memoria que invalidar. Lo que tu sistema de archivos sincronice, la siguiente llamada a herramienta lo ve. Aplica igual entre herramientas: registra una decisión desde Claude Code el lunes, abre Cursor el martes — mismo cerebro, ambos agentes.

La sincronización nativa cifrada para equipos con semántica de merge adecuada está en la hoja de ruta. La base local-first de hoy es lo que hace que esa federación sea aditiva, no un reajuste.

Estado auto-cargado

Cuando un cliente MCP se conecta, Brain OS expone un recurso brain://status con una visión operativa general: entidades activas, alertas, prioridad principal y decisiones recientes. El agente comienza cada sesión con contexto, no con amnesia.

Pruebas

Brain OS incluye un conjunto de pruebas de humo en tests/smoke.mjs, conectado a npm test y ejecutado en cada push por .github/workflows/audit.yml. Ejecuta localmente:

npm test

Cobertura actual (regresión + ruta feliz):

decision_log — colisión de tipos sin supersedencia, supersedes explícito funciona, supersedencia entre entidades rechazada
decision_check — el indicador solo de palabra clave permanece como precaución sin embeddings (sin STOPs falsos), comparación semántica asimétrica (faceta rechazada vs. elegida)
decision_refresh — limpia superseded_by pendiente cuando el estado transiciona fuera de superseded
plan_advance — sin promoción excesiva cuando ya existe un paso activo
entity_update — aplica el diff y registra cambios, crea entidad faltante, mode_reason requerido al estacionar, las actualizaciones solo de estado se aplican, los saltos de clasificación protegidos son visibles
semantic_recall — lanza EmbeddingsNotConfiguredError (no un Error genérico) cuando BRAIN_EMBEDDINGS no está configurado
Resolución de almacenamiento — falla cerrado en un cwd sin almacenamiento en lugar de crear silenciosamente un .brain/ vacío

Brechas conocidas (sin cobertura directa aún): puntuación de focus_get, heurísticas de pattern_detect, memory_*, plan_set/add/read y el recurso brain://status. Ampliar el conjunto está en la hoja de ruta.

Si encuentras un error, abre un issue con la herramienta, la entrada y la salida: ese es el camino más rápido hacia una solución.

Comunidad

Discord: discord.gg/9VBUGstjY — preguntas, comentarios, qué te falló, qué estás lanzando con Brain OS
Sitio web: brainos-hq.com
Issues: github.com/brainOS-HQ/brain-os/issues

Licencia

MIT