knowing — самоадаптирующийся движок понимания кода

Самоадаптирующийся движок понимания кода. Наблюдает за плотностью собственного графа и автоматически подстраивает стратегию извлечения данных. 38 типов рёбер, 28 MCP-инструментов, 263 класса эквивалентности, криптографические доказательства. Становится умнее с ростом масштаба, а не хуже.

Основан на опубликованном исследовании: Content-Addressing as a Computation Primitive for Software Relationship Intelligence (DOI: 10.5281/zenodo.20342255)

Ваша архитектурная схема говорит, что сервис A вызывает сервис B. Можете это доказать?

knowing может. Он строит контентно-адресованный граф извлечённых связей в коде, делает снимок в виде дерева Меркля, привязанного к git-коммиту, и генерирует криптографические доказательства, проверяемые офлайн. Агенты используют его для ранжированного контекста. Команды безопасности — для аудита. Платформенные команды — чтобы сравнивать код с трассами продакшена.

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

brew install blackwell-systems/tap/knowing

{ "mcpServers": { "knowing": { "command": "knowing", "args": ["mcp", "--watch"] } } }

Вот и всё. MCP-сервер автоматически индексирует репозиторий при первом запуске. API-ключи не нужны, загрузки моделей не нужны. Ваш агент теперь имеет ранжированный контекст, радиус поражения, область покрытия тестами и неявное шумоподавление, которое улучшает результаты в активных сессиях.

Убедитесь, что всё работает: Спросите агента: «Используй инструмент context_for_task, чтобы найти символы, связанные с [чем-то, что точно есть в вашем коде].»

Три продукта на одной архитектуре

knowing — это три продукта, построенных на одном фундаменте (контентно-адресованный граф с иерархическими деревьями Меркля):

1. Движок контекста для AI-агентов
Один вызов возвращает наиболее релевантные символы для задачи, отсортированные по центральности в графе, актуальности и изученной полезности, упакованные под ваш токенный бюджет. 263 класса эквивалентности фреймворков устраняют разрывы в словарном запасе, когда ключевые слова не срабатывают. На 47% меньше вызовов инструментов. На 84% меньше токенов. Результаты улучшаются с обратной связью.

2. Примитив аудита для соответствия требованиям
Каждое состояние графа — это корень Меркля, привязанный к git-коммиту. knowing prove генерирует криптографическое доказательство существования связи. knowing verify проверяет его офлайн. knowing fsck верифицирует весь граф за 98 мс. Обнаружение цепочек поставок извлекает рёбра доступа к учётным данным, запуска процессов и сетевой эксфильтрации для выявления структурно подозрительного кода.

3. Шумоподавление, которое обучается
Символы, возвращённые агенту, но не использованные им, понижаются в рейтинге при последующих запросах. При изменении кода обратная связь автоматически аннулируется (проверяется через корни Меркля пакетов). Система становится точнее в активных сессиях. Именно ради этого свойства и создан knowing.

Это не отдельные функции. Они — структурные следствия контентной адресации: тот же хэш, который делает контекст кэшируемым, делает его и доказуемым, а тот же корень Меркля, который обнаруживает устаревание, аннулирует устаревшую обратную связь.

На какие вопросы отвечает

Для вашего агента:

• «Я меняю эту функцию. Что сломается?» (радиус поражения: вызывающий код, тесты, маршруты, репозитории)
• «Дай мне 50 000 токенов контекста для этой задачи.» (ранжирование по графу, а не grep-поиск)
• «Какие тесты нужно запустить?» (обход графа вызовов, точность 98%)

Для платформенной команды:

• «Используется ли этот маршрут в продакшене?» (статический анализ + трассы OTel runtime)
• «Как выглядел граф сервисов в конкретном снимке?» (цепочка снимков, каждый корень привязан к git-коммиту)

Для команды безопасности:

• «Докажи, что сервис A вызывает сервис B в этом коммите.» (доказательство Меркля, проверяемо офлайн)
• «Докажи, что эта зависимость НЕ существует.» (доказательство отсутствия через отсортированные листья)
• «Сгенерируй отчёт о соответствии.» (knowing audit -proofs, одна команда)
• «Этот пакет читает учётные данные и запускает процессы?» (knowing audit-supply-chain --scan-all)

Цифры

Метрика	Результат
Кросс-системное извлечение	P@10=0.330 при холодном старте (302 задачи, 17 репозиториев, 8 языков)
Против конкурентов	3.79× codegraph (19K звёзд), 6.00× GitNexus, 6.35× Gortex, 22.0× grep
Классы эквивалентности	277 вручную подобранных + изученных из использования, +57% P@10
Шумоподавление	Неявная обратная связь по кластерам: R@10 +5.2%, MRR +12.6%
Экономия вызовов инструментов	На 47% меньше (один вызов контекста заменяет цикл grep+read)
Экономия токенов	На 84% меньше токенов (формат GCF)
Скорость повторных запросов	В 93× быстрее (кэш подграфов по ключу Меркля)
Разностное сравнение Меркля	В 517× быстрее полного сканирования рёбер при 100K рёбрах
Область покрытия тестами	Точность 98%, полнота 82%
Проверка целостности графа	98 мс (24 936 рёбер)
Генерация доказательства	72 мкс генерация, 1.2 мкс верификация
Аннулирование обратной связи	100% при изменении кода, накладные расходы 11%
Пропускная способность индексации	16 репозиториев (8 языков) за ~60 с
Типы рёбер	38 (включая цепочку поставок: reads_env, executes_process)

Все бенчмарки воспроизводимы. Кросс-системный бенчмарк использует 17 репозиториев, зафиксированных на точных коммитах, с манифестом корпуса и скриптом настройки для полного воспроизведения с нуля.

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

Путь A: MCP-сервер (рекомендуется для AI-агентов)

# 1. Установка
brew install blackwell-systems/tap/knowing
# Или: npm install -g @blackwell-systems/knowing
# Или: pip install knowing
# Или: go install github.com/blackwell-systems/knowing/cmd/knowing@latest

# 2. Добавьте в конфиг агента (.mcp.json, настройки Claude Code и т.д.)
#    Сервер автоматически индексирует репозиторий при первом запуске.

Путь B: CLI (исследование графа самостоятельно)

# 1. Установка (как выше)
brew install blackwell-systems/tap/knowing

# 2. Индексация репозитория
knowing add .

# 3. Проверка, что индексирование прошло успешно
knowing stats

# 4. Получение контекста для задачи
knowing context -task "refactor auth middleware" -format gcf

# 5. Проверка целостности графа
knowing fsck

Другие CLI-команды

# Найти затронутые тесты
knowing test-scope -files internal/auth/middleware.go

# Объяснить, почему символ оказался на этом месте
knowing why -task "refactor auth" -symbol "SessionHandler"

# Доказать существование связи (криптографическое доказательство Меркля)
knowing prove -source "AuthService" -target "SessionStore"

# Верифицировать офлайн (без базы данных)
knowing verify proof.json

# Проверить, устарел ли граф (CI-заглушка: завершается с кодом 1, если устарел)
knowing stale

# Аудит цепочки поставок (сканирование всех файлов на подозрительные паттерны)
knowing audit-supply-chain --scan-all

# Удалить репозиторий (удаляет все данные: узлы, рёбра, снимки, обратную связь)
knowing remove ./path/to/repo

Настройка MCP-интеграции

Добавьте MCP-сервер в конфиг вашего агента. Конфигурация одинакова для всех клиентов, различается только путь к файлу:

Агент	Файл конфига
Claude Code	.mcp.json (корень проекта) или ~/.claude/mcp.json (глобально)
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code (Copilot, Continue, Cline, Roo)	.vscode/mcp.json
Zed	~/.config/zed/settings.json, раздел "context_servers"
Codex (OpenAI)	codex.json или флаг --mcp-config
JetBrains	Settings > Tools > MCP Servers

{
  "mcpServers": {
    "knowing": {
      "command": "knowing",
      "args": ["mcp", "--watch"],
      "transport": "stdio"
    }
  }
}

Флаг --watch переиндексирует при изменении файлов. Агент всегда работает со свежими данными.

Что получает агент: Ключевой инструмент — context_for_task. Когда агент вызывает его с описанием задачи, knowing возвращает ранжированные релевантные символы кода, упакованные в токенный бюджет. Это заменяет циклы grep-read. Другие полезные инструменты: blast_radius (что сломается?), test_scope (какие тесты запустить?), explain_symbol (почему этот символ здесь?). Полный список — в MCP Tools Reference (28 инструментов).

Для HTTP transport (многоагентный режим, демон):

knowing serve -addr :8100 .

{
  "mcpServers": {
    "knowing": {
      "url": "http://localhost:8100",
      "transport": "streamable-http"
    }
  }
}

Почему это работает

Git версионирует файлы. knowing версионирует понимание кода.

Вся система построена на одной идее: контентно-адресованная идентичность. Каждый символ, каждая связь и каждый снимок хэшируются по SHA-256. Это единственное решение даёт вам бесплатно:

• Обнаружение устаревания. Изменённый файл = новый хэш = устаревшие рёбра известны без сканирования.
• Кэширование. Тот же корень пакета = те же результаты. Ускорение в 93× на неизменённых запросах.
• Целостность. Верификация всех хранимых хэшей и непрерывности цепочки снимков. 98 мс.
• История. Каждый снимок — корень Меркля, привязанный к git-коммиту. Проходите по цепочке.
• Аннулирование обратной связи. Обратная связь хранит корень Меркля пакета. Код изменился = корень изменился = старая обратная связь невидима.
• Доказательства. Путь Меркля от листа к корню — самодостаточное криптографическое доказательство.

Поддерживаемые языки и форматы

Язык/Формат	Экстрактор	Обнаружение фреймворков
Go	tree-sitter + go/packages + SCIP	net/http, gin, echo, chi, gorilla/mux
TypeScript/JavaScript	tree-sitter	Express.js, Fastify, Hono, NestJS, Next.js
Python	tree-sitter	Flask, FastAPI, Django
Rust	tree-sitter	Actix, Axum, Rocket
Java	tree-sitter	Spring annotations
C#	tree-sitter	ASP.NET attributes
Protocol Buffers	tree-sitter	service, message, enum, RPC
Terraform (HCL)	tree-sitter	resource, data, module, variable
SQL	tree-sitter	таблицы, представления, функции, FK-рёбра
Kubernetes YAML	yaml.v3	deployments, services, configmaps
CloudFormation/SAM	yaml.v3	resources, !Ref/!GetAtt/!Sub перекрёстные ссылки
Docker Compose	yaml.v3	services, ports, networks, depends_on
GitHub Actions	yaml.v3	workflows, jobs, steps, action references
CSS/SCSS	tree-sitter	селекторы, var() зависимости
OpenAPI/JSON Schema	json/yaml	endpoints, models, $ref resolution
Dockerfile	парсер	FROM образы, многоэтапные COPY --from зависимости
Ruby	tree-sitter	классы, модули, методы, require-рёбра
GraphQL	парсер	типы, поля, интерфейсы

MCP-инструменты

Инструмент	Назначение
index_repo, graph_query, repo_graph	Построение и инспекция графа
cross_repo_callers, blast_radius, trace_dataflow, flow_between	Понимание влияния и путей
snapshot_diff, semantic_diff, pr_impact, stale_edges	Сравнение состояний графа, анализ изменений
runtime_traffic, dead_routes, trace_stats	Запрос связей, наблюдаемых в runtime
context_for_task, context_for_files, context_for_pr, explain_symbol	Ранжированный контекст для агентов
ownership, test_scope, communities, plan_turn, feedback	Маршрутизация, владельцы кода, выбор тестов, улучшение ранжирования
prove, prove_absent, fsck	Криптографические доказательства, доказательства отсутствия, проверка целостности
untrack_repo	Удаление всех данных репозитория

MCP-ресурсы

8 ресурсов только для чтения — ориентация агента без вызова инструментов:

Ресурс	Возвращает
knowing://report	Размер графа, топ-типы, количество горячих точек, возраст снимка
knowing://schema	Типы узлов, типы рёбер, уровни провенанса, формат хэша
knowing://stats	Счётчики по репозиторию, типу и типу ребра
knowing://repos	Все отслеживаемые репозитории с счётчиками и временем последней индексации
knowing://session	Вызовы контекста, обслуженные символы, попадания/промахи кэша, аптайм
knowing://index-health	Статус: healthy/stale/corrupted, результат проверки целостности
knowing://communities	Список сообществ с связностью и корнями Меркля
knowing://community/{id}	Детали одного сообщества

Форматы передачи данных

Формат	Назначение	Экономия vs JSON
GCF (Graph Compact Format)	Потребление LLM: строчно-ориентированный, позиционные поля	На 84% меньше токенов
GCB (Graph Compact Binary)	Транспорт и кэширование: varint, length-prefixed	На 74% меньше байт
JSON	Отладка для человека, универсальные потребители	Базовый

Документация

Документ	Содержание
Introduction	Принцип работы, пайплайн извлечения, пятиминутный обзор
Architecture	Архитектура системы, схемы, контентная адресация, модель демона
Audit & Compliance	Доказательства Меркля, fsck, цепочка снимков, CI-заглушки
CLI Reference	Команды, флаги, примеры, устранение неполадок
MCP Tools	Схемы инструментов, параметры, форматы возврата
Edge Types	Семантика связей и провенанс
Context Packing	RWR, HITS, ранжирование, токенное бюджетирование
Benchmarks	Воспроизводимые бенчмарки с контрактами производительности

Лицензия

MIT