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

Sous ces surfaces se trouvent les couches dont le système est constitué :

| Couche | Rôle |
| --- | --- |
| **[kin-db](https://github.com/firelock-ai/kin-db)** | Stockage de graphes, instantanés, indexation, recherche textuelle et recherche vectorielle. |
| **[kin-model](https://github.com/firelock-ai/kin-model)** | Types canoniques et modèles de domaine partagés sur l'ensemble de la pile. |
| **[kin-blobs](https://github.com/firelock-ai/kin-blobs)** | Stockage de blobs adressables par contenu. |
| **[kin-search](https://github.com/firelock-ai/kin-search)** | Primitives de recherche lexicale et récupération par étapes. |
| **[kin-vector](https://github.com/firelock-ai/kin-vector)** | Substrat vectoriel et des plus proches voisins. |
| **[kin-infer](https://github.com/firelock-ai/kin-infer)** | Substrat d'inférence et d'embedding. |
| **[kin-lsp](https://github.com/firelock-ai/kin-lsp)** | Enrichissement par language-server alimentant la couche sémantique. |

Ce sont des couches d'implémentation d'un seul système, et non des produits
distincts qu'un nouvel utilisateur doit assembler. Aucune d'entre elles n'est
installée séparément.

## Open source et l'écosystème Kin

Le cœur de Kin est open source sous licence 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),
et [kin-editor](https://github.com/firelock-ai/kin-editor), ainsi que les
bibliothèques de support kin-model, kin-blobs, kin-search, kin-vector, kin-infer,
kin-lsp et kin-actions.

[KinLab](https://kinlab.ai) est un produit propriétaire construit sur ce cœur
open source : la couche hébergée de collaboration et de plan de contrôle décrite
ci-dessus.

La même frontière s'applique à la manière dont les travaux de benchmark sont
partagés. La [spécification de benchmark et un vérificateur autonome de bundles,
sans dépendances](https://github.com/firelock-ai/kin-bench-spec) sont publics, de
sorte qu'une affirmation peut être vérifiée sans accès au système qui l'a
produite. L'infrastructure d'exécution et de preuve qui génère des bundles de
preuves scellés (l'orchestration, la porte de preuve de version épinglée et
l'environnement de mesure hébergé) reste privée pour l'instant. La spécification
et le vérificateur s'ouvrent en premier ; l'exécuteur pourra s'ouvrir plus tard.

## Le chemin le plus court basé sur un graphe

Cinq commandes, et la dernière est la réponse :```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"

Utilisez `kin setup --intent editor` pour le chemin VS Code. Confirmez la liste de contrôle de santé lisible par machine obtenue avec `kin setup status --json`.

L'installateur résout la [dernière version stable](https://github.com/firelock-ai/kin/releases/latest),
vérifie sa somme de contrôle SHA-256 publiée, installe les binaires gérés sous
`~/.kin`, puis lance la configuration. L'exécution de l'intention explicite `agent` configure le
serveur MCP intégré pour les clients pris en charge détectés. Utilisez `--intent local` pour une utilisation
en CLI et système de fichiers sans configuration MCP, ou `--intent editor` pour le chemin VS
Code.

Pour supprimer uniquement les intégrations gérées par la configuration, exécutez `kin setup uninstall`. Pour la
racine gérée par défaut (`~/.kin`), `kin setup uninstall --all` arrête également tous les
daemons Kin, supprime les blocs PATH exacts de l'ancien installateur et supprime récursivement l'installation
gérée (`--dry-run` en affiche un aperçu). Un `KIN_HOME` personnalisé n'est jamais supprimé
récursivement : exécutez d'abord la désinstallation limitée au registre, puis examinez et supprimez ce répertoire
explicitement. Les tranches modifiées appartenant à la configuration bloquent la suppression complète à moins d'ajouter
`--force`, de sorte que la désinstallation ne remplace jamais silencieusement une configuration client ou
shell modifiée par l'utilisateur. Sous Windows, la CLI planifie la suppression de son répertoire d'installation verrouillé
immédiatement après la sortie du processus en cours. Windows conserve intentionnellement
un fichier sidecar d'autorité frère inerte, limité à l'utilisateur actuel ; le maintien de cette identité de verrou
stable empêche un crash ou une future installation simultanée de créer deux autorités de mutation indépendantes.
La CLI et le résultat JSON divulguent ces métadonnées de coordination conservées plutôt que de prétendre à zéro octet résiduel.

Pour une installation manuelle, chaque archive et son fichier `.sha256` sont publiés sous
`https://github.com/firelock-ai/kin/releases/latest/download/`. Les noms d'actifs dynamiques
sont `kin-macos-aarch64`, `kin-macos-x86_64`, `kin-linux-aarch64`,
`kin-linux-x86_64` et `kin-windows-x86_64` ; utilisez le suffixe `.tar.gz` pour les
archives macOS et Linux et le suffixe `.zip` pour Windows, comme indiqué sur la
page de la dernière version. Le zip Windows est également ce que l'installateur PowerShell et
le lanceur npm récupèrent.

Le point d'entrée npm résout le même canal de publication public :```sh
npm install -g @kinlab/kin@latest

Un préfixe utilisateur se trouve sur le `PATH` de votre shell interactif et nulle part ailleurs. Les scripts, les étapes CI,
`docker exec` et les clients d’agent ne l’héritent pas, alors donnez-leur le chemin absolu vers le
binaire plutôt qu’un simple `kin`. Voir
[Fonctionne avec votre agent](#works-with-your-agent) pour la forme d’enregistrement.

Un tap Homebrew suit le même canal de publication :```sh
brew install firelock-ai/kin/kin

Dans un dépôt Git détecté, `kin init` admet de manière atomique l’intégralité de l’historique accessible, les références, les objets bruts, l’arbre de travail exact et la politique d’admission dans l’autorité de graphe repository-v6. Un espace de travail avec des modifications non validées, des changements indexés ou des fichiers non suivis est tout de même admis : `kin init` admet l’état validé et divulgue ce qu’il n’a pas admis. Il ne substitue jamais un instantané exact-HEAD ni une reconstruction sémantique du système de fichiers brut. Les URL de dépôt distant prises en charge, les refspecs, le suivi de branches et les valeurs par défaut de push sont scellés dans la configuration de coexistence Git de Kin ; les paramètres de transfert non sûrs, ambigus ou non pris en charge échouent en mode fermé avant la publication.

L’admission dérive également la couche d’entités et de relations sémantiques pour chaque fichier source d’entité pris en charge dans cet historique, et `kin init` rapporte les comptes durables liés à la génération qu’il a validés. `kin status` rapporte cette vue d’autorité du dépôt ; `kin graph status` rapporte séparément le graphe de requêtes vivant et mutable du démon, qui peut inclure un enrichissement dérivé ultérieurement. Les surfaces de requête consomment l’enrichissement détenu par le graphe lorsqu’il existe et signalent son absence au lieu de masquer l’écart derrière une recherche de fichiers bruts.

#### Quels fichiers deviennent des entités

« Fichier source d’entité pris en charge » désigne un fichier revendiqué par l’un des adaptateurs de langage de Kin. Le registre d’adaptateurs constitue l’ensemble complet, et chaque fichier d’un dépôt y est résolu :

| Langage | Extensions |
| --- | --- |
| 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` |

Un fichier d’en-tête `.h` est lu comme du C++ lorsque son contenu l’indique, afin qu’un projet C++ ne perde pas ses espaces de noms et ses modèles au profit de la grammaire C.

Tout le reste est admis comme contenu et reste interrogeable en tant qu’historique et texte, mais n’est pas analysé en entités et relations. Cela inclut Markdown, HTML et CSS, SQL, YAML, JSON et TOML, les scripts shell, Objective-C, Scala, Elixir, Dart, Lua, R, Zig, Haskell et Nix. Si votre langage figure sur cette liste, `locate` et `refs` n’y trouveront pas de symboles.

### 3. Poser une vraie question au graphe```sh
kin locate "where are webhook retries handled"
kin refs ExactEntityName
kin trace ExactEntityName
kin overview

Ce qui le distingue du fait de pointer un autre agent vers le serveur MCP, c'est que la règle est appliquée à l'intérieur de l'agent plutôt qu'empruntée à la couche d'autorisation d'un fournisseur. Il dispose des outils de Kin plus exactement deux outils locaux, `edit_file` et `write_file`. Il n'y a pas de shell, pas de grep et aucun outil de lecture de fichier, donc il ne peut pas répondre à une question sur le dépôt à partir d'une recherche brute de fichiers, et un outil qu'il invente est refusé par son nom. Lorsque Kin signale qu'un résultat vide ne peut pas être fiable, on dit à l'agent que la réponse est inconnue et on lui donne l'écart nommé au lieu de conclure que la chose n'existe pas. Chaque modification s'exécute dans une transaction Kin sous une session Kin, donc le changement porte une provenance nommant l'agent. Exécutez `kin agent doctor --base-url <url>` d'abord pour vérifier que les deux moitiés répondent. Voir [la référence CLI](https://github.com/firelock-ai/kin/blob/main/docs/cli-reference.md#kin-agent) pour la surface complète.

Travailler avec Claude Code, Codex, Cursor, Gemini et tout autre outil qui parle MCP reste de première classe. `kin setup --intent agent` configure chaque client qu'il détecte en une seule passe. Voici les commandes en une ligne par client lorsque vous préférez installer Kin directement.

Exécutez `kin init .` dans le dépôt avant de connecter un client, pas après. Ces outils répondent depuis le graphe, donc un client pointé vers un répertoire sans graphe obtient une surface d'outils sans rien derrière. `kin setup` le dit lui-même : son contrôle aller-retour signale « aucun dépôt Kin initialisé à ou au-dessus » du répertoire dans lequel il a été exécuté, et vous dit d'exécuter `kin init` là-bas et de relancer la configuration.

Claude Code, depuis l'intérieur d'une session :```
/plugin marketplace add firelock-ai/kin
/plugin install kin@kin

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

Kiro prend la même chose qu'un lien web :
[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 prend l'entrée standard ci-dessous plutôt qu'une commande sur une seule ligne. Son CLI lit
`~/.cline/mcp.json`. Dans l'extension VS Code, ouvrez le panneau MCP Servers, puis
l'onglet Configure, puis Configure MCP Servers, et ajoutez l'entrée à cet endroit.

Chaque autre client qui lit une configuration MCP standard prend cette entrée :```json
{
  "mcpServers": {
    "kin": { "command": "npx", "args": ["-y", "@kinlab/kin", "mcp", "start"] }
  }
}

Le résultat est `PASS`, `NEEDS ATTENTION` ou `WOULD BLOCK`, et il est accompagné de
l'impact Kin dérivé du graphe, du contexte nécessaire pour le réparer, et des
preuves derrière les deux. La paternité est déclarée, non vérifiée. La commande ne
bloquera pas votre fusion ni ne modifiera l'état du graphe. Elle remet les preuves à un humain ou à une
politique CI et s'arrête là.

## Comment Kin se rapporte à Git

À côté de Git aujourd'hui. Autorité du dépôt au fil du temps. Lors d'une adoption brownfield,
Git reste une frontière explicite d'interopérabilité import/export ; il ne répond
jamais aux requêtes d'exécution de Kin ni ne répare la vérité manquante du graphe.

- `kin init` importe l'historique Git complet atteignable et les arêtes parentes exactes.
  Kin n'a délibérément aucun mode d'initialisation à historique partiel ou uniquement par instantané.
- Après l'importation, le graphe de Kin possède l'identité du dépôt, l'état de l'arborescence, l'historique, les références,
  et les relations sémantiques. Les vues du système de fichiers et de Git sont des projections.
- `kin git export --output ../repo.git` écrit une nouvelle projection Git nue à partir d'une
  génération d'autorité détenue par le graphe. Il ne consulte pas les fichiers de travail ni un
  magasin d'objets `.git/` ambiant, et il refuse une destination existante ou située dans le dépôt.
  Les objets, références et répertoires sont vidés avant que la publication de destination sans remplacement ne soit
  reconnue. La publication ancrée par capacité est actuellement disponible sur les hôtes Unix ; les autres hôtes refusent avant
  de créer l'exportation.

Cela permet à une équipe de migrer un dépôt existant sans abandonner son éditeur,
compilateur, système de build ou interopérabilité Git pendant que Kin devient l'autorité.

## Plateforme et maturité

Le runtime principal et la projection du système de fichiers ont des limites de prise en charge
différentes :

| Plateforme | Runtime principal Kin | Projection `kin-vfs` |
| --- | --- | --- |
| macOS, Apple Silicon et Intel | Le graphe natif, les vecteurs, le démon, la configuration, MCP et les surfaces de revue sont inclus dans l'archive de publication. | Fourni et testé sur les deux architectures. Il utilise `DYLD_INSERT_LIBRARIES` ; les programmes protégés par SIP ou durcis peuvent rejeter l'injection. |
| Linux x86_64 et arm64 | `kin` et `kin-daemon` sont des builds statiques musl destinés à fonctionner sur les distributions glibc et musl. | L'exécutable VFS public et le shim sont des builds GNU/glibc, pas des builds musl. Ils sont compilés contre un plancher glibc épinglé de 2.31 et lient OpenSSL 3, donc un hôte de projection a besoin des deux ; Debian 12 les charge, et Alpine et les autres distributions musl ne sont pas des hôtes de projection pris en charge. La publication refuse de publier une archive Linux dont les binaires demandent plus de glibc que ce plancher. La preuve de publication arm64 s'exécute sur Ubuntu 24.04. |
| Windows x86_64 natif | Prise en charge précoce : les dépôts sont admis et les requêtes de graphe et lexicales répondent nativement, mais les flux de travail MCP et de revue ne sont pas encore couverts de bout en bout par la preuve d'installation. WSL2 reste le chemin recommandé pour Kin complet. | Non fourni. Utilisez WSL2 avec une distribution Linux qui respecte la limite glibc pour la projection. |

Le graphe est l'autorité dans chaque cas ci-dessus. Le shim, un montage NFS, un montage
FUSE et Windows ProjFS sont quatre façons de voir cette vérité comme des fichiers, et Kin
choisit entre eux en sondant ce que cet hôte peut exécuter : un montage là où un
est disponible, car le noyau le sert et aucun processus ne peut l'en dépouiller,
avec le shim injecté comme solution de repli de compatibilité sur macOS et Linux et
ProjFS en tête sur Windows, où aucun shim n'existe. `kin vfs on` engage celui choisi,
`kin vfs off` le désengage, et `kin doctor` porte une ligne indiquant lequel est
en vigueur et s'il fonctionne. Lorsqu'un mode manque, Kin imprime la
ligne exacte qui l'installe ou l'active pour votre plateforme.
[docs/projection.md](https://github.com/firelock-ai/kin/blob/main/docs/projection.md) contient le tableau complet par plateforme.

La première indexation lit tout l'historique Git atteignable, donc `kin init` sur un
dépôt volumineux ou de longue durée prend des minutes, pas des secondes, avant que l'intégration
ne commence. Après le retour de `init`, le démon continue la préparation en
arrière-plan, et les premiers appels d'agent sur un grand dépôt peuvent prendre
nettement plus de temps pour répondre.

Des tests arm64 limités ont trouvé le graphe principal et le chemin lexical utilisables à 512 Mo,
mais le téléchargement complet des intégrations nécessite un modèle d'environ 522 Mo et a actuellement besoin de 2 Go comme
plancher de fonctionnement sûr ; 1 Go est une limite dangereuse et 512 Mo peut se terminer pendant
l'intégration. Ce sont des contraintes alpha observées, pas des promesses de dimensionnement universelles.

Un `kin --version` réussi établit seulement que le binaire principal s'exécute. Il
n'établit pas la compatibilité VFS ni une projection vivante adossée au graphe. Sur un
hôte Unix pris en charge, utilisez `kin vfs status`, qui sonde chaque mode de projection et
imprime ce qui est réellement en vigueur, puis `kin setup status` et un vrai
lancement `kin-vfs exec --workspace . -- <commande>`. Le lanceur VFS inclut une
sentinelle d'interposition et signale lorsque le système d'exploitation retire le shim.
Le [README kin-vfs](https://github.com/firelock-ai/kin-vfs#current-platform-and-package-boundaries)
contient la limite complète.

Les artefacts de publication sont publiés avec sommes de contrôle et le flux de travail de publication exécute l'installation
anonyme, le démon/MCP, l'intégration et de véritables vérifications de projection VFS adossée au graphe
sur sa matrice de runners pris en charge. Le flux de travail lui-même est public :
[Preuve d'installation](https://github.com/firelock-ai/kin/actions/workflows/install-proof.yml).
Une publication verte établit ces artefacts et environnements exacts ; ce n'est pas une
affirmation que chaque distribution, outil ou forme de dépôt est déjà couvert.

## FAQ

### Kin remplace-t-il Git ?

À côté de Git aujourd'hui. Autorité du dépôt au fil du temps. Git reste une
frontière explicite d'interopérabilité import/export lors d'une adoption brownfield, donc une équipe
peut migrer un dépôt existant sans abandonner son éditeur, compilateur,
système de build ou interopérabilité Git.

### Mon code quitte-t-il ma machine ?

Kin conserve le travail du dépôt local dans votre environnement, donc l'ingestion du dépôt,
le stockage du graphe et les requêtes locales s'exécutent tous là-bas. KinLab est un produit
distinct qui ajoute une collaboration hébergée sous des accords explicites d'accès et d'accès anticipé.

### Avec quels agents fonctionne-t-il ?

Fonctionner avec Claude Code, Codex, Cursor, Gemini et tout ce qui parle MCP
reste une priorité. `kin setup --intent agent` configure chaque client qu'il détecte
en une seule passe.

### Bloque-t-il une fusion ?

La revue est consultative, donc elle signale le risque sans bloquer et la décision de fusion
reste à votre équipe. `kin review shadow` remet les preuves à un humain ou à une
politique CI et s'arrête là.

## Posture de preuve

Le package de preuve Go Multi-SWE-Bench préenregistré publié est épinglé à une
version plus ancienne, pas à la dernière publication mobile, et n'établit pas une large
affirmation de vitesse, d'économies de jetons ou de victoire par catégorie. Les résultats comparatifs sont retenus
ici en attendant une vérification indépendante.

Lisez la méthodologie, l'ensemble de tâches, l'identité de build et les artefacts dans le
[package de preuve public](https://firelock.ai/labs/kin-proof). Traitez les affirmations en dehors
de ce périmètre mesuré comme des hypothèses jusqu'à ce qu'elles aient leur propre preuve reproductible.

## Écrits

Les notes d'ingénierie de la construction de Kin, écrites pour qu'un étranger puisse les réutiliser,
vivent sur [kinlab.ai/blog](https://kinlab.ai/blog) avec un flux sur
[kinlab.ai/rss.xml](https://kinlab.ai/rss.xml).

- [La vérification qui a réussi parce qu'elle ne mesurait rien](https://kinlab.ai/blog/checks-that-cannot-fail)
- [Votre recherche de code dit que rien ne l'utilise. Pouvez-vous le supprimer ?](https://kinlab.ai/blog/empty-answer-safe-to-delete)

## Apprendre et contribuer

- [Démarrage rapide et configuration avancée](https://github.com/firelock-ai/kin/blob/main/docs/quickstart.md)
- [Taille du stockage et ce qui la détermine](https://github.com/firelock-ai/kin/blob/main/docs/store-size.md)
- [Référence des outils MCP](https://github.com/firelock-ai/kin/blob/main/docs/mcp-tools.md)
- [Prise en charge des langues et ce que chaque niveau extrait](https://github.com/firelock-ai/kin/blob/main/docs/language-support.md)
- [Référence des variables d'environnement](https://github.com/firelock-ai/kin/blob/main/docs/env-vars.md)
- [Thèse graphe d'abord](https://github.com/firelock-ai/kin/blob/main/docs/thesis.md)
- [Modèle d'autorité d'écriture et son état transitoire](https://github.com/firelock-ai/kin/blob/main/docs/write-authority-model.md)
- [Discussions GitHub](https://github.com/firelock-ai/kin/discussions)
- [Rapports de bogues et demandes de fonctionnalités](https://github.com/firelock-ai/kin/issues/new/choose)
- [Guide de contribution](https://github.com/firelock-ai/kin/blob/main/CONTRIBUTING.md)
- [Signalement de sécurité privé](https://github.com/firelock-ai/kin/blob/main/SECURITY.md)

## Licence

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

<p align="center"><em>Un logiciel qui se souvient de lui-même.</em></p>