GZOO Cortex

GZOO Cortex

Локальный граф знаний для разработчиков. Отслеживает файлы ваших проектов, извлекает сущности и связи с помощью LLM и позволяет выполнять запросы ко всем вашим проектам на естественном языке.

«Какие архитектурные решения я принимал в разных проектах?»

Cortex находит решения в ваших README, TypeScript-файлах, конфигурационных файлах и экспортированных диалогах — а затем синтезирует ответ с цитированием источников.

Зачем это нужно

Вы работаете над несколькими проектами. Решения, паттерны и контекст разбросаны по сотням файлов. Вы забываете, что решили три месяца назад. Вы заново решаете проблемы, которые уже решали в другом репозитории.

Cortex отслеживает директории ваших проектов, автоматически извлекает знания и предоставляет их вам, когда они нужны.

Что он делает

• Отслеживает изменения в файлах проектов (md, ts, js, py, json, yaml)
• Извлекает сущности: решения, паттерны, компоненты, зависимости, ограничения, задачи
• Выводит связи между сущностями в разных проектах
• Обнаруживает противоречия, когда решения конфликтуют
• Выполняет запросы на естественном языке с цитированием источников
• Осуществляет семантический поиск — сочетает поиск по ключевым словам и векторное (эмбеддинговое) сходство, чтобы запросы совпадали по смыслу, а не только по ключевым словам (опционально; см. Семантический поиск)
• Интеллектуально маршрутизирует между облачными и локальными LLM
• Уважает конфиденциальность — ограниченные проекты никогда не покидают вашу машину
• Веб-панель с визуализацией графа знаний, живой лентой и обозревателем запросов
• MCP-сервер для прямой интеграции с Claude Code

Быстрый старт

1. Установка

npm install -g @gzoo/cortex

Если глобальная установка завершается ошибкой EACCES, используйте пользовательский префикс:

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @gzoo/cortex

Или установите из исходников:

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

Проверка: cortex --version (текущий релиз: 0.8.1)

2. Настройка

Запустите интерактивный мастер:

cortex init
cortex doctor                              # verify config, providers, and DB

Он проведет вас через:

• LLM-провайдер — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter или Ollama (локальный)
• API-ключ — безопасно сохраняется в ~/.cortex/.env
• Режим маршрутизации — cloud-first, hybrid, local-first или local-only
• Директории для отслеживания — какие директории Cortex должен мониторить
• Лимит бюджета — месячный лимит расходов на LLM

cortex init записывает глобальную конфигурацию в ~/.cortex/cortex.config.json. API-ключи хранятся в ~/.cortex/.env.

3. Регистрация проектов

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

4. Загрузка, отслеживание и запросы

Сначала выполните обратную загрузку существующих файлов — наблюдатель улавливает только новые изменения:

cortex ingest "~/projects/app/src/**/*.ts"   # one-shot backfill
cortex serve                                 # dashboard + API + file watcher (recommended)

Команда	Что делает
cortex serve	Веб-панель + API + файловый наблюдатель (ignoreInitial — без повторной загрузки при старте)
cortex watch	Файловый наблюдатель только для CLI (без панели)
cortex ingest	Разовая загрузка; события не отображаются в живой ленте

Не запускайте watch и serve вместе — они конкурируют за изменения файлов. Живая лента показывает события в реальном времени только от cortex serve (сохранения файлов во время работы сервера).

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. Веб-панель

cortex serve                               # open http://localhost:3710

Удаленный доступ:

cortex serve --host 0.0.0.0

Аутентификация автоматически применяется на хостах, отличных от localhost. Токен-носитель генерируется автоматически и сохраняется в ~/.cortex/.env (прочитайте его с помощью grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Откройте панель один раз с http://<host>:3710/?token=<token> — токен встраивается только для запросов, которые уже подтверждают владение им, и затем сохраняется для вкладки браузера (так что анонимные посетители никогда его не получают). Вызовы API/WebSocket за обратным прокси используют Authorization: Bearer <token>.

Исключение файлов и директорий

Cortex по умолчанию игнорирует node_modules, dist, .git и другие распространенные директории. Чтобы добавить еще:

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

Как это работает

Cortex запускает конвейер при каждом изменении файла:

1. Парсинг — содержимое файла разбивается на фрагменты парсером с учетом языка (tree-sitter для кода, remark для markdown)
2. Извлечение — LLM идентифицирует сущности (решения, компоненты, паттерны и т.д.)
3. Связывание — LLM выводит связи между новыми и существующими сущностями
4. Обнаружение — противоречия и дубликаты автоматически помечаются
5. Хранение — сущности, связи и векторы сохраняются в SQLite + LanceDB
6. Запросы — запросы на естественном языке ищут по графу и синтезируют ответы

Все данные остаются локально в ~/.cortex/. Только вызовы LLM API покидают вашу машину (и никогда для ограниченных проектов).

LLM-провайдеры

Cortex не зависит от провайдера. Он поддерживает:

• Anthropic Claude (Sonnet, Haiku) — через нативный Anthropic API
• Google Gemini — через API, совместимый с OpenAI
• DeepSeek (Reasoner, Chat) — сильное логическое мышление, очень доступная цена
• Groq — быстрое инференс с бесплатным тарифом
• Любой API, совместимый с OpenAI — OpenRouter, локальные прокси и т.д.
• Ollama (Mistral, Llama и др.) — полностью локально, облако не требуется

Отслеживание затрат использует тарифы с учетом провайдера для моделей DeepSeek, Gemini, Groq и OpenRouter — а не общий резервный вариант Anthropic.

Эмбеддинги (для семантического поиска) настраиваются как отдельный провайдер — независимо от вашей чат-модели — так что вы можете запускать чат на DeepSeek, а эмбеддинги на OpenAI. См. Семантический поиск.

Режимы маршрутизации

Режим	Затраты на облако	Качество	Требуется Ollama
cloud-first	Зависит от провайдера	Наивысшее	Нет
hybrid	Снижены	Высокое	Да
local-first	Минимальны	Хорошее	Да
local-only	$0	Хорошее	Да

В режиме cloud-first все задачи направляются вашему облачному провайдеру. Ollama не требуется и используется только при включенном резервном бюджете. Гибридный режим направляет высоконагруженные задачи (извлечение сущностей, ранжирование) в Ollama, а задачи, требующие логического мышления (вывод связей, запросы), — вашему облачному провайдеру.

Требования

• Node.js 20+
• API-ключ LLM для облачных режимов — Anthropic, Google Gemini, DeepSeek, Groq или любой провайдер, совместимый с OpenAI
• Ollama — только для режимов hybrid, local-first или local-only (установка)

Конфигурация

Конфигурация многослойная — более поздние источники переопределяют более ранние:

Приоритет	Расположение	Область действия
1	Встроенные значения по умолчанию	Глобальная
2	~/.cortex/cortex.config.json	Глобальная (создается cortex init)
3	./cortex.config.json	Переопределения проекта (опционально)
4	Переменные окружения CORTEX_*	Сессия

API-ключи хранятся отдельно в ~/.cortex/.env (никогда в JSON конфигурации).

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
cortex doctor                            # validate setup

Полный справочник по конфигурации: docs/configuration.md

Семантический поиск (Эмбеддинги)

Cortex сочетает поиск по ключевым словам (полнотекстовый) с векторным сходством, поэтому запросы совпадают по смыслу, а не по точным словам. Эмбеддинги опциональны и по умолчанию отключены — включите их с облачным провайдером эмбеддингов (локальный GPU или Ollama не требуются):

cortex config set llm.embeddings.enabled true
cortex config set llm.embeddings.baseUrl https://api.openai.com/v1
cortex config set llm.embeddings.model text-embedding-3-small
cortex config set llm.embeddings.apiKeySource env:OPENAI_API_KEY
cortex config set llm.embeddings.dimensions 1536
# then add the key to ~/.cortex/.env:
echo 'OPENAI_API_KEY=sk-...' >> ~/.cortex/.env

Провайдер эмбеддингов не зависит от вашего чат-провайдера — запускайте чат на DeepSeek (или Anthropic, Groq, …), а эмбеддинги на OpenAI. Любая конечная точка эмбеддингов, совместимая с OpenAI, работает.

Новые файлы автоматически эмбеддируются по мере их загрузки. Чтобы построить индекс для графа, который вы уже загрузили, запустите разовую переиндексацию:

cortex reindex                 # all projects
cortex reindex my-app          # a single project

Команды

Команда	Описание
cortex init	Интерактивный мастер настройки
cortex doctor	Проверка конфигурации, провайдеров, проектов, секретов и базы данных
cortex projects add/list/remove/show	Управление зарегистрированными проектами
cortex serve	Веб-панель + API + файловый наблюдатель (порт 3710)
cortex watch [project]	Файловый наблюдатель только для CLI
cortex ingest <file-or-glob>	Разовая загрузка файлов (отдельно от живой ленты)
cortex reindex [project]	Перестроить индекс семантического (эмбеддингового) поиска для существующих сущностей
cortex query <question>	Запрос на естественном языке с цитированием
cortex find <term>	Поиск сущностей по имени
cortex status	Статистика графа, затраты, статус провайдера
cortex costs	Детальная разбивка затрат
cortex contradictions	Список активных противоречий
cortex resolve <id>	Разрешить противоречие
cortex models list/pull/test/info	Управление моделями Ollama
cortex mcp	Запустить MCP-сервер для Claude Code
cortex report	Сводка после загрузки
cortex privacy set/list	Установить конфиденциальность директории
cortex config list/get/set/validate	Чтение/запись конфигурации
cortex config exclude add/remove/list	Управление исключениями файлов/директорий
cortex stop / cortex restart	Управление запущенными процессами наблюдения/обслуживания
cortex db	Операции с базой данных

Полный справочник CLI: docs/cli-reference.md

Веб-панель

Запустите cortex serve, чтобы открыть полноценную веб-панель по адресу http://localhost:3710 с:

• Главная панель — статистика графа, недавняя активность, разбивка по типам сущностей
• Граф знаний — интерактивный граф на D3-force с кластеризацией, клик для исследования
• Живая лента — события изменения файлов и извлечения сущностей в реальном времени через WebSocket (только от cortex serve)
• Обозреватель запросов — запросы на естественном языке с потоковыми ответами
• Разрешение противоречий — просмотр и разрешение конфликтующих решений

Удаленное развертывание

Для доступа за пределами localhost привяжитесь ко всем интерфейсам и поместите Cortex за обратный прокси:

cortex serve --host 0.0.0.0

Пример конфигурации nginx — защитите /api/ и /ws базовой аутентификацией; обслуживайте статические ресурсы без аутентификации (панель встраивает токен-носитель в HTML):

location /api/ {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_set_header Authorization "Bearer $CORTEX_TOKEN";
}

location /ws {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location / {
    auth_basic off;
    proxy_pass http://127.0.0.1:3710;
}

Установите CORTEX_SERVER_AUTH_TOKEN или server.auth.token в конфигурации. Когда аутентификация включена, Cortex встраивает токен в HTML панели, чтобы вызовы API и WebSocket аутентифицировались автоматически.

MCP-сервер (Интеграция с Claude Code)

Cortex включает MCP-сервер, чтобы Claude Code мог напрямую запрашивать ваш граф знаний:

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

Это дает Claude Code 12 инструментов:

Инструмент	Описание
cortex_ask	Вопросы на естественном языке о ваших проектах
get_status	Статус системы и статистика графа
list_projects	Список зарегистрированных проектов
find_entity	Поиск сущностей по имени
query_cortex	Структурированные запросы к графу знаний
get_contradictions	Список обнаруженных противоречий
resolve_contradiction	Разрешить противоречие
search_entities	Поиск сущностей с фильтрами
ingest_file	Запустить загрузку файлов
add_project	Зарегистрировать новый проект
remove_project	Отменить регистрацию проекта
session_brief	Сводка контекста для текущей сессии

Архитектура

Монорепозиторий с восемью пакетами:

• @cortex/core — типы, EventBus, загрузчик конфигурации, классы ошибок
• @cortex/ingest — парсеры файлов (tree-sitter + remark), разбивка на фрагменты, наблюдатель, конвейер
• @cortex/graph — хранилище SQLite, векторы LanceDB, движок запросов
• @cortex/llm — провайдеры Anthropic/Gemini/совместимые с OpenAI/Ollama, маршрутизатор, промпты, кэш
• @cortex/cli — CLI на Commander.js
• @cortex/mcp — сервер Model Context Protocol (транспорт stdio, 12 инструментов)
• @cortex/server — Express REST API + ретранслятор WebSocket
• @cortex/web — React + Vite + D3 веб-панель

Документация по архитектуре: docs/

Конфиденциальность и безопасность

• Файлы, классифицированные как restricted, никогда не отправляются облачным LLM
• Конфиденциальные файлы (.env, .pem, .key) автоматически обнаруживаются и блокируются
• Секреты API-ключей сканируются и редактируются перед любой передачей в облако
• Все данные хранятся локально в ~/.cortex/ — никакой телеметрии

Полная архитектура безопасности: docs/security.md

Создано с использованием

• SQLite через better-sqlite3 — хранение сущностей и связей
• LanceDB — векторные эмбеддинги для семантического поиска
• Anthropic Claude — облачный LLM-провайдер
• Google Gemini — облачный LLM-провайдер (через API, совместимое с OpenAI)
• DeepSeek — облачный LLM-провайдер (рассуждение + чат)
• Groq — быстрое облачное инференс-решение
• Ollama — локальное инференс-решение для LLM
• tree-sitter — языково-ориентированный разбор файлов
• Chokidar — кроссплатформенное отслеживание файлов
• Commander.js — фреймворк для CLI
• React + Vite — веб-панель управления
• D3 — визуализация графа знаний

Участие в разработке

Руководство по участию смотрите в CONTRIBUTING.md.

Лицензия

MIT — смотрите LICENSE

О проекте

Создано GZOO — платформой автоматизации бизнеса на базе ИИ.

Cortex начинался как внутренний инструмент для сохранения контекста между несколькими клиентскими проектами. Мы открыли его исходный код, потому что каждый разработчик, работающий более чем над одной задачей, теряет контекст, и мы считаем, что этот подход — автоматическое отслеживание файлов + граф знаний + запросы на естественном языке — является правильным способом решения этой проблемы.