kin v0.6.4

subgraph surfaces["Access surfaces"]
    cli["kin CLI"]
    mcp["Kin MCP server"]
    editor["kin-editor for VS Code"]
end

daemon["kin daemon"]
authority["Graph authority<br/>entities, relations, changes, provenance"]
db["kin-db<br/>graph storage, snapshots,<br/>index, text and vector search"]
prims["kin-model, kin-blobs, kin-search,<br/>kin-vector, kin-infer, kin-lsp"]
vfs["kin-vfs<br/>transparent file projection"]
tools["Editors, compilers, build systems"]
git["Git<br/>import and export boundary"]
kinlab["KinLab<br/>hosted collaboration and control plane"]

people --> cli
people --> mcp
people --> editor
cli --> daemon
mcp --> daemon
editor --> daemon
daemon --> authority
authority --> db
db --> prims
authority <-->|"kin init imports, kin git export"| git
authority -->|"publish and sync"| kinlab
authority --> vfs
vfs --> tools

Под этими поверхностями находятся слои, из которых построена система:

| Слой | Роль |
| --- | --- |
| **[kin-db](https://github.com/firelock-ai/kin-db)** | Графовое хранилище, снимки, индексация, текстовый поиск и векторный поиск. |
| **[kin-model](https://github.com/firelock-ai/kin-model)** | Канонические типы и доменные модели, общие для всего стека. |
| **[kin-blobs](https://github.com/firelock-ai/kin-blobs)** | Хранилище блобов с адресацией по содержимому. |
| **[kin-search](https://github.com/firelock-ai/kin-search)** | Примитивы лексического поиска и поэтапное извлечение. |
| **[kin-vector](https://github.com/firelock-ai/kin-vector)** | Векторная подложка и поиск ближайших соседей. |
| **[kin-infer](https://github.com/firelock-ai/kin-infer)** | Подложка для инференса и эмбеддингов. |
| **[kin-lsp](https://github.com/firelock-ai/kin-lsp)** | Обогащение через языковой сервер, питающее семантический слой. |

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

## Открытый исходный код и экосистема Kin

Ядро Kin распространяется с открытым исходным кодом под лицензией Apache-2.0:
[kin](https://github.com/firelock-ai/kin),
[kin-db](https://github.com/firelock-ai/kin-db), [kin-vfs](https://github.com/firelock-ai/kin-vfs)
и [kin-editor](https://github.com/firelock-ai/kin-editor), а также вспомогательные
библиотеки kin-model, kin-blobs, kin-search, kin-vector, kin-infer, kin-lsp и
kin-actions.

[KinLab](https://kinlab.ai) — это проприетарный продукт, построенный на этом
открытом ядре: описанный выше хостируемый слой совместной работы и плоскости
управления.

Та же граница действует и в отношении обмена результатами бенчмарков.
[Спецификация бенчмарка и автономный верификатор пакетов без зависимостей](https://github.com/firelock-ai/kin-bench-spec)
являются публичными, поэтому утверждение можно проверить без доступа к системе,
которая его создала. Инфраструктура запуска и доказательств, которая формирует
запечатанные пакеты доказательств (оркестрация, шлюз доказательств с закреплёнными
релизами и хостируемая среда измерений), пока остаётся закрытой. Спецификация и
верификатор открываются первыми; раннер может быть открыт позже.

## Кратчайший путь на основе графа

Пять команд, и последняя — это ответ:```sh
curl -fsSL https://get.kinlab.dev/install | sh
exec "$SHELL" -l
cd /path/to/your/repository
kin init .
kin locate "where are webhook retries handled"

Используйте `kin setup --intent editor` для пути VS Code. Подтвердите итоговый
машиночитаемый контрольный список работоспособности с помощью `kin setup status --json`.

Установщик определяет [последний стабильный релиз](https://github.com/firelock-ai/kin/releases/latest),
проверяет его опубликованную SHA-256 контрольную сумму, устанавливает управляемые
бинарные файлы в `~/.kin` и запускает настройку. Запуск с явным `agent` интентом
настраивает встроенный MCP-сервер для обнаруженных поддерживаемых клиентов.
Используйте `--intent local` для использования CLI и файловой системы без
настройки MCP, или `--intent editor` для пути VS Code.

Чтобы удалить только интеграции, управляемые настройкой, выполните `kin setup uninstall`.
Для корневого каталога по умолчанию (`~/.kin`) `kin setup uninstall --all` также
останавливает все демоны Kin, удаляет точные блоки PATH из устаревшего установщика
и рекурсивно удаляет управляемую установку (`--dry-run` показывает предварительный
просмотр). Пользовательский `KIN_HOME` никогда не удаляется рекурсивно: сначала
выполните удаление в рамках ledger, затем вручную проверьте и удалите этот каталог.
Изменённые срезы, принадлежащие настройке, блокируют полное удаление, если не
добавить `--force`, поэтому удаление никогда не перезаписывает молча изменённую
пользователем конфигурацию клиента или оболочки. В Windows CLI планирует удаление
своего заблокированного каталога установки сразу после завершения работы процесса.
Windows намеренно сохраняет один инертный sidecar авторизации, доступный только
текущему пользователю; сохранение стабильной идентичности этой блокировки
предотвращает сбой или одновременную будущую установку, которая могла бы создать
два независимых органа мутации. CLI и JSON-результат раскрывают эти сохранённые
метаданные координации, а не заявляют о нулевых остаточных байтах.

Для ручной установки каждый архив и его файл `.sha256` публикуются по адресу
`https://github.com/firelock-ai/kin/releases/latest/download/`. Имена перемещаемых
артефактов: `kin-macos-aarch64`, `kin-macos-x86_64`, `kin-linux-aarch64`,
`kin-linux-x86_64` и `kin-windows-x86_64`; используйте суффикс `.tar.gz` для
архивов macOS и Linux и суффикс `.zip` для Windows, как показано на странице
последнего релиза. ZIP-файл для Windows также загружается установщиком PowerShell
и лаунчером npm.

Точка входа npm использует тот же публичный канал релизов:```sh
npm install -g @kinlab/kin@latest

Префикс пользователя находится в `PATH` вашей интерактивной оболочки и больше нигде. Скрипты, шаги CI,
`docker exec` и агентные клиенты его не наследуют, поэтому указывайте им абсолютный путь к
бинарному файлу, а не просто `kin`. См.
[Работа с вашим агентом](#works-with-your-agent) для описания регистрации.

То же самое касается Homebrew-тапа, который отслеживает тот же канал релизов:```sh
brew install firelock-ai/kin/kin

В обнаруженном Git-репозитории `kin init` атомарно принимает всю достижимую историю, ссылки, сырые объекты, точное рабочее дерево и политику допуска в авторитет графа repository-v6. Рабочее дерево с незакоммиченными правками, промежуточными изменениями или неотслеживаемыми файлами всё равно допускается: `kin init` принимает закоммиченное состояние и раскрывает, что именно оно не приняло. Оно никогда не подменяет снимок точного HEAD или семантическую пересборку на основе сырой файловой системы. Поддерживаемые локальные URL-адреса удалённых репозиториев, refspec-ы, отслеживание веток и настройки push по умолчанию фиксируются в конфигурации сосуществования Kin с Git; небезопасные, неоднозначные или неподдерживаемые настройки передачи завершаются с ошибкой до публикации.

Допуск также выводит семантический слой сущностей и связей для каждого поддерживаемого файла-источника сущностей в этой истории, и `kin init` сообщает долговечные, привязанные к поколению счётчики, которые оно зафиксировало. `kin status` сообщает об этом представлении авторитета репозитория; `kin graph status` отдельно сообщает об изменяемом живом графе запросов демона, который может включать более позднее производное обогащение. Поверхности запросов потребляют обогащение, принадлежащее графу, когда оно существует, и сообщают о его отсутствии, а не скрывают пробел за поиском по сырым файлам.

#### Какие файлы становятся сущностями

«Поддерживаемый файл-источник сущностей» означает файл, на который претендует один из языковых адаптеров Kin. Реестр адаптеров — это полный набор, и каждый файл в репозитории разрешается через него:

| Язык | Расширения |
| --- | --- |
| TypeScript | `.ts`, `.tsx` |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
| Python | `.py`, `.pyi` |
| Go | `.go` |
| Java | `.java` |
| Rust | `.rs` |
| C | `.c`, `.h` |
| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx` |
| C# | `.cs` |
| Ruby | `.rb` |
| PHP | `.php` |
| Swift | `.swift` |
| Kotlin | `.kt`, `.kts` |
| HCL / Terraform | `.tf`, `.tfvars` |

Файл `.h` читается как C++, когда его содержимое говорит об этом, поэтому проект на C++ не теряет пространства имён и шаблоны из-за грамматики C.

Всё остальное допускается как контент и остаётся доступным для запросов как история и текст, но не разбирается на сущности и связи. Сюда входят Markdown, HTML и CSS, SQL, YAML, JSON и TOML, shell-скрипты, Objective-C, Scala, Elixir, Dart, Lua, R, Zig, Haskell и Nix. Если ваш язык есть в этом списке, `locate` и `refs` не найдут в нём символы.

### 3. Задайте графу реальный вопрос```sh
kin locate "where are webhook retries handled"
kin refs ExactEntityName
kin trace ExactEntityName
kin overview

Что отличает это от наведения другого агента на MCP-сервер, так это то, что
правило применяется внутри агента, а не заимствуется из слоя разрешений
вендора. У него есть инструменты Kin плюс ровно два локальных: `edit_file` и
`write_file`. Нет ни shell, ни grep, ни инструмента чтения файлов, поэтому он
не может ответить на вопрос о репозитории на основе поиска по сырым файлам,
а инструмент, который он придумывает, отклоняется по имени. Когда Kin сообщает,
что пустому результату нельзя доверять, агенту говорят, что ответ неизвестен,
и называют конкретный пробел вместо того, чтобы заключить, что сущности не
существует. Каждое изменение выполняется внутри транзакции Kin в рамках
сессии Kin, поэтому изменение несёт происхождение с указанием агента. Сначала
запустите `kin agent doctor --base-url <url>`, чтобы проверить, что обе части
отвечают. Полную поверхность см. в
[справочнике CLI](https://github.com/firelock-ai/kin/blob/main/docs/cli-reference.md#kin-agent).

Работа с Claude Code, Codex, Cursor, Gemini и всем остальным, что говорит на
MCP, остаётся первоклассной. `kin setup --intent agent` настраивает каждый
обнаруженный клиент за один проход. Вот однострочники для каждого клиента,
если вы предпочитаете установить Kin напрямую.

Запустите `kin init .` в репозитории до подключения клиента, а не после. Эти
инструменты отвечают из графа, поэтому клиент, наведённый на каталог без графа,
получает поверхность инструментов, за которой ничего нет. `kin setup` сам об
этом говорит: его проверка с возвратом сообщает «no initialized Kin repository
at or above» каталога, в котором он выполнялся, и предлагает запустить там
`kin init` и повторить настройку.

Claude Code, изнутри сессии:```
/plugin marketplace add firelock-ai/kin
/plugin install kin@kin

Gemini CLI:```sh
gemini extensions install https://github.com/firelock-ai/kin

Kiro принимает то же самое в виде веб-ссылки:
[Add Kin to Kiro](https://kiro.dev/launch/mcp/add?name=kin&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40kinlab%2Fkin%22%2C%22mcp%22%2C%22start%22%5D%7D).

Cline принимает стандартную запись ниже, а не однострочную команду. Его CLI читает
`~/.cline/mcp.json`. В расширении VS Code откройте панель MCP Servers, затем
вкладку Configure, затем Configure MCP Servers и добавьте запись туда.

Каждый другой клиент, который читает стандартную конфигурацию MCP, принимает эту запись:```json
{
  "mcpServers": {
    "kin": { "command": "npx", "args": ["-y", "@kinlab/kin", "mcp", "start"] }
  }
}

Результат — `PASS`, `NEEDS ATTENTION` или `WOULD BLOCK`, и он сопровождается
влиянием Kin, выведенным из графа, контекстом, необходимым для исправления, и
доказательствами, стоящими за обоими. Авторство объявляется, а не проверяется. Команда не
заблокирует ваш merge и не изменит состояние графа. Она передаёт доказательства человеку или
политике CI и на этом останавливается.

## Как Kin соотносится с Git

Рядом с Git на сегодняшний день. Авторитет репозитория со временем. Во время внедрения в brownfield-проектах
Git остаётся явной границей интероперабельности импорта/экспорта; он никогда
не отвечает на запросы Kin во время выполнения и не исправляет отсутствующую истину графа.

- `kin init` импортирует полную достижимую историю Git и точные рёбра родителей.
  Kin намеренно не имеет режима инициализации с частичной историей или только снапшотами.
- После импорта граф Kin владеет идентичностью репозитория, состоянием дерева, историей, ссылками
  и семантическими отношениями. Представления файловой системы и Git — это проекции.
- `kin git export --output ../repo.git` записывает новую голую Git-проекцию из
  одного поколения авторитета, принадлежащего графу. Он не обращается к рабочим файлам или
  окружающему хранилищу объектов `.git/` и отказывается от существующего или находящегося в репозитории
  назначения. Объекты, ссылки и каталоги сбрасываются до того, как
  публикация в назначение без замены будет подтверждена. Публикация с привязкой к возможностям
  в настоящее время доступна на Unix-хостах; другие хосты отказываются до
  создания экспорта.

Это позволяет команде мигрировать существующий репозиторий, не отказываясь от своего редактора,
компилятора, системы сборки или интероперабельности с Git, пока Kin становится авторитетным.

## Платформа и зрелость

Основное ядро выполнения и проекция файловой системы имеют разные
границы поддержки:

| Платформа | Основное ядро Kin | Проекция `kin-vfs` |
| --- | --- | --- |
| macOS, Apple Silicon и Intel | Нативные граф, вектор, демон, настройка, MCP и поверхности обзора поставляются в архиве релиза. | Поставляется и проверяется на обеих архитектурах. Использует `DYLD_INSERT_LIBRARIES`; программы, защищённые SIP или hardened, могут отклонять инъекцию. |
| Linux x86_64 и arm64 | `kin` и `kin-daemon` — статические сборки musl, предназначенные для работы на дистрибутивах glibc и musl. | Публичный исполняемый файл VFS и шим — сборки GNU/glibc, а не musl. Они собраны с фиксированным минимальным glibc 2.31 и связываются с OpenSSL 3, поэтому хосту проекции нужны оба; Debian 12 загружает их, а Alpine и другие дистрибутивы musl не поддерживаются как хосты проекции. Релиз отказывается публиковать Linux-архив, бинарники которого запрашивают больше glibc, чем этот минимум. Доказательство релиза arm64 выполняется на Ubuntu 24.04. |
| Нативный Windows x86_64 | Ранняя поддержка: репозитории принимаются, а графовые и лексические запросы отвечают нативно, но рабочие процессы MCP и обзора ещё не покрыты сквозным доказательством установки. WSL2 остаётся рекомендуемым путём для полного Kin. | Не поставляется. Используйте WSL2 с дистрибутивом Linux, который соответствует границе glibc для проекции. |

Граф является авторитетом в каждом из вышеперечисленных случаев. Шим, NFS-монтирование, FUSE-монтирование
и Windows ProjFS — четыре способа увидеть эту истину как файлы, и Kin
выбирает между ними, проверяя, что может запустить этот хост: монтирование там, где оно
доступно, потому что ядро его обслуживает и ни один процесс не может его лишить,
с инъецированным шимом как резервным вариантом совместимости на macOS и Linux и
ProjFS в качестве основного на Windows, где шима не существует. `kin vfs on` включает выбранный
режим, `kin vfs off` отключает его, а `kin doctor` содержит строку, указывающую, какой
режим действует и работает ли он. Там, где режим отсутствует, Kin печатает
точную строку, которая устанавливает или включает его для вашей платформы.
[docs/projection.md](https://github.com/firelock-ai/kin/blob/main/docs/projection.md) содержит полную таблицу по платформам.

Первое индексирование читает всю достижимую историю Git, поэтому `kin init` на
большом или долгоживущем репозитории занимает минуты, а не секунды, прежде чем начнётся
встраивание. После возврата `init` демон продолжает подготовку в
фоновом режиме, и первые вызовы агента на большом репозитории могут занимать
заметно больше времени для ответа.

Ограниченное тестирование arm64 показало, что основной граф и лексический путь работают при 512 МБ,
но полное встраивание загружает модель примерно на 522 МБ и в настоящее время требует 2 ГБ как
безопасный операционный минимум; 1 ГБ — небезопасная граница, а 512 МБ может завершиться во время
встраивания. Это наблюдаемые ограничения альфа-версии, а не универсальные обещания размеров.

Успешный `kin --version` устанавливает только то, что основной бинарник запускается. Он
не устанавливает совместимость VFS или живую проекцию на основе графа. На поддерживаемом
Unix-хосте используйте `kin vfs status`, который проверяет каждый режим проекции и
печатает, что фактически действует, затем `kin setup status` и реальный
запуск `kin-vfs exec --workspace . -- <command>`. Запускатор VFS включает
канарейку интерпозиции и сообщает, когда операционная система удаляет шим.
[README kin-vfs](https://github.com/firelock-ai/kin-vfs#current-platform-and-package-boundaries)
содержит полную границу.

Артефакты релиза публикуются с контрольными суммами, а рабочий процесс релиза выполняет анонимную
установку, проверки демона/MCP, встраивания и реальной проекции VFS на основе графа
по всей своей матрице поддерживаемых раннеров. Сам рабочий процесс публичен:
[Install Proof](https://github.com/firelock-ai/kin/actions/workflows/install-proof.yml).
Зелёный релиз устанавливает именно эти артефакты и среды; это не
утверждение, что каждый дистрибутив, инструмент или форма репозитория уже покрыты.

## FAQ

### Заменяет ли Kin Git?

Рядом с Git на сегодняшний день. Авторитет репозитория со временем. Git остаётся явной
границей интероперабельности импорта/экспорта во время внедрения в brownfield-проектах, поэтому команда
может мигрировать существующий репозиторий, не отказываясь от своего редактора,
компилятора, системы сборки или интероперабельности с Git.

### Покидают ли мои данные мою машину?

Kin хранит локальную работу репозитория в вашей среде, поэтому приём репозитория,
хранение графа и локальные запросы выполняются там. KinLab — это отдельный
продукт, который добавляет хостинг совместной работы в рамках явных соглашений о доступе и раннем доступе.

### С какими агентами он работает?

Работа с Claude Code, Codex, Cursor, Gemini и всем остальным, что говорит на MCP,
остаётся приоритетной. `kin setup --intent agent` настраивает каждого клиента, который он обнаруживает,
за один проход.

### Блокирует ли он merge?

Обзор носит рекомендательный характер, поэтому он отмечает риски без блокировки, и решение о merge
остаётся за вашей командой. `kin review shadow` передаёт доказательства человеку или
политике CI и на этом останавливается.

## Позиция по доказательствам

Опубликованный предварительно зарегистрированный пакет доказательств Multi-SWE-Bench Go привязан к
более старой сборке, а не к движущемуся последнему релизу, и не устанавливает широкое
утверждение о скорости, экономии токенов или победе в категории. Сравнительные результаты здесь
не приводятся до независимой проверки.

Прочтите методологию, набор задач, идентичность сборки и артефакты в
[публичном пакете доказательств](https://firelock.ai/labs/kin-proof). Относитесь к утверждениям за пределами
этого измеренного объёма как к гипотезам, пока у них не будет собственного воспроизводимого доказательства.

## Публикации

Инженерные заметки о создании Kin, записанные так, чтобы посторонний мог их переиспользовать,
находятся на [kinlab.ai/blog](https://kinlab.ai/blog) с лентой на
[kinlab.ai/rss.xml](https://kinlab.ai/rss.xml).

- [Проверка, которая прошла, потому что ничего не измеряла](https://kinlab.ai/blog/checks-that-cannot-fail)
- [Ваш поиск по коду говорит, что ничего его не использует. Можно ли его удалить?](https://kinlab.ai/blog/empty-answer-safe-to-delete)

## Обучение и вклад

- [Краткое руководство и расширенная конфигурация](https://github.com/firelock-ai/kin/blob/main/docs/quickstart.md)
- [Размер хранилища и что его определяет](https://github.com/firelock-ai/kin/blob/main/docs/store-size.md)
- [Справочник инструментов MCP](https://github.com/firelock-ai/kin/blob/main/docs/mcp-tools.md)
- [Поддержка языков и что извлекает каждый уровень](https://github.com/firelock-ai/kin/blob/main/docs/language-support.md)
- [Справочник переменных окружения](https://github.com/firelock-ai/kin/blob/main/docs/env-vars.md)
- [Тезис «граф прежде всего»](https://github.com/firelock-ai/kin/blob/main/docs/thesis.md)
- [Модель авторитета записи и её переходное состояние](https://github.com/firelock-ai/kin/blob/main/docs/write-authority-model.md)
- [GitHub Discussions](https://github.com/firelock-ai/kin/discussions)
- [Отчёты об ошибках и запросы функций](https://github.com/firelock-ai/kin/issues/new/choose)
- [Руководство по вкладу](https://github.com/firelock-ai/kin/blob/main/CONTRIBUTING.md)
- [Приватное сообщение о безопасности](https://github.com/firelock-ai/kin/blob/main/SECURITY.md)

## Лицензия

[Apache-2.0](https://github.com/firelock-ai/kin/blob/main/LICENSE).

<p align="center"><em>Программное обеспечение, которое помнит себя.</em></p>