brain
El recorrido guiado, y la puerta de entrada. Abre con la lista de cerebros que conoce esta máquina; al abrir uno caes en su lista de pasos. Necesita un terminal, porque hace preguntas — en un script, usa los comandos sueltos.
Documentación · Referencia
Todos los comandos, todos los flags.
La referencia completa del CLI brain, los fallos que son silenciosos en vez de ruidosos, y las preguntas que salen antes de que nadie instale nada.
Si un comando no hace lo que esperas, la tabla de resolución de problemas está ordenada por la frecuencia con la que muerde cada uno, no por gravedad.
Referencia de comandos
brain a secas cubre todo lo de abajo. Estos existen para scripts, para automatización, y para cuando sabes exactamente lo que quieres. Todos aceptan --help. La salida va con color y tabulada en un terminal, y en texto plano cuando se redirige, para que los logs queden limpios.
brain status responde a «¿esto está funcionando de verdad?»: cada fuente, si puede ejecutarse realmente, cuándo le toca, cuánto ha traído, y cómo de grande es el grafo. Cuando una fuente no puede ejecutarse, la tabla dice de qué tipo de «no está listo» se trata, en vez de obligarte a abrir ficheros para averiguarlo.brain new [proyecto]
Empieza un cerebro nuevo, saltándose la lista.
brain list
Todos los cerebros de esta máquina, en texto: progreso de configuración, número de fuentes, tamaño del grafo, última sincronización y ubicación. Una carpeta que se ha movido o se ha borrado se informa como ausente, no se descarta en silencio.
brain add [carpeta]
Registra un cerebro que ya existe — uno creado antes de que existiera la lista, o uno que llegó con un repositorio clonado. En un terminal, ejecútalo sin argumentos para buscar la carpeta.
brain forget <carpeta>
Saca un cerebro de la lista sin tocar nada de su interior. Los conectores, el grafo y los documentos replicados se quedan. brain add vuelve a poner la entrada.
brain init [proyecto]
Prepara una carpeta para recibir conectores: crea connectors/registry.yaml y connectors/state/, añade la salida generada a .gitignore, y añade connectors/ a .graphifyignore. Nunca sobrescribe un registro existente, así que se puede repetir sin miedo.
brain guide [proyecto]
Imprime los siete pasos, deduce del proyecto en disco cuáles están hechos, y da el comando exacto que toca. Es de solo lectura, así que se puede ejecutar en cualquier sitio — incluido desde un agente que necesite saber por dónde va un cerebro.
- --verbose
- Muestra también el detalle de los pasos ya completados.
brain status [proyecto]
Las fuentes registradas — tipo, si cada una puede ejecutarse de verdad, cuándo le toca, cuántos registros ha traído — y después el tamaño del grafo en nodos y aristas, y por dónde va la configuración.
brain presets
Lista los sistemas para los que brainiphy trae un conector terminado, y los datos de cuenta que necesita cada uno.
brain new-connector <proyecto> <nombre>
Escribe connectors/<nombre>/sync.py y lo registra en registry.yaml con su tipo y su intervalo. Los scripts existentes no se sobrescriben nunca.
- (ninguno)
- La plantilla genérica. Implementa fetch_records() y luego registra cualquier credencial con brain secret set.
- --mirror CARPETA
- Un conector completo que replica una carpeta local con rsync -a --delete. No hay nada que implementar.
- --preset NOMBRE
- Un conector terminado para un sistema que brainiphy ya conoce. Consulta brain presets.
- --api URL
- Una API REST sin preset. La paginación, los reintentos, el backoff y los permisos ya están escritos; tú añades una función collect_* por cada objeto.
- --var K=V
- Rellena una constante del script generado. Se aplica al final, así que puede sobrescribir un valor calculado como SECRET_ITEM.
- --interval-minutes N
- Cada cuánto le toca a esta fuente. Por defecto, 60.
brain sync [proyecto]
Ejecuta todos los conectores a los que les ha vencido el intervalo y después reconstruye el grafo — pero solo si al menos un conector llegó a ejecutarse. Imprime ran / skipped / errors / graph_rebuilt y sale con código distinto de cero si algún conector falló.
- --dry-run
- Informa de qué conectores tocan y de si sus scripts existen. No ejecuta ninguno.
- --full
- Fuerza un reindexado y una reconstrucción completos aunque no tocara nada. Va implícito en la primera construcción.
- --backend NOMBRE
- Fuerza un backend de modelo concreto para la pasada de indexado.
brain view [proyecto]
Abre el grafo interactivo de graphify en tu navegador. Si el dibujo es más viejo que el grafo, se redibuja antes, y eso no cuesta tokens.
brain connect-claude [proyecto]
Enchufa el grafo a Claude.
- (ninguno)
- Conecta Claude Code mediante CLAUDE.md y hooks. Es la opción por defecto, la de menos riesgo.
- --desktop
- Registra además un servidor MCP graphify-mcp en claude_desktop_config.json, apuntando al graph.json de este proyecto.
- --trust-desktop
- Añade el proyecto a localAgentModeTrustedFolders. Es aditivo: las entradas existentes no se sustituyen nunca.
brain schedule [proyecto] --interval-minutes N
Genera un LaunchAgent que ejecuta brain sync <proyecto> --full cada cierto intervalo. Los logs caen en connectors/logs/. Se niega a ejecutarse si el proyecto no tiene conectores registrados.
- --load
- Lo activa al momento. Sin esto solo escribe el plist e imprime el comando de launchctl.
brain secret set <item>
Guarda la credencial de un conector en el Llavero de macOS, pidiéndola con entrada oculta. La escritura se confirma releyéndola.
brain secret get <item>
Imprime una credencial guardada, en crudo, para redirigirla. Solo para depurar.
Para las partes que cambian menos a menudo — la disposición exacta en disco y el contrato del conector — mira un cerebro en disco y escribir un conector.
Resolución de problemas
Estos son los fallos silenciosos, no los ruidosos — aquellos en los que algo informa de éxito y el resultado sigue estando mal. Los errores ruidosos suelen decir lo que son.
La primera sincronización informa de un proyecto vacío, o de un grafo con casi nada dentro.
Por qué
graphify respeta .gitignore, y brain init mete raw/ ahí para que el material replicado del cliente no acabe nunca en un commit. Sin --no-gitignore, graphify se salta el corpus entero.
Arreglo
Usa brain sync, que pasa el flag por ti. Si estás llamando a graphify extract a mano, añade --no-gitignore.
Un cerebro programado sigue informando de éxito, pero el grafo deja de responder a preguntas nuevas.
Por qué
La pasada incremental graphify update solo indexa código. Un cerebro hecho de documentos necesita la pasada completa de extracción.
Arreglo
El LaunchAgent que escribe brain schedule ya pasa --full. Si escribiste tu propia entrada de cron, añádelo.
brain view muestra un dibujo que no cuadra con el grafo.
Por qué
graphify extract escribe graph.json sin redibujar graph.html, así que después de una reconstrucción completa el dibujo es el anterior.
Arreglo
brain view lo redibuja cuando está desfasado. Ejecuta brain view en vez de abrir graph.html directamente.
Una fuente aparece listada pero no se ejecuta, y el script está claramente ahí.
Por qué
Una plantilla sin la descarga escrita, y un preset al que le falta el identificador de cuenta, están las dos en disco y ninguna puede ejecutarse.
Arreglo
brain status dice de qué tipo de «no está listo» se trata. brain guide da el comando exacto para arreglarlo.
Un conector se autentica pero no devuelve nada para algunos objetos.
Por qué
La credencial no tiene permisos sobre esos objetos. Un permiso que falta puede parecer un fallo de autenticación.
Arreglo
Prueba el conector generado antes de sincronizar: informa de qué objetos puede leer realmente la credencial y no escribe nada.
Una credencial se da por guardada y luego falla en la siguiente ejecución automática.
Por qué
security de macOS puede salir con código 0 en una escritura que no guardó nada, o que guardó otro valor.
Arreglo
brain secret set ya relee el valor para confirmarlo. Si guardaste el item de otra forma, vuelve a ponerlo con brain secret set.
brain schedule se niega a ejecutarse.
Por qué
El proyecto no tiene conectores registrados.
Arreglo
Añade al menos una fuente primero. Programar un bucle de sincronización sin nada que sincronizar es una operación vacía y silenciosa, incómoda de depurar después.
Los scripts de los conectores aparecen en el grafo como código fuente.
Por qué
Falta connectors/ en .graphifyignore — normalmente porque se saltó brain init en un proyecto que ya tenía un registry.yaml.
Arreglo
Ejecuta brain init sobre el proyecto. Nunca sobrescribe un registro existente, así que no hay riesgo.
Preguntas frecuentes
¿Qué es graphify, y por qué va aparte?
graphify es el motor que convierte una carpeta de ficheros normalizados en un grafo de conocimiento. brainiphy es la capa que lo rodea: descubrir fuentes, escribir los conectores, mantenerlos sincronizados y enchufar el resultado a Claude. Tenerlos separados hace que graphify siga siendo una herramienta de grafos general y que brainiphy siga siendo reemplazable a su alrededor. El instalador te trae graphify.
¿Por qué solo macOS?
Dos dependencias duras: las credenciales van al Llavero de macOS, y la programación es un LaunchAgent de launchd. Todo lo demás es Python corriente. Los ports son bienvenidos — es MIT.
Mi CRM no es el preset que traéis. ¿Y ahora qué?
Entonces es una API REST, y --api <url-base> genera un conector con la parte de red ya hecha. Tú escribes una función por cada tipo de registro — o se lo pides a Claude, que para eso existe la skill. Si no es una API en absoluto, la plantilla básica se conforma con una función que devuelva registros.
¿Se sube algo a algún sitio?
No. Las fuentes se leen en local o desde sus propias APIs y se indexan en tu máquina. Lo único que sale es lo que envías cuando un modelo indexa tus documentos — la misma frontera de confianza que ya aceptaste al usar Claude.
¿Re-sincronizar va a duplicarlo todo?
No. Los ficheros se nombran con un slug estable del ID remoto de cada registro, así que volver a sincronizar sobrescribe en el sitio. Las carpetas replicadas usan rsync --delete, así que un fichero borrado en el origen deja de ser un nodo.
¿Puedo pasarle un cerebro a un compañero?
Sí — es una carpeta. Que la copie, y brain add se la pone en su lista. Lo que no viaja son las credenciales, que están en su propio Llavero y no en la carpeta.
¿Quitar un cerebro borra los datos de mi cliente?
No, y es deliberado. brain forget y la tecla d de la aplicación solo quitan la entrada de la lista. Los conectores, los documentos replicados y el grafo se quedan exactamente donde estaban. Borrarlos de verdad es rm.
¿Cómo me deshago de brainiphy?
bash install.sh --uninstall. Elimina el virtualenv, los dos accesos en ~/.local/bin, el bloque marcado de tu perfil de shell, y el enlace de la skill. Tus cerebros son carpetas tuyas y se quedan como están.