cortex

Un cerebro autoalojado para un hogar o un equipo: un panel donde las personas chatean entre sí y con un agente que ha leído sus notas compartidas — con tu propio modelo, en tu propia máquina.

Estado: alfa. La API y la superficie de configuración se están asentando; espera cambios incompatibles entre versiones menores. Los formatos de índice y checkpoint son cachés desechables — eliminar .cortex/ pierde conversaciones, nunca notas.

pip install cortxai
cortex setup                 # wizard: brain dir, model endpoint, admin account
cortex serve --host 0.0.0.0  # dashboard on :8642

O bash install.sh (autodetección de pipx/uv/venv), o docker compose up después de la configuración única cortex setup /brain documentada en docker-compose.yml.

Lo que no hace: cortex no aloja ningún modelo — tú aportas un endpoint: Ollama, vLLM, LM Studio, un proxy LiteLLM, OpenRouter o la API de Anthropic. La búsqueda vectorial es coseno exacto en proceso, adecuada para cerebros de tamaño personal y de equipo, incorrecta para millones de fragmentos. Las ediciones del vault son de último escritor gana con detección de conflictos (un 409 y un banner), no una fusión de nivel git. El conector de calendario aún no expande reglas de recurrencia.

El panel

• Chat — hilos privados con el agente. Busca antes de responder, transmite sus llamadas a herramientas (⚙ search_brain … ✓ 33ms) y cita archivos por ruta; al hacer clic en una cita se abre en la vista del vault.

• Canales — chat entre pares para las personas del cerebro. Menciona a @cortex y el agente responde en el canal, leyendo solo el vault compartido — nunca el vault personal de nadie.

• Vault — vaults compartidos y personales, editados en el navegador con renderizado estilo Obsidian: [[wikilinks]], ![[embeds]], > [!note] callouts, frontmatter, casillas de tareas que escriben de vuelta, #tags. Ctrl-S guarda; una edición concurrente recibe un banner de conflicto, no una sobrescritura silenciosa.

• Importar — trae un vault de Obsidian existente como subida zip, una URL de git o una ruta del servidor. Se omiten .obsidian/, .git/ y los tipos de archivo que no son de vault.

• Administración — cuentas (admin / member), estadísticas del índice.

Las cuentas son nombre de usuario + contraseña (scrypt), las sesiones son cookies HttpOnly. Cada usuario ve el vault compartido, su propio vault y las fuentes de conectores — la búsqueda, grep y el agente están limitados por solicitud, filtrados dentro de la consulta en lugar de recortados después.

Related MCP server: claudecode-mcp

La pila del agente

El agente ReAct de LangGraph sobre modelos de chat de LangChain, con estado de conversación en un checkpoint AsyncSqliteSaver por hilo:

providers:
  local:
    kind: openai                    # Ollama, vLLM, LM Studio — one wire
    base_url: "http://localhost:11434/v1"
    chat_model: qwen3
    embed_model: nomic-embed-text
  router:
    kind: openrouter                # cloud aggregator, OpenAI wire
    api_key_env: OPENROUTER_API_KEY
    chat_model: anthropic/claude-sonnet-5
  claude:
    kind: anthropic                 # direct Anthropic Messages API
    api_key_env: ANTHROPIC_API_KEY
    chat_model: claude-sonnet-5
roles:
  chat: router
  embed: local

Un proxy LiteLLM es kind: litellm con su base_url — su enrutamiento y política de respaldo permanecen en el proxy, por lo que cortex no lleva el SDK de LiteLLM. Los endpoints se clasifican por hechos de red: las direcciones privadas, de loopback, CGNAT y Tailscale son de confianza; cualquier dirección pública recibe una advertencia clara de que tus notas saldrán de la red.

La recuperación es híbrida: SQLite FTS5 y coseno vectorial clasificados por separado, fusionados con fusión de rango recíproco, ajustados por recencia — el diseño de la base de conocimiento de Cerebras. El índice se reconstruye desde cero cuando cambia el esquema de fragmentos o el modelo de embeddings, porque mezclar silenciosamente espacios vectoriales es corrupción. Sin endpoint de embeddings significa búsqueda de texto completo que lo dice, no puntuaciones vectoriales falsas.

Cuatro formas de extenderlo

Una extensión rota se informa y se aísla, nunca es fatal. El registro no es autorización: una herramienta que toca algo sensible mantiene sus propias comprobaciones dentro del invocable.

Gestiona desde el panel. El panel Extender, solo para administradores, lista cada plugin, skill, conector y servidor MCP con lo que proporciona, su error de carga si lo tiene, y un interruptor de habilitación que nunca edita tu archivo fuente. Puedes escribir un plugin o conector en el navegador: se carga antes de guardarse, por lo que el código que no importa se rechaza con el mensaje del propio cargador en lugar de romper silenciosamente el siguiente turno, y un guardado exitoso reconstruye el agente para que la nueva herramienta esté activa sin reiniciar. Los conectores tienen un cuadro de configuración y un botón "Ejecutar ahora"; los servidores MCP tienen un formulario. Los servidores definidos en cortex.yaml aparecen de solo lectura — el archivo sigue siendo el propietario de lo que declara.

Guardar un plugin o conector ejecuta ese código en el servidor como el usuario de cortex. Ese es el mismo nivel de confianza que configurar un servidor MCP stdio, y es por eso que el panel es solo para administradores. Desde la terminal, cortex ext list, cortex ext disable plugin <name> y cortex ext delete hacen la misma gestión sin el navegador.

Cortex también es un servidor MCP — claude mcp add home-brain -- cortex mcp --brain ~/brain da a Claude Code, Cursor o Hermes el mismo registro de herramientas, al alcance del propietario de la máquina.

Estructura de un cerebro

~/brain/
├── cortex.yaml        # providers, roles, mcp servers, connectors
├── vaults/shared/     # everyone's notes
├── vaults/<user>/     # each user's private vault
├── sources/           # connector output
├── skills/ plugins/ connectors/
└── .cortex/           # index, checkpoints, usage.jsonl — disposable cache

Haz una copia de seguridad copiando la carpeta. Cerebro de casa, cerebro de empresa, cerebro de club: tres carpetas, tres procesos cortex serve.

Observabilidad

Cada llamada de modelo y herramienta añade JSONL a .cortex/usage.jsonl con prompt_tokens/completion_tokens cuando el endpoint los informa — los recuentos ausentes permanecen ausentes en lugar de convertirse en ceros, que es lo que preflight espera para la calibración. La telemetría nunca hace fallar una llamada.

Desarrollo

uv venv --python 3.12 && uv pip install -e '.[dev]'
.venv/bin/pytest                    # 102 tests
.venv/bin/ruff check src tests
cd web && npm install && npm run dev   # SPA dev server, proxies to :8642

El contrato del frontend vive en docs/product-spec.md; publicar una versión está en RELEASING.md.

Docs: unchained-labs.github.io/cortex · Marca: Unchained-Labs/branding · Licencia: MIT