GZOO Cortex

Grafo de conocimiento local para desarrolladores. Monitoriza los archivos de tu proyecto, extrae entidades y relaciones utilizando LLMs, y te permite realizar consultas en lenguaje natural entre todos tus proyectos.

“¿Qué decisiones de arquitectura he tomado en mis proyectos?”

Cortex encuentra decisiones en tus archivos README, archivos TypeScript, archivos de configuración y exportaciones de conversaciones, y luego sintetiza una respuesta con citas de las fuentes.

Por qué

Trabajas en múltiples proyectos. Las decisiones, los patrones y el contexto están dispersos en cientos de archivos. Olvidas lo que decidiste hace tres meses. Vuelves a resolver problemas que ya resolviste en otro repositorio.

Cortex monitoriza los directorios de tus proyectos, extrae el conocimiento automáticamente y te lo devuelve cuando lo necesitas.

Related MCP server: agentmako

Qué hace

• Monitoriza tus archivos de proyecto (md, ts, js, json, yaml) en busca de cambios

• Extrae entidades: decisiones, patrones, componentes, dependencias, restricciones, elementos de acción

• Infiere relaciones entre entidades a través de proyectos

• Detecta contradicciones cuando las decisiones entran en conflicto

• Consulta en lenguaje natural con citas de las fuentes

• Enruta de forma inteligente entre LLMs en la nube y locales

• Respeta la privacidad: los proyectos restringidos nunca salen de tu máquina

• Panel web con visualización de grafo de conocimiento, feed en vivo y explorador de consultas

• Servidor MCP para integración directa con Claude Code

Inicio rápido

1. Instalación

npm install -g @gzoo/cortex

O instala desde el código fuente:

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

2. Configuración

Ejecuta el asistente interactivo:

cortex init

Esto te guiará a través de:

• Proveedor de LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter u Ollama (local)

• Clave API — guardada de forma segura en ~/.cortex/.env

• Modo de enrutamiento — cloud-first, hybrid, local-first o local-only

• Directorios de monitorización — qué directorios debe supervisar Cortex

• Límite de presupuesto — tope de gasto mensual en LLM

La configuración se almacena en ~/.cortex/cortex.config.json. Las claves API van en ~/.cortex/.env.

3. Registrar proyectos

cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list                       # verify

4. Monitorizar y consultar

cortex watch                               # start watching for changes
cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions

5. Panel web

cortex serve                               # open http://localhost:3710

Excluir archivos y directorios

Cortex ignora node_modules, dist, .git y otros directorios comunes por defecto. Para añadir más:

cortex config exclude add docs             # exclude a directory
cortex config exclude add "*.log"          # exclude by pattern
cortex config exclude list                 # see all excludes
cortex config exclude remove docs          # remove an exclude

Cómo funciona

Cortex ejecuta una tubería en cada cambio de archivo:

1. Analizar — el contenido del archivo se divide en fragmentos mediante un analizador consciente del lenguaje (tree-sitter para código, remark para markdown)

2. Extraer — el LLM identifica entidades (decisiones, componentes, patrones, etc.)

3. Relacionar — el LLM infiere relaciones entre entidades nuevas y existentes

4. Detectar — las contradicciones y duplicados se marcan automáticamente

5. Almacenar — las entidades, relaciones y vectores van a SQLite + LanceDB

6. Consultar — las consultas en lenguaje natural buscan en el grafo y sintetizan respuestas

Todos los datos permanecen locales en ~/.cortex/. Solo las llamadas a la API de LLM salen de tu máquina (y nunca para proyectos restringidos).

Proveedores de LLM

Cortex es agnóstico al proveedor. Soporta:

• Anthropic Claude (Sonnet, Haiku) — vía API nativa de Anthropic

• Google Gemini — vía API compatible con OpenAI

• DeepSeek (Reasoner, Chat) — razonamiento sólido, muy asequible

• Groq — inferencia rápida con nivel gratuito

• Cualquier API compatible con OpenAI — OpenRouter, proxies locales, etc.

• Ollama (Mistral, Llama, etc.) — totalmente local, no requiere nube

Modos de enrutamiento

El modo híbrido enruta las tareas de gran volumen (extracción de entidades, clasificación) a Ollama y las tareas que requieren mucho razonamiento (inferencia de relaciones, consultas) a tu proveedor en la nube.

Requisitos

• Node.js 20+

• Clave API de LLM para modos en la nube — Anthropic, Google Gemini, DeepSeek, Groq o cualquier proveedor compatible con OpenAI

• Ollama (para modos híbrido/local) — instalar

Configuración

Toda la configuración reside en ~/.cortex/cortex.config.json. Las claves API están en ~/.cortex/.env.

cortex config list                       # see all non-default settings
cortex config set llm.mode hybrid        # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10  # set budget
cortex config exclude add vendor         # exclude a directory from watching
cortex privacy set ~/clients restricted  # mark directory as restricted

Referencia completa de configuración: docs/configuration.md

Comandos

Referencia completa de CLI: docs/cli-reference.md

Panel web

Ejecuta cortex serve para abrir un panel web completo en http://localhost:3710 con:

• Inicio del panel — estadísticas del grafo, actividad reciente, desglose por tipo de entidad

• Grafo de conocimiento — grafo interactivo D3-force con agrupación, haz clic para explorar

• Feed en vivo — eventos de cambio de archivo y extracción de entidades en tiempo real vía WebSocket

• Explorador de consultas — consultas en lenguaje natural con respuestas en streaming

• Resolutor de contradicciones — revisa y resuelve decisiones en conflicto

Servidor MCP (Integración con Claude Code)

Cortex incluye un servidor MCP para que Claude Code pueda consultar tu grafo de conocimiento directamente:

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

Esto le da a Claude Code 12 herramientas:

Arquitectura

Monorepo con ocho paquetes:

• @cortex/core — tipos, EventBus, cargador de configuración, clases de error

• @cortex/ingest — analizadores de archivos (tree-sitter + remark), fragmentador, monitor, tubería

• @cortex/graph — almacén SQLite, vectores LanceDB, motor de consultas

• @cortex/llm — proveedores Anthropic/Gemini/compatible con OpenAI/Ollama, enrutador, prompts, caché

• @cortex/cli — CLI de Commander.js con 18 comandos

• @cortex/mcp — servidor del Protocolo de Contexto de Modelo (transporte stdio, 12 herramientas)

• @cortex/server — API REST de Express + relé WebSocket

• @cortex/web — panel web React + Vite + D3

Documentación de arquitectura: docs/

Privacidad y seguridad

• Los archivos clasificados como restricted nunca se envían a LLMs en la nube

• Los archivos sensibles (.env, .pem, .key) se detectan automáticamente y se bloquean

• Los secretos de las claves API se escanean y redactan antes de cualquier transmisión a la nube

• Todos los datos se almacenan localmente en ~/.cortex/ — nada se comunica con el exterior

Arquitectura de seguridad completa: docs/security.md

Construido con

• SQLite vía better-sqlite3 — almacenamiento de entidades y relaciones

• LanceDB — incrustaciones vectoriales para búsqueda semántica

• Anthropic Claude — proveedor de LLM en la nube

• Google Gemini — proveedor de LLM en la nube (vía API compatible con OpenAI)

• DeepSeek — proveedor de LLM en la nube (razonamiento + chat)

• Groq — inferencia rápida en la nube

• Ollama — inferencia de LLM local

• tree-sitter — análisis de archivos consciente del lenguaje

• Chokidar — monitorización de archivos multiplataforma

• Commander.js — marco de trabajo CLI

• React + Vite — panel web

• D3 — visualización de grafo de conocimiento

Contribución

Consulta CONTRIBUTING.md para ver las directrices.

Licencia

MIT — ver LICENSE

Acerca de

Construido por GZOO — una plataforma de automatización empresarial impulsada por IA.

Cortex comenzó como una herramienta interna para mantener el contexto en múltiples proyectos de clientes. Lo hemos hecho de código abierto porque todo desarrollador que trabaja en más de una cosa pierde el contexto, y creemos que este enfoque — monitorización automática de archivos + grafo de conocimiento + consultas en lenguaje natural — es la forma correcta de resolverlo.