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

Sob essas superfícies estão as camadas das quais o sistema é construído:

| Camada | Função |
| --- | --- |
| **[kin-db](https://github.com/firelock-ai/kin-db)** | Armazenamento de grafos, snapshots, indexação, pesquisa de texto e pesquisa vetorial. |
| **[kin-model](https://github.com/firelock-ai/kin-model)** | Tipos canônicos e modelos de domínio compartilhados em toda a stack. |
| **[kin-blobs](https://github.com/firelock-ai/kin-blobs)** | Armazenamento de blobs endereçável por conteúdo. |
| **[kin-search](https://github.com/firelock-ai/kin-search)** | Primitivas de pesquisa lexical e recuperação em etapas. |
| **[kin-vector](https://github.com/firelock-ai/kin-vector)** | Substrato de vetores e vizinhos mais próximos. |
| **[kin-infer](https://github.com/firelock-ai/kin-infer)** | Substrato de inferência e embeddings. |
| **[kin-lsp](https://github.com/firelock-ai/kin-lsp)** | Enriquecimento via language-server que alimenta a camada semântica. |

Estas são camadas de implementação de um único sistema, não produtos separados
que um novo usuário precisa montar. Nenhuma delas é instalada separadamente.

## Open source e o ecossistema Kin

O núcleo do Kin é open source sob 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),
e [kin-editor](https://github.com/firelock-ai/kin-editor), além das bibliotecas
de suporte kin-model, kin-blobs, kin-search, kin-vector, kin-infer, kin-lsp e
kin-actions.

O [KinLab](https://kinlab.ai) é um produto proprietário construído sobre esse núcleo
aberto: a camada hospedada de colaboração e control-plane descrita acima.

O mesmo limite se aplica a como o trabalho de benchmark é compartilhado. A
[especificação de benchmark e um verificador de bundle autônomo e sem dependências](https://github.com/firelock-ai/kin-bench-spec)
são públicos, para que uma alegação possa ser verificada sem acesso ao sistema que
a produziu. O runner e a infraestrutura de prova que geram bundles de evidência
selados (a orquestração, o portão de prova de release fixado e o ambiente de
medição hospedado) permanecem privados por enquanto. A spec e o verificador abrem
primeiro; o runner pode abrir depois.

## Caminho mais curto baseado em grafos

Cinco comandos, e o último é a resposta:```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"

Use `kin setup --intent editor` para o caminho do VS Code. Confirme a lista de verificação de saúde legível por máquina resultante com `kin setup status --json`.

O instalador resolve a [versão estável mais recente](https://github.com/firelock-ai/kin/releases/latest),
verifica sua soma de verificação SHA-256 publicada, instala os binários gerenciados em
`~/.kin` e inicia a configuração. Executar a intenção explícita `agent` configura o
servidor MCP integrado para os clientes suportados detectados. Use `--intent local` para uso
de CLI e sistema de arquivos sem configuração MCP, ou `--intent editor` para o caminho do VS
Code.

Para remover apenas as integrações gerenciadas pela configuração, execute `kin setup uninstall`. Para
a raiz gerenciada padrão (`~/.kin`), `kin setup uninstall --all` também interrompe todos os daemons
do Kin, remove blocos exatos de PATH de instaladores legados e exclui recursivamente a
instalação gerenciada (`--dry-run` fornece uma prévia). Um `KIN_HOME` personalizado nunca é removido
recursivamente: primeiro execute o uninstall com escopo de ledger e depois revise e remova esse diretório
explicitamente. Fatias modificadas de propriedade da configuração bloqueiam a remoção completa, a menos que você
adicione `--force`, então o uninstall nunca sobrescreve silenciosamente a configuração editada de cliente ou
shell de um usuário. No Windows, a CLI agenda a exclusão do seu diretório de instalação bloqueado
imediatamente após o processo em execução sair. O Windows retém intencionalmente
um sidecar de autoridade irmão inerte, apenas para o usuário atual; manter essa identidade de bloqueio
estável evita que uma falha ou uma instalação futura concorrente crie duas
autoridades de mutação independentes. A CLI e o resultado JSON divulgam esses metadados de coordenação
retidos em vez de alegar zero bytes residuais.

Para instalação manual, cada arquivo e seu arquivo `.sha256` são publicados em
`https://github.com/firelock-ai/kin/releases/latest/download/`. Os nomes de ativos dinâmicos
são `kin-macos-aarch64`, `kin-macos-x86_64`, `kin-linux-aarch64`,
`kin-linux-x86_64` e `kin-windows-x86_64`; use o sufixo `.tar.gz` para os
arquivos macOS e Linux e o sufixo `.zip` para Windows, conforme mostrado na
página da versão mais recente. O zip do Windows também é o que o instalador do PowerShell e
o launcher do npm buscam.

O ponto de entrada do npm resolve o mesmo canal de lançamento público:```sh
npm install -g @kinlab/kin@latest

Um prefixo de usuário está no `PATH` do seu shell interativo e em nenhum outro lugar. Scripts, etapas de CI,
`docker exec` e clientes de agente não o herdam, então forneça a esses o caminho absoluto para o
binário em vez de um `kin` simples. Consulte
[Funciona com o seu agente](#works-with-your-agent) para o formato de registro.

Um tap do Homebrew acompanha o mesmo canal de lançamento:```sh
brew install firelock-ai/kin/kin

Num repositório Git detetado, `kin init` admite atomicamente todo o histórico alcançável, refs, objetos brutos, a árvore de trabalho exata e a política de admissão na autoridade do grafo repository-v6. Um worktree com edições não confirmadas, alterações em staged ou ficheiros não rastreados ainda assim admite: `kin init` admite o estado confirmado e revela o que não admitiu. Nunca substitui por um snapshot exato de HEAD ou por uma reconstrução semântica do sistema de ficheiros bruto. URLs de repositório remoto suportados, refspecs, rastreio de ramos e predefinições de push são selados na configuração de coexistência Git do Kin; definições de transferência inseguras, ambíguas ou não suportadas falham de forma fechada antes da publicação.

A admissão também deriva a camada de entidades e relações semânticas para cada ficheiro de origem de entidade suportado nesse histórico, e `kin init` reporta as contagens duráveis, limitadas por geração, que confirmou. `kin status` reporta essa vista de autoridade do repositório; `kin graph status` reporta separadamente o grafo de consulta vivo e mutável do daemon, que pode incluir enriquecimento derivado posteriormente.
As superfícies de consulta consomem o enriquecimento detido pelo grafo quando existe e reportam a sua ausência em vez de esconder a lacuna atrás da pesquisa de ficheiros brutos.

#### Que ficheiros se tornam entidades

"Ficheiro de origem de entidade suportado" significa um ficheiro que um dos adaptadores de linguagem do Kin reivindica. O registo de adaptadores é o conjunto completo, e cada ficheiro num repositório resolve-se através dele:

| Linguagem | Extensões |
| --- | --- |
| 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` |

Um cabeçalho `.h` é lido como C++ quando o seu conteúdo assim o indica, para que um projeto C++ não perca namespaces e templates para a gramática C.

Tudo o resto é admitido como conteúdo e permanece consultável como histórico e texto, mas não é analisado em entidades e relações. Isso inclui Markdown, HTML e CSS, SQL, YAML, JSON e TOML, scripts de shell, Objective-C, Scala, Elixir, Dart, Lua, R, Zig, Haskell e Nix. Se a sua linguagem estiver nessa lista, `locate` e `refs` não encontrarão símbolos nela.

### 3. Faça uma pergunta real ao grafo```sh
kin locate "where are webhook retries handled"
kin refs ExactEntityName
kin trace ExactEntityName
kin overview

O que o diferencia de apontar outro agente para o servidor MCP é que a
regra é aplicada dentro do agente, em vez de ser emprestada da camada de
permissões de um fornecedor. Ele tem as ferramentas da Kin mais exatamente duas
locais, `edit_file` e `write_file`. Não há shell, nem grep e nenhuma ferramenta
de leitura de arquivos, então ele não consegue responder a uma pergunta sobre o
repositório a partir de uma busca bruta de arquivos, e uma ferramenta que ele
inventa é recusada pelo nome. Quando a Kin relata que um resultado vazio não
pode ser confiável, o agente recebe a informação de que a resposta é
desconhecida e recebe a lacuna nomeada em vez de concluir que a coisa não
existe. Cada edição é executada dentro de uma transação da Kin sob uma sessão da
Kin, então a alteração carrega proveniência nomeando o agente. Execute `kin agent doctor
--base-url <url>` primeiro para verificar se ambas as metades respondem. Consulte
[a referência da CLI](https://github.com/firelock-ai/kin/blob/main/docs/cli-reference.md#kin-agent) para a superfície completa.

Trabalhar com Claude Code, Codex, Cursor, Gemini e qualquer outra coisa que fale MCP
continua sendo prioridade. `kin setup --intent agent` configura cada cliente que
detecta em uma única passagem. Estes são os one-liners por cliente para quando
você preferir instalar a Kin diretamente.

Execute `kin init .` no repositório antes de conectar um cliente, não depois.
Essas ferramentas respondem a partir do grafo, então um cliente apontado para um
diretório sem grafo obtém uma superfície de ferramentas sem nada por trás dela.
O próprio `kin setup` diz isso: sua verificação de ida e volta relata "nenhum
repositório Kin inicializado em ou acima" do diretório em que foi executado e
informa para você executar `kin init` lá e executar o setup novamente.

Claude Code, de dentro de uma sessão:```
/plugin marketplace add firelock-ai/kin
/plugin install kin@kin

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

Kiro aceita o mesmo formato de link web:
[Adicionar Kin ao 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).

O Cline aceita a entrada padrão abaixo em vez de um comando de uma linha. Sua CLI lê
`~/.cline/mcp.json`. Na extensão do VS Code, abra o painel MCP Servers, depois
a aba Configure, depois Configure MCP Servers, e adicione a entrada lá.

Qualquer outro cliente que leia uma configuração MCP padrão aceita esta entrada:```json
{
  "mcpServers": {
    "kin": { "command": "npx", "args": ["-y", "@kinlab/kin", "mcp", "start"] }
  }
}

O resultado é `PASS`, `NEEDS ATTENTION` ou `WOULD BLOCK`, e vem acompanhado do
impacto Kin derivado do grafo, do contexto necessário para repará-lo e das
evidências por trás de ambos. A autoria é declarada, não verificada. O comando
não bloqueará seu merge nem alterará o estado do grafo. Ele entrega as
evidências a um humano ou a uma política de CI e para por aí.

## Como o Kin se relaciona com o Git

Ao lado do Git hoje. Autoridade do repositório ao longo do tempo. Durante a
adoção brownfield, o Git permanece como uma fronteira explícita de
interoperabilidade de importação/exportação; ele nunca responde a consultas de
runtime do Kin nem repara a verdade ausente do grafo.

- `kin init` importa todo o histórico Git alcançável e as arestas exatas de
  pais. O Kin deliberadamente não possui modo de inicialização com histórico
  parcial ou somente snapshot.
- Após a importação, o grafo do Kin é dono da identidade do repositório, do
  estado da árvore, do histórico, das refs e das relações semânticas. As visões
  de filesystem e Git são projeções.
- `kin git export --output ../repo.git` grava uma nova projeção Git bare a
  partir de uma geração de autoridade de propriedade do grafo. Ele não consulta
  arquivos de trabalho nem um armazenamento de objetos `.git/` ambiente, e
  recusa um destino existente ou dentro do repositório. Objetos, refs e
  diretórios são liberados antes que a publicação no destino sem substituição
  seja reconhecida. A publicação ancorada em capabilities está disponível
  atualmente em hosts Unix; outros hosts recusam antes de criar a exportação.

Isso permite que uma equipe migre um repositório existente sem abrir mão de seu
editor, compilador, sistema de build ou interoperabilidade com o Git enquanto o
Kin se torna autoritativo.

## Plataforma e maturidade

O runtime principal e a projeção de filesystem têm limites de suporte
diferentes:

| Plataforma | Runtime principal do Kin | Projeção `kin-vfs` |
| --- | --- | --- |
| macOS, Apple Silicon e Intel | Grafo nativo, vetor, daemon, setup, MCP e superfícies de review são enviados no arquivo de release. | Enviado e exercitado em ambas as arquiteturas. Usa `DYLD_INSERT_LIBRARIES`; programas protegidos por SIP ou endurecidos podem rejeitar a injeção. |
| Linux x86_64 e arm64 | `kin` e `kin-daemon` são builds estáticos musl destinados a rodar em distribuições glibc e musl. | O executável público de VFS e o shim são builds GNU/glibc, não builds musl. Eles são compilados contra um piso glibc fixado em 2.31 e vinculam OpenSSL 3, então um host de projeção precisa de ambos; Debian 12 os carrega, e Alpine e outras distribuições musl não são hosts de projeção suportados. O release recusa publicar um arquivo Linux cujos binários peçam mais glibc do que esse piso. A prova do release arm64 roda no Ubuntu 24.04. |
| Windows nativo x86_64 | Suporte inicial: repositórios são admitidos e consultas de grafo e léxicas respondem nativamente, mas fluxos de trabalho MCP e de review ainda não são cobertos de ponta a ponta pela prova de instalação. WSL2 continua sendo o caminho recomendado para o Kin completo. | Não enviado. Use WSL2 com uma distribuição Linux que atenda ao limite glibc para projeção. |

O grafo é a autoridade em todos os casos acima. O shim, um mount NFS, um mount
FUSE e o Windows ProjFS são quatro maneiras de ver essa verdade como arquivos,
e o Kin escolhe entre eles sondando o que este host pode executar: um mount
onde um está disponível, porque o kernel o serve e nenhum processo pode tê-lo
removido, com o shim injetado como fallback de compatibilidade no macOS e Linux
e o ProjFS liderando no Windows, onde não existe shim. `kin vfs on` ativa o
escolhido, `kin vfs off` o desativa, e `kin doctor` carrega uma linha dizendo
qual está em vigor e se está funcionando. Onde um modo está ausente, o Kin
imprime a linha exata que o instala ou habilita para sua plataforma.
[docs/projection.md](https://github.com/firelock-ai/kin/blob/main/docs/projection.md) tem a tabela completa por plataforma.

A primeira indexação lê todo o histórico Git alcançável, então `kin init` em um
repositório grande ou de longa duração leva minutos, não segundos, antes que o
embedding comece. Após o `init` retornar, o daemon continua se preparando em
segundo plano, e as primeiras chamadas de agente em um repositório grande podem
levar visivelmente mais tempo para responder.

Testes limitados em arm64 descobriram que o grafo principal e o caminho léxico
são utilizáveis em 512 MB, mas o download completo de embedding traz um modelo
de aproximadamente 522 MB e atualmente precisa de 2 GB como piso operacional
seguro; 1 GB é uma borda insegura e 512 MB pode encerrar durante o embedding.
Estas são restrições observadas de alpha, não promessas universais de tamanho.

Um `kin --version` bem-sucedido estabelece apenas que o binário principal roda.
Ele não estabelece compatibilidade de VFS nem uma projeção viva apoiada no
grafo. Em um host Unix suportado, use `kin vfs status`, que sonda cada modo de
projeção e imprime o que está realmente em vigor, depois `kin setup status` e
um lançamento real de `kin-vfs exec --workspace . -- <command>`. O launcher de
VFS inclui um canário de interposição e relata quando o sistema operacional
remove o shim. O [README do kin-vfs](https://github.com/firelock-ai/kin-vfs#current-platform-and-package-boundaries)
contém o limite completo.

Os artefatos de release são publicados com checksums e o fluxo de trabalho de
release executa instalação anônima, daemon/MCP, embedding e verificações reais
de projeção VFS apoiada no grafo em toda a sua matriz de runners suportados. O
próprio fluxo de trabalho é público:
[Install Proof](https://github.com/firelock-ai/kin/actions/workflows/install-proof.yml).
Um release verde estabelece exatamente esses artefatos e ambientes; não é uma
afirmação de que toda distribuição, ferramenta ou formato de repositório já
está coberto.

## FAQ

### O Kin substitui o Git?

Ao lado do Git hoje. Autoridade do repositório ao longo do tempo. O Git
permanece como uma fronteira explícita de interoperabilidade de
importação/exportação durante a adoção brownfield, então uma equipe pode migrar
um repositório existente sem abrir mão de seu editor, compilador, sistema de
build ou interoperabilidade com o Git.

### Meu código sai da minha máquina?

O Kin mantém o trabalho local do repositório no seu ambiente, então ingestão de
repositório, armazenamento de grafo e consultas locais rodam todos lá. O KinLab
é um produto separado que adiciona colaboração hospedada sob acordos explícitos
de acesso e acesso antecipado.

### Com quais agentes ele funciona?

Funcionar com Claude Code, Codex, Cursor, Gemini e qualquer outra coisa que fale
MCP continua sendo prioridade. `kin setup --intent agent` configura cada cliente
que detecta em uma única passada.

### Ele bloqueia um merge?

O review é consultivo, então sinaliza risco sem bloquear e a decisão de merge
permanece com sua equipe. `kin review shadow` entrega evidências a um humano ou
a uma política de CI e para por aí.

## Postura de prova

O pacote de prova publicado e pré-registrado Multi-SWE-Bench Go está fixado em
um build mais antigo, não no release mais recente em movimento, e não estabelece
uma afirmação ampla de velocidade, economia de tokens ou vitória por categoria.
Resultados comparativos são retidos aqui até verificação independente.

Leia a metodologia, o conjunto de tarefas, a identidade do build e os artefatos
no [pacote de prova público](https://firelock.ai/labs/kin-proof). Trate
afirmações fora desse escopo medido como hipóteses até que tenham sua própria
prova reproduzível.

## Escrita

Notas de engenharia da construção do Kin, escritas para que um estranho possa
reutilizá-las, vivem em [kinlab.ai/blog](https://kinlab.ai/blog) com um feed em
[kinlab.ai/rss.xml](https://kinlab.ai/rss.xml).

- [O check que passou porque não media nada](https://kinlab.ai/blog/checks-that-cannot-fail)
- [Sua busca de código diz que nada o usa. Você pode deletá-lo?](https://kinlab.ai/blog/empty-answer-safe-to-delete)

## Aprenda e contribua

- [Quickstart e configuração avançada](https://github.com/firelock-ai/kin/blob/main/docs/quickstart.md)
- [Tamanho do store e o que o impulsiona](https://github.com/firelock-ai/kin/blob/main/docs/store-size.md)
- [Referência de ferramentas MCP](https://github.com/firelock-ai/kin/blob/main/docs/mcp-tools.md)
- [Suporte a idiomas e o que cada camada extrai](https://github.com/firelock-ai/kin/blob/main/docs/language-support.md)
- [Referência de variáveis de ambiente](https://github.com/firelock-ai/kin/blob/main/docs/env-vars.md)
- [Tese graph-first](https://github.com/firelock-ai/kin/blob/main/docs/thesis.md)
- [Modelo de autoridade de escrita e seu estado transicional](https://github.com/firelock-ai/kin/blob/main/docs/write-authority-model.md)
- [GitHub Discussions](https://github.com/firelock-ai/kin/discussions)
- [Relatórios de bugs e solicitações de recursos](https://github.com/firelock-ai/kin/issues/new/choose)
- [Guia de contribuição](https://github.com/firelock-ai/kin/blob/main/CONTRIBUTING.md)
- [Relato privado de segurança](https://github.com/firelock-ai/kin/blob/main/SECURITY.md)

## Licença

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

<p align="center"><em>Software que se lembra de si mesmo.</em></p>