GZOO Cortex

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

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

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

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

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

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

Related MCP server: Graft

Что он делает

• Отслеживает изменения в файлах проекта (md, ts, js, json, yaml)

• Извлекает сущности: решения, паттерны, компоненты, зависимости, ограничения, задачи

• Выводит связи между сущностями в разных проектах

• Обнаруживает противоречия, когда решения конфликтуют

• Выполняет запросы на естественном языке с указанием источников

• Интеллектуально маршрутизирует запросы между облачными и локальными LLM

• Соблюдает конфиденциальность — ограниченные проекты никогда не покидают ваш компьютер

• Веб-панель с визуализацией графа знаний, лентой событий в реальном времени и проводником запросов

• MCP-сервер для прямой интеграции с Claude Code

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

1. Установка

npm install -g @gzoo/cortex

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

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

2. Настройка

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

cortex init

Он поможет вам настроить:

• Провайдер LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter или Ollama (локально)

• API-ключ — сохраняется безопасно в ~/.cortex/.env

• Режим маршрутизации — облачный, гибридный, локальный или только локальный

• Директории для отслеживания — какие папки должен мониторить Cortex

• Бюджетный лимит — ежемесячный лимит расходов на LLM

Конфигурация хранится в ~/.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 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. Веб-панель

cortex serve                               # open http://localhost:3710

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

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/. Только вызовы API LLM покидают ваш компьютер (и никогда для проектов с ограниченным доступом).

Провайдеры LLM

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

• Anthropic Claude (Sonnet, Haiku) — через нативный API Anthropic

• Google Gemini — через API, совместимый с OpenAI

• DeepSeek (Reasoner, Chat) — мощные рассуждения, очень доступно

• Groq — быстрое выполнение с бесплатным уровнем

• Любой API, совместимый с OpenAI — OpenRouter, локальные прокси и т.д.

• Ollama (Mistral, Llama и др.) — полностью локально, облако не требуется

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

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

Требования

• Node.js 20+

• API-ключ LLM для облачных режимов — Anthropic, Google Gemini, DeepSeek, Groq или любой провайдер, совместимый с OpenAI

• Ollama (для гибридного/локального режимов) — установить

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

Вся конфигурация находится в ~/.cortex/cortex.config.json. API-ключи — в ~/.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

Полное руководство по конфигурации: docs/configuration.md

Команды

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

Веб-панель

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

• Главная панель — статистика графа, недавняя активность, разбивка по типам сущностей

• Граф знаний — интерактивный граф D3-force с кластеризацией, кликабельный для исследования

• Лента событий — события изменения файлов и извлечения сущностей в реальном времени через WebSocket

• Проводник запросов — запросы на естественном языке с потоковыми ответами

• Разрешение противоречий — просмотр и разрешение конфликтующих решений

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

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

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

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

Архитектура

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

• @cortex/core — типы, шина событий, загрузчик конфигурации, классы ошибок

• @cortex/ingest — парсеры файлов (tree-sitter + remark), чанкер, наблюдатель, конвейер

• @cortex/graph — хранилище SQLite, векторы LanceDB, движок запросов

• @cortex/llm — провайдеры Anthropic/Gemini/OpenAI-compatible/Ollama, маршрутизатор, промпты, кэш

• @cortex/cli — CLI на базе Commander.js с 18 командами

• @cortex/mcp — сервер протокола Model Context Protocol (транспорт stdio, 12 инструментов)

• @cortex/server — REST API на Express + ретранслятор 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 начинался как внутренний инструмент для поддержания контекста в нескольких клиентских проектах. Мы сделали его открытым, потому что каждый разработчик, работающий над более чем одной задачей, теряет контекст, и мы считаем, что этот подход — автоматическое отслеживание файлов + граф знаний + запросы на естественном языке — является правильным способом решения этой проблемы.